gcc/fortran/intrinsic.texi

   1 @ignore
   2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
   3 Free Software Foundation, Inc.
   4 This is part of the GNU Fortran manual.
   5 For copying conditions, see the file gfortran.texi.
   6
   7 Permission is granted to copy, distribute and/or modify this document
   8 under the terms of the GNU Free Documentation License, Version 1.3 or
   9 any later version published by the Free Software Foundation; with the
  10 Invariant Sections being ``Funding Free Software'', the Front-Cover
  11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
  12 (see below).  A copy of the license is included in the gfdl(7) man page.
  13
  14
  15 Some basic guidelines for editing this document:
  16
  17   (1) The intrinsic procedures are to be listed in alphabetical order.
  18   (2) The generic name is to be used.
  19   (3) The specific names are included in the function index and in a
  20       table at the end of the node (See ABS entry).
  21   (4) Try to maintain the same style for each entry.
  22
  23
  24 @end ignore
  25
  26 @tex
  27 \gdef\acos{\mathop{\rm acos}\nolimits}
  28 \gdef\asin{\mathop{\rm asin}\nolimits}
  29 \gdef\atan{\mathop{\rm atan}\nolimits}
  30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
  31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
  32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
  33 @end tex
  34
  35
  36 @node Intrinsic Procedures
  37 @chapter Intrinsic Procedures
  38 @cindex intrinsic procedures
  39
  40 @menu
  41 * Introduction:         Introduction to Intrinsics
  42 * @code{ABORT}:         ABORT,     Abort the program
  43 * @code{ABS}:           ABS,       Absolute value
  44 * @code{ACCESS}:        ACCESS,    Checks file access modes
  45 * @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
  46 * @code{ACOS}:          ACOS,      Arccosine function
  47 * @code{ACOSH}:         ACOSH,     Inverse hyperbolic cosine function
  48 * @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
  49 * @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
  50 * @code{AIMAG}:         AIMAG,     Imaginary part of complex number
  51 * @code{AINT}:          AINT,      Truncate to a whole number
  52 * @code{ALARM}:         ALARM,     Set an alarm clock
  53 * @code{ALL}:           ALL,       Determine if all values are true
  54 * @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
  55 * @code{AND}:           AND,       Bitwise logical AND
  56 * @code{ANINT}:         ANINT,     Nearest whole number
  57 * @code{ANY}:           ANY,       Determine if any values are true
  58 * @code{ASIN}:          ASIN,      Arcsine function
  59 * @code{ASINH}:         ASINH,     Inverse hyperbolic sine function
  60 * @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
  61 * @code{ATAN}:          ATAN,      Arctangent function
  62 * @code{ATAN2}:         ATAN2,     Arctangent function
  63 * @code{ATANH}:         ATANH,     Inverse hyperbolic tangent function
  64 * @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
  65 * @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
  66 * @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
  67 * @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
  68 * @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
  69 * @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
  70 * @code{BGE}:           BGE,       Bitwise greater than or equal to
  71 * @code{BGT}:           BGT,       Bitwise greater than
  72 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
  73 * @code{BLE}:           BLE,       Bitwise less than or equal to
  74 * @code{BLT}:           BLT,       Bitwise less than
  75 * @code{BTEST}:         BTEST,     Bit test function
  76 * @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
  77 * @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
  78 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
  79 * @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
  80 * @code{C_LOC}:         C_LOC,     Obtain the C address of an object
  81 * @code{C_SIZEOF}:      C_SIZEOF,  Size in bytes of an expression
  82 * @code{CEILING}:       CEILING,   Integer ceiling function
  83 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
  84 * @code{CHDIR}:         CHDIR,     Change working directory
  85 * @code{CHMOD}:         CHMOD,     Change access permissions of files
  86 * @code{CMPLX}:         CMPLX,     Complex conversion function
  87 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
  88 * @code{COMPLEX}:       COMPLEX,   Complex conversion function
  89 * @code{CONJG}:         CONJG,     Complex conjugate function
  90 * @code{COS}:           COS,       Cosine function
  91 * @code{COSH}:          COSH,      Hyperbolic cosine function
  92 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
  93 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
  94 * @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
  95 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
  96 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
  97 * @code{DBLE}:          DBLE,      Double precision conversion function
  98 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
  99 * @code{DIGITS}:        DIGITS,    Significant digits function
 100 * @code{DIM}:           DIM,       Positive difference
 101 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
 102 * @code{DPROD}:         DPROD,     Double product function
 103 * @code{DREAL}:         DREAL,     Double real part function
 104 * @code{DSHIFTL}:       DSHIFTL,   Combined left shift
 105 * @code{DSHIFTR}:       DSHIFTR,   Combined right shift
 106 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
 107 * @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
 108 * @code{EPSILON}:       EPSILON,   Epsilon function
 109 * @code{ERF}:           ERF,       Error function
 110 * @code{ERFC}:          ERFC,      Complementary error function
 111 * @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
 112 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
 113 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
 114 * @code{EXIT}:          EXIT,      Exit the program with status.
 115 * @code{EXP}:           EXP,       Exponential function
 116 * @code{EXPONENT}:      EXPONENT,  Exponent function
 117 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF,  Query dynamic type for extension
 118 * @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
 119 * @code{FGET}:          FGET,      Read a single character in stream mode from stdin
 120 * @code{FGETC}:         FGETC,     Read a single character in stream mode
 121 * @code{FLOOR}:         FLOOR,     Integer floor function
 122 * @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
 123 * @code{FNUM}:          FNUM,      File number function
 124 * @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
 125 * @code{FPUTC}:         FPUTC,     Write a single character in stream mode
 126 * @code{FRACTION}:      FRACTION,  Fractional part of the model representation
 127 * @code{FREE}:          FREE,      Memory de-allocation subroutine
 128 * @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
 129 * @code{FSTAT}:         FSTAT,     Get file status
 130 * @code{FTELL}:         FTELL,     Current stream position
 131 * @code{GAMMA}:         GAMMA,     Gamma function
 132 * @code{GERROR}:        GERROR,    Get last system error message
 133 * @code{GETARG}:        GETARG,    Get command line arguments
 134 * @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
 135 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
 136 * @code{GETCWD}:        GETCWD,    Get current working directory
 137 * @code{GETENV}:        GETENV,    Get an environmental variable
 138 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
 139 * @code{GETGID}:        GETGID,    Group ID function
 140 * @code{GETLOG}:        GETLOG,    Get login name
 141 * @code{GETPID}:        GETPID,    Process ID function
 142 * @code{GETUID}:        GETUID,    User ID function
 143 * @code{GMTIME}:        GMTIME,    Convert time to GMT info
 144 * @code{HOSTNM}:        HOSTNM,    Get system host name
 145 * @code{HUGE}:          HUGE,      Largest number of a kind
 146 * @code{HYPOT}:         HYPOT,     Euclidean distance function
 147 * @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
 148 * @code{IALL}:          IALL,      Bitwise AND of array elements
 149 * @code{IAND}:          IAND,      Bitwise logical and
 150 * @code{IANY}:          IANY,      Bitwise OR of array elements
 151 * @code{IARGC}:         IARGC,     Get the number of command line arguments
 152 * @code{IBCLR}:         IBCLR,     Clear bit
 153 * @code{IBITS}:         IBITS,     Bit extraction
 154 * @code{IBSET}:         IBSET,     Set bit
 155 * @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
 156 * @code{IDATE}:         IDATE,     Current local time (day/month/year)
 157 * @code{IEOR}:          IEOR,      Bitwise logical exclusive or
 158 * @code{IERRNO}:        IERRNO,    Function to get the last system error number
 159 * @code{IMAGE_INDEX}:   IMAGE_INDEX, Cosubscript to image index conversion
 160 * @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
 161 * @code{INT}:           INT,       Convert to integer type
 162 * @code{INT2}:          INT2,      Convert to 16-bit integer type
 163 * @code{INT8}:          INT8,      Convert to 64-bit integer type
 164 * @code{IOR}:           IOR,       Bitwise logical or
 165 * @code{IPARITY}:       IPARITY,   Bitwise XOR of array elements
 166 * @code{IRAND}:         IRAND,     Integer pseudo-random number
 167 * @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
 168 * @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
 169 * @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
 170 * @code{ISHFT}:         ISHFT,     Shift bits
 171 * @code{ISHFTC}:        ISHFTC,    Shift bits circularly
 172 * @code{ISNAN}:         ISNAN,     Tests for a NaN
 173 * @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
 174 * @code{KILL}:          KILL,      Send a signal to a process
 175 * @code{KIND}:          KIND,      Kind of an entity
 176 * @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
 177 * @code{LCOBOUND}:      LCOBOUND,  Lower codimension bounds of an array
 178 * @code{LEADZ}:         LEADZ,     Number of leading zero bits of an integer
 179 * @code{LEN}:           LEN,       Length of a character entity
 180 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
 181 * @code{LGE}:           LGE,       Lexical greater than or equal
 182 * @code{LGT}:           LGT,       Lexical greater than
 183 * @code{LINK}:          LINK,      Create a hard link
 184 * @code{LLE}:           LLE,       Lexical less than or equal
 185 * @code{LLT}:           LLT,       Lexical less than
 186 * @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
 187 * @code{LOC}:           LOC,       Returns the address of a variable
 188 * @code{LOG}:           LOG,       Logarithm function
 189 * @code{LOG10}:         LOG10,     Base 10 logarithm function
 190 * @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
 191 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
 192 * @code{LONG}:          LONG,      Convert to integer type
 193 * @code{LSHIFT}:        LSHIFT,    Left shift bits
 194 * @code{LSTAT}:         LSTAT,     Get file status
 195 * @code{LTIME}:         LTIME,     Convert time to local time info
 196 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
 197 * @code{MASKL}:         MASKL,     Left justified mask
 198 * @code{MASKR}:         MASKR,     Right justified mask
 199 * @code{MATMUL}:        MATMUL,    matrix multiplication
 200 * @code{MAX}:           MAX,       Maximum value of an argument list
 201 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
 202 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
 203 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
 204 * @code{MCLOCK}:        MCLOCK,    Time function
 205 * @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
 206 * @code{MERGE}:         MERGE,     Merge arrays
 207 * @code{MERGE_BITS}:    MERGE_BITS, Merge of bits under mask
 208 * @code{MIN}:           MIN,       Minimum value of an argument list
 209 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
 210 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
 211 * @code{MINVAL}:        MINVAL,    Minimum value of an array
 212 * @code{MOD}:           MOD,       Remainder function
 213 * @code{MODULO}:        MODULO,    Modulo function
 214 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
 215 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
 216 * @code{NEAREST}:       NEAREST,   Nearest representable number
 217 * @code{NEW_LINE}:      NEW_LINE,  New line character
 218 * @code{NINT}:          NINT,      Nearest whole number
 219 * @code{NORM2}:         NORM2,     Euclidean vector norm
 220 * @code{NOT}:           NOT,       Logical negation
 221 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
 222 * @code{NUM_IMAGES}:    NUM_IMAGES, Number of images
 223 * @code{OR}:            OR,        Bitwise logical OR
 224 * @code{PACK}:          PACK,      Pack an array into an array of rank one
 225 * @code{PARITY}:        PARITY,    Reduction with exclusive OR
 226 * @code{PERROR}:        PERROR,    Print system error message
 227 * @code{POPCNT}:        POPCNT,    Number of bits set
 228 * @code{POPPAR}:        POPPAR,    Parity of the number of bits set
 229 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
 230 * @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
 231 * @code{PRODUCT}:       PRODUCT,   Product of array elements
 232 * @code{RADIX}:         RADIX,     Base of a data model
 233 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
 234 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
 235 * @code{RAND}:          RAND,      Real pseudo-random number
 236 * @code{RANGE}:         RANGE,     Decimal exponent range
 237 * @code{RAN}:           RAN,       Real pseudo-random number
 238 * @code{REAL}:          REAL,      Convert to real type
 239 * @code{RENAME}:        RENAME,    Rename a file
 240 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
 241 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
 242 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
 243 * @code{RSHIFT}:        RSHIFT,    Right shift bits
 244 * @code{SAME_TYPE_AS}:  SAME_TYPE_AS,  Query dynamic types for equality
 245 * @code{SCALE}:         SCALE,     Scale a real value
 246 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
 247 * @code{SECNDS}:        SECNDS,    Time function
 248 * @code{SECOND}:        SECOND,    CPU time function
 249 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
 250 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
 251 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
 252 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
 253 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
 254 * @code{SHIFTA}:        SHIFTA,    Right shift with fill
 255 * @code{SHIFTL}:        SHIFTL,    Left shift
 256 * @code{SHIFTR}:        SHIFTR,    Right shift
 257 * @code{SIGN}:          SIGN,      Sign copying function
 258 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
 259 * @code{SIN}:           SIN,       Sine function
 260 * @code{SINH}:          SINH,      Hyperbolic sine function
 261 * @code{SIZE}:          SIZE,      Function to determine the size of an array
 262 * @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
 263 * @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
 264 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
 265 * @code{SPREAD}:        SPREAD,    Add a dimension to an array
 266 * @code{SQRT}:          SQRT,      Square-root function
 267 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
 268 * @code{STAT}:          STAT,      Get file status
 269 * @code{STORAGE_SIZE}:  STORAGE_SIZE, Storage size in bits
 270 * @code{SUM}:           SUM,       Sum of array elements
 271 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
 272 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
 273 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
 274 * @code{TAN}:           TAN,       Tangent function
 275 * @code{TANH}:          TANH,      Hyperbolic tangent function
 276 * @code{THIS_IMAGE}:    THIS_IMAGE, Cosubscript index of this image
 277 * @code{TIME}:          TIME,      Time function
 278 * @code{TIME8}:         TIME8,     Time function (64-bit)
 279 * @code{TINY}:          TINY,      Smallest positive number of a real kind
 280 * @code{TRAILZ}:        TRAILZ,    Number of trailing zero bits of an integer
 281 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
 282 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
 283 * @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
 284 * @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
 285 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
 286 * @code{UCOBOUND}:      UCOBOUND,  Upper codimension bounds of an array
 287 * @code{UMASK}:         UMASK,     Set the file creation mask
 288 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
 289 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
 290 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
 291 * @code{XOR}:           XOR,       Bitwise logical exclusive or
 292 @end menu
 293
 294 @node Introduction to Intrinsics
 295 @section Introduction to intrinsic procedures
 296
 297 The intrinsic procedures provided by GNU Fortran include all of the
 298 intrinsic procedures required by the Fortran 95 standard, a set of
 299 intrinsic procedures for backwards compatibility with G77, and a
 300 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
 301 standards.  Any conflict between a description here and a description in
 302 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
 303 2008 standard is unintentional, and the standard(s) should be considered
 304 authoritative.
 305
 306 The enumeration of the @code{KIND} type parameter is processor defined in
 307 the Fortran 95 standard.  GNU Fortran defines the default integer type and
 308 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 309 respectively.  The standard mandates that both data types shall have
 310 another kind, which have more precision.  On typical target architectures
 311 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 312 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 313 In the description of generic intrinsic procedures, the kind type parameter
 314 will be specified by @code{KIND=*}, and in the description of specific
 315 names for an intrinsic procedure the kind type parameter will be explicitly
 316 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
 317 brevity the optional @code{KIND=} syntax will be omitted.
 318
 319 Many of the intrinsic procedures take one or more optional arguments.
 320 This document follows the convention used in the Fortran 95 standard,
 321 and denotes such arguments by square brackets.
 322
 323 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
 324 which can be used to restrict the set of intrinsic procedures to a
 325 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
 326 option, and so all intrinsic procedures described here are accepted.  There
 327 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 328 implemented both a function and a subroutine.  Both classes
 329 have been implemented in @command{gfortran} for backwards compatibility
 330 with @command{g77}.  It is noted here that these functions and subroutines
 331 cannot be intermixed in a given subprogram.  In the descriptions that follow,
 332 the applicable standard for each intrinsic procedure is noted.
 333
 334
 335
 336 @node ABORT
 337 @section @code{ABORT} --- Abort the program
 338 @fnindex ABORT
 339 @cindex program termination, with core dump
 340 @cindex terminate program, with core dump
 341 @cindex core, dump
 342
 343 @table @asis
 344 @item @emph{Description}:
 345 @code{ABORT} causes immediate termination of the program.  On operating
 346 systems that support a core dump, @code{ABORT} will produce a core dump even if
 347 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
 348 purposes.
 349 @c TODO: Check if this (with -fno-dump-core) is correct.
 350
 351 @item @emph{Standard}:
 352 GNU extension
 353
 354 @item @emph{Class}:
 355 Subroutine
 356
 357 @item @emph{Syntax}:
 358 @code{CALL ABORT}
 359
 360 @item @emph{Return value}:
 361 Does not return.
 362
 363 @item @emph{Example}:
 364 @smallexample
 365 program test_abort
 366   integer :: i = 1, j = 2
 367   if (i /= j) call abort
 368 end program test_abort
 369 @end smallexample
 370
 371 @item @emph{See also}:
 372 @ref{EXIT}, @ref{KILL}
 373
 374 @end table
 375
 376
 377
 378 @node ABS
 379 @section @code{ABS} --- Absolute value
 380 @fnindex ABS
 381 @fnindex CABS
 382 @fnindex DABS
 383 @fnindex IABS
 384 @fnindex ZABS
 385 @fnindex CDABS
 386 @cindex absolute value
 387
 388 @table @asis
 389 @item @emph{Description}:
 390 @code{ABS(A)} computes the absolute value of @code{A}.
 391
 392 @item @emph{Standard}:
 393 Fortran 77 and later, has overloads that are GNU extensions
 394
 395 @item @emph{Class}:
 396 Elemental function
 397
 398 @item @emph{Syntax}:
 399 @code{RESULT = ABS(A)}
 400
 401 @item @emph{Arguments}:
 402 @multitable @columnfractions .15 .70
 403 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
 404 @code{REAL}, or @code{COMPLEX}.
 405 @end multitable
 406
 407 @item @emph{Return value}:
 408 The return value is of the same type and
 409 kind as the argument except the return value is @code{REAL} for a
 410 @code{COMPLEX} argument.
 411
 412 @item @emph{Example}:
 413 @smallexample
 414 program test_abs
 415   integer :: i = -1
 416   real :: x = -1.e0
 417   complex :: z = (-1.e0,0.e0)
 418   i = abs(i)
 419   x = abs(x)
 420   x = abs(z)
 421 end program test_abs
 422 @end smallexample
 423
 424 @item @emph{Specific names}:
 425 @multitable @columnfractions .20 .20 .20 .25
 426 @item Name            @tab Argument            @tab Return type       @tab Standard
 427 @item @code{ABS(A)}   @tab @code{REAL(4) A}    @tab @code{REAL(4)}    @tab Fortran 77 and later
 428 @item @code{CABS(A)}  @tab @code{COMPLEX(4) A} @tab @code{REAL(4)}    @tab Fortran 77 and later
 429 @item @code{DABS(A)}  @tab @code{REAL(8) A}    @tab @code{REAL(8)}    @tab Fortran 77 and later
 430 @item @code{IABS(A)}  @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
 431 @item @code{ZABS(A)}  @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
 432 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
 433 @end multitable
 434 @end table
 435
 436
 437
 438 @node ACCESS
 439 @section @code{ACCESS} --- Checks file access modes
 440 @fnindex ACCESS
 441 @cindex file system, access mode
 442
 443 @table @asis
 444 @item @emph{Description}:
 445 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
 446 exists, is readable, writable or executable. Except for the
 447 executable check, @code{ACCESS} can be replaced by
 448 Fortran 95's @code{INQUIRE}.
 449
 450 @item @emph{Standard}:
 451 GNU extension
 452
 453 @item @emph{Class}:
 454 Inquiry function
 455
 456 @item @emph{Syntax}:
 457 @code{RESULT = ACCESS(NAME, MODE)}
 458
 459 @item @emph{Arguments}:
 460 @multitable @columnfractions .15 .70
 461 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
 462 file name. Tailing blank are ignored unless the character @code{achar(0)}
 463 is present, then all characters up to and excluding @code{achar(0)} are
 464 used as file name.
 465 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
 466 file access mode, may be any concatenation of @code{"r"} (readable),
 467 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
 468 for existence.
 469 @end multitable
 470
 471 @item @emph{Return value}:
 472 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
 473 accessible in the given mode; otherwise or if an invalid argument
 474 has been given for @code{MODE} the value @code{1} is returned.
 475
 476 @item @emph{Example}:
 477 @smallexample
 478 program access_test
 479   implicit none
 480   character(len=*), parameter :: file  = 'test.dat'
 481   character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
 482   if(access(file,' ') == 0) print *, trim(file),' is exists'
 483   if(access(file,'r') == 0) print *, trim(file),' is readable'
 484   if(access(file,'w') == 0) print *, trim(file),' is writable'
 485   if(access(file,'x') == 0) print *, trim(file),' is executable'
 486   if(access(file2,'rwx') == 0) &
 487     print *, trim(file2),' is readable, writable and executable'
 488 end program access_test
 489 @end smallexample
 490 @item @emph{Specific names}:
 491 @item @emph{See also}:
 492
 493 @end table
 494
 495
 496
 497 @node ACHAR
 498 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
 499 @fnindex ACHAR
 500 @cindex @acronym{ASCII} collating sequence
 501 @cindex collating sequence, @acronym{ASCII}
 502
 503 @table @asis
 504 @item @emph{Description}:
 505 @code{ACHAR(I)} returns the character located at position @code{I}
 506 in the @acronym{ASCII} collating sequence.
 507
 508 @item @emph{Standard}:
 509 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
 510
 511 @item @emph{Class}:
 512 Elemental function
 513
 514 @item @emph{Syntax}:
 515 @code{RESULT = ACHAR(I [, KIND])}
 516
 517 @item @emph{Arguments}:
 518 @multitable @columnfractions .15 .70
 519 @item @var{I}    @tab The type shall be @code{INTEGER}.
 520 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 521 expression indicating the kind parameter of the result.
 522 @end multitable
 523
 524 @item @emph{Return value}:
 525 The return value is of type @code{CHARACTER} with a length of one.
 526 If the @var{KIND} argument is present, the return value is of the
 527 specified kind and of the default kind otherwise.
 528
 529 @item @emph{Example}:
 530 @smallexample
 531 program test_achar
 532   character c
 533   c = achar(32)
 534 end program test_achar
 535 @end smallexample
 536
 537 @item @emph{Note}:
 538 See @ref{ICHAR} for a discussion of converting between numerical values
 539 and formatted string representations.
 540
 541 @item @emph{See also}:
 542 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
 543
 544 @end table
 545
 546
 547
 548 @node ACOS
 549 @section @code{ACOS} --- Arccosine function
 550 @fnindex ACOS
 551 @fnindex DACOS
 552 @cindex trigonometric function, cosine, inverse
 553 @cindex cosine, inverse
 554
 555 @table @asis
 556 @item @emph{Description}:
 557 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
 558
 559 @item @emph{Standard}:
 560 Fortran 77 and later, for a complex argument Fortran 2008 or later
 561
 562 @item @emph{Class}:
 563 Elemental function
 564
 565 @item @emph{Syntax}:
 566 @code{RESULT = ACOS(X)}
 567
 568 @item @emph{Arguments}:
 569 @multitable @columnfractions .15 .70
 570 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
 571 less than or equal to one - or the type shall be @code{COMPLEX}.
 572 @end multitable
 573
 574 @item @emph{Return value}:
 575 The return value is of the same type and kind as @var{X}.
 576 The real part of the result is in radians and lies in the range
 577 @math{0 \leq \Re \acos(x) \leq \pi}.
 578
 579 @item @emph{Example}:
 580 @smallexample
 581 program test_acos
 582   real(8) :: x = 0.866_8
 583   x = acos(x)
 584 end program test_acos
 585 @end smallexample
 586
 587 @item @emph{Specific names}:
 588 @multitable @columnfractions .20 .20 .20 .25
 589 @item Name            @tab Argument         @tab Return type     @tab Standard
 590 @item @code{ACOS(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}  @tab Fortran 77 and later
 591 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}  @tab Fortran 77 and later
 592 @end multitable
 593
 594 @item @emph{See also}:
 595 Inverse function: @ref{COS}
 596
 597 @end table
 598
 599
 600
 601 @node ACOSH
 602 @section @code{ACOSH} --- Inverse hyperbolic cosine function
 603 @fnindex ACOSH
 604 @fnindex DACOSH
 605 @cindex area hyperbolic cosine
 606 @cindex inverse hyperbolic cosine
 607 @cindex hyperbolic function, cosine, inverse
 608 @cindex cosine, hyperbolic, inverse
 609
 610 @table @asis
 611 @item @emph{Description}:
 612 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
 613
 614 @item @emph{Standard}:
 615 Fortran 2008 and later
 616
 617 @item @emph{Class}:
 618 Elemental function
 619
 620 @item @emph{Syntax}:
 621 @code{RESULT = ACOSH(X)}
 622
 623 @item @emph{Arguments}:
 624 @multitable @columnfractions .15 .70
 625 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
 626 @end multitable
 627
 628 @item @emph{Return value}:
 629 The return value has the same type and kind as @var{X}. If @var{X} is
 630 complex, the imaginary part of the result is in radians and lies between
 631 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
 632
 633 @item @emph{Example}:
 634 @smallexample
 635 PROGRAM test_acosh
 636   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
 637   WRITE (*,*) ACOSH(x)
 638 END PROGRAM
 639 @end smallexample
 640
 641 @item @emph{Specific names}:
 642 @multitable @columnfractions .20 .20 .20 .25
 643 @item Name             @tab Argument          @tab Return type       @tab Standard
 644 @item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
 645 @end multitable
 646
 647 @item @emph{See also}:
 648 Inverse function: @ref{COSH}
 649 @end table
 650
 651
 652
 653 @node ADJUSTL
 654 @section @code{ADJUSTL} --- Left adjust a string
 655 @fnindex ADJUSTL
 656 @cindex string, adjust left
 657 @cindex adjust string
 658
 659 @table @asis
 660 @item @emph{Description}:
 661 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
 662 Spaces are inserted at the end of the string as needed.
 663
 664 @item @emph{Standard}:
 665 Fortran 90 and later
 666
 667 @item @emph{Class}:
 668 Elemental function
 669
 670 @item @emph{Syntax}:
 671 @code{RESULT = ADJUSTL(STRING)}
 672
 673 @item @emph{Arguments}:
 674 @multitable @columnfractions .15 .70
 675 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
 676 @end multitable
 677
 678 @item @emph{Return value}:
 679 The return value is of type @code{CHARACTER} and of the same kind as
 680 @var{STRING} where leading spaces are removed and the same number of
 681 spaces are inserted on the end of @var{STRING}.
 682
 683 @item @emph{Example}:
 684 @smallexample
 685 program test_adjustl
 686   character(len=20) :: str = '   gfortran'
 687   str = adjustl(str)
 688   print *, str
 689 end program test_adjustl
 690 @end smallexample
 691
 692 @item @emph{See also}:
 693 @ref{ADJUSTR}, @ref{TRIM}
 694 @end table
 695
 696
 697
 698 @node ADJUSTR
 699 @section @code{ADJUSTR} --- Right adjust a string
 700 @fnindex ADJUSTR
 701 @cindex string, adjust right
 702 @cindex adjust string
 703
 704 @table @asis
 705 @item @emph{Description}:
 706 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
 707 Spaces are inserted at the start of the string as needed.
 708
 709 @item @emph{Standard}:
 710 Fortran 95 and later
 711
 712 @item @emph{Class}:
 713 Elemental function
 714
 715 @item @emph{Syntax}:
 716 @code{RESULT = ADJUSTR(STRING)}
 717
 718 @item @emph{Arguments}:
 719 @multitable @columnfractions .15 .70
 720 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 721 @end multitable
 722
 723 @item @emph{Return value}:
 724 The return value is of type @code{CHARACTER} and of the same kind as
 725 @var{STRING} where trailing spaces are removed and the same number of
 726 spaces are inserted at the start of @var{STRING}.
 727
 728 @item @emph{Example}:
 729 @smallexample
 730 program test_adjustr
 731   character(len=20) :: str = 'gfortran'
 732   str = adjustr(str)
 733   print *, str
 734 end program test_adjustr
 735 @end smallexample
 736
 737 @item @emph{See also}:
 738 @ref{ADJUSTL}, @ref{TRIM}
 739 @end table
 740
 741
 742
 743 @node AIMAG
 744 @section @code{AIMAG} --- Imaginary part of complex number
 745 @fnindex AIMAG
 746 @fnindex DIMAG
 747 @fnindex IMAG
 748 @fnindex IMAGPART
 749 @cindex complex numbers, imaginary part
 750
 751 @table @asis
 752 @item @emph{Description}:
 753 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
 754 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
 755 for compatibility with @command{g77}, and their use in new code is
 756 strongly discouraged.
 757
 758 @item @emph{Standard}:
 759 Fortran 77 and later, has overloads that are GNU extensions
 760
 761 @item @emph{Class}:
 762 Elemental function
 763
 764 @item @emph{Syntax}:
 765 @code{RESULT = AIMAG(Z)}
 766
 767 @item @emph{Arguments}:
 768 @multitable @columnfractions .15 .70
 769 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
 770 @end multitable
 771
 772 @item @emph{Return value}:
 773 The return value is of type @code{REAL} with the
 774 kind type parameter of the argument.
 775
 776 @item @emph{Example}:
 777 @smallexample
 778 program test_aimag
 779   complex(4) z4
 780   complex(8) z8
 781   z4 = cmplx(1.e0_4, 0.e0_4)
 782   z8 = cmplx(0.e0_8, 1.e0_8)
 783   print *, aimag(z4), dimag(z8)
 784 end program test_aimag
 785 @end smallexample
 786
 787 @item @emph{Specific names}:
 788 @multitable @columnfractions .20 .20 .20 .25
 789 @item Name               @tab Argument            @tab Return type     @tab Standard
 790 @item @code{AIMAG(Z)}    @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 791 @item @code{DIMAG(Z)}    @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}  @tab GNU extension
 792 @item @code{IMAG(Z)}     @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 793 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 794 @end multitable
 795 @end table
 796
 797
 798
 799 @node AINT
 800 @section @code{AINT} --- Truncate to a whole number
 801 @fnindex AINT
 802 @fnindex DINT
 803 @cindex floor
 804 @cindex rounding, floor
 805
 806 @table @asis
 807 @item @emph{Description}:
 808 @code{AINT(A [, KIND])} truncates its argument to a whole number.
 809
 810 @item @emph{Standard}:
 811 Fortran 77 and later
 812
 813 @item @emph{Class}:
 814 Elemental function
 815
 816 @item @emph{Syntax}:
 817 @code{RESULT = AINT(A [, KIND])}
 818
 819 @item @emph{Arguments}:
 820 @multitable @columnfractions .15 .70
 821 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
 822 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 823 expression indicating the kind parameter of the result.
 824 @end multitable
 825
 826 @item @emph{Return value}:
 827 The return value is of type @code{REAL} with the kind type parameter of the
 828 argument if the optional @var{KIND} is absent; otherwise, the kind
 829 type parameter will be given by @var{KIND}.  If the magnitude of
 830 @var{X} is less than one, @code{AINT(X)} returns zero.  If the
 831 magnitude is equal to or greater than one then it returns the largest
 832 whole number that does not exceed its magnitude.  The sign is the same
 833 as the sign of @var{X}.
 834
 835 @item @emph{Example}:
 836 @smallexample
 837 program test_aint
 838   real(4) x4
 839   real(8) x8
 840   x4 = 1.234E0_4
 841   x8 = 4.321_8
 842   print *, aint(x4), dint(x8)
 843   x8 = aint(x4,8)
 844 end program test_aint
 845 @end smallexample
 846
 847 @item @emph{Specific names}:
 848 @multitable @columnfractions .20 .20 .20 .25
 849 @item Name           @tab Argument         @tab Return type      @tab Standard
 850 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
 851 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
 852 @end multitable
 853 @end table
 854
 855
 856
 857 @node ALARM
 858 @section @code{ALARM} --- Execute a routine after a given delay
 859 @fnindex ALARM
 860 @cindex delayed execution
 861
 862 @table @asis
 863 @item @emph{Description}:
 864 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
 865 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
 866 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
 867 supplied, it will be returned with the number of seconds remaining until
 868 any previously scheduled alarm was due to be delivered, or zero if there
 869 was no previously scheduled alarm.
 870
 871 @item @emph{Standard}:
 872 GNU extension
 873
 874 @item @emph{Class}:
 875 Subroutine
 876
 877 @item @emph{Syntax}:
 878 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
 879
 880 @item @emph{Arguments}:
 881 @multitable @columnfractions .15 .70
 882 @item @var{SECONDS} @tab The type of the argument shall be a scalar
 883 @code{INTEGER}. It is @code{INTENT(IN)}.
 884 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
 885 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
 886 values may be either @code{SIG_IGN=1} to ignore the alarm generated
 887 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
 888 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
 889 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
 890 @end multitable
 891
 892 @item @emph{Example}:
 893 @smallexample
 894 program test_alarm
 895   external handler_print
 896   integer i
 897   call alarm (3, handler_print, i)
 898   print *, i
 899   call sleep(10)
 900 end program test_alarm
 901 @end smallexample
 902 This will cause the external routine @var{handler_print} to be called
 903 after 3 seconds.
 904 @end table
 905
 906
 907
 908 @node ALL
 909 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
 910 @fnindex ALL
 911 @cindex array, apply condition
 912 @cindex array, condition testing
 913
 914 @table @asis
 915 @item @emph{Description}:
 916 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
 917 in the array along dimension @var{DIM}.
 918
 919 @item @emph{Standard}:
 920 Fortran 95 and later
 921
 922 @item @emph{Class}:
 923 Transformational function
 924
 925 @item @emph{Syntax}:
 926 @code{RESULT = ALL(MASK [, DIM])}
 927
 928 @item @emph{Arguments}:
 929 @multitable @columnfractions .15 .70
 930 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
 931 it shall not be scalar.
 932 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
 933 with a value that lies between one and the rank of @var{MASK}.
 934 @end multitable
 935
 936 @item @emph{Return value}:
 937 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
 938 the kind type parameter is the same as the kind type parameter of
 939 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
 940 an array with the rank of @var{MASK} minus 1.  The shape is determined from
 941 the shape of @var{MASK} where the @var{DIM} dimension is elided.
 942
 943 @table @asis
 944 @item (A)
 945 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
 946 It also is true if @var{MASK} has zero size; otherwise, it is false.
 947 @item (B)
 948 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
 949 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
 950 is determined by applying @code{ALL} to the array sections.
 951 @end table
 952
 953 @item @emph{Example}:
 954 @smallexample
 955 program test_all
 956   logical l
 957   l = all((/.true., .true., .true./))
 958   print *, l
 959   call section
 960   contains
 961     subroutine section
 962       integer a(2,3), b(2,3)
 963       a = 1
 964       b = 1
 965       b(2,2) = 2
 966       print *, all(a .eq. b, 1)
 967       print *, all(a .eq. b, 2)
 968     end subroutine section
 969 end program test_all
 970 @end smallexample
 971 @end table
 972
 973
 974
 975 @node ALLOCATED
 976 @section @code{ALLOCATED} --- Status of an allocatable entity
 977 @fnindex ALLOCATED
 978 @cindex allocation, status
 979
 980 @table @asis
 981 @item @emph{Description}:
 982 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
 983 status of @var{ARRAY} and @var{SCALAR}, respectively.
 984
 985 @item @emph{Standard}:
 986 Fortran 95 and later.  Note, the @code{SCALAR=} keyword and allocatable
 987 scalar entities are available in Fortran 2003 and later.
 988
 989 @item @emph{Class}:
 990 Inquiry function
 991
 992 @item @emph{Syntax}:
 993 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
 994
 995 @item @emph{Arguments}:
 996 @multitable @columnfractions .15 .70
 997 @item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
 998 @item @var{SCALAR}   @tab The argument shall be an @code{ALLOCATABLE} scalar.
 999 @end multitable
1000
1001 @item @emph{Return value}:
1002 The return value is a scalar @code{LOGICAL} with the default logical
1003 kind type parameter.  If the argument is allocated, then the result is
1004 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1005
1006 @item @emph{Example}:
1007 @smallexample
1008 program test_allocated
1009   integer :: i = 4
1010   real(4), allocatable :: x(:)
1011   if (.not. allocated(x)) allocate(x(i))
1012 end program test_allocated
1013 @end smallexample
1014 @end table
1015
1016
1017
1018 @node AND
1019 @section @code{AND} --- Bitwise logical AND
1020 @fnindex AND
1021 @cindex bitwise logical and
1022 @cindex logical and, bitwise
1023
1024 @table @asis
1025 @item @emph{Description}:
1026 Bitwise logical @code{AND}.
1027
1028 This intrinsic routine is provided for backwards compatibility with
1029 GNU Fortran 77.  For integer arguments, programmers should consider
1030 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1031
1032 @item @emph{Standard}:
1033 GNU extension
1034
1035 @item @emph{Class}:
1036 Function
1037
1038 @item @emph{Syntax}:
1039 @code{RESULT = AND(I, J)}
1040
1041 @item @emph{Arguments}:
1042 @multitable @columnfractions .15 .70
1043 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1044 type or a scalar @code{LOGICAL} type.
1045 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1046 @end multitable
1047
1048 @item @emph{Return value}:
1049 The return type is either a scalar @code{INTEGER} or a scalar
1050 @code{LOGICAL}.  If the kind type parameters differ, then the
1051 smaller kind type is implicitly converted to larger kind, and the
1052 return has the larger kind.
1053
1054 @item @emph{Example}:
1055 @smallexample
1056 PROGRAM test_and
1057   LOGICAL :: T = .TRUE., F = .FALSE.
1058   INTEGER :: a, b
1059   DATA a / Z'F' /, b / Z'3' /
1060
1061   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1062   WRITE (*,*) AND(a, b)
1063 END PROGRAM
1064 @end smallexample
1065
1066 @item @emph{See also}:
1067 Fortran 95 elemental function: @ref{IAND}
1068 @end table
1069
1070
1071
1072 @node ANINT
1073 @section @code{ANINT} --- Nearest whole number
1074 @fnindex ANINT
1075 @fnindex DNINT
1076 @cindex ceiling
1077 @cindex rounding, ceiling
1078
1079 @table @asis
1080 @item @emph{Description}:
1081 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1082
1083 @item @emph{Standard}:
1084 Fortran 77 and later
1085
1086 @item @emph{Class}:
1087 Elemental function
1088
1089 @item @emph{Syntax}:
1090 @code{RESULT = ANINT(A [, KIND])}
1091
1092 @item @emph{Arguments}:
1093 @multitable @columnfractions .15 .70
1094 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
1095 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1096 expression indicating the kind parameter of the result.
1097 @end multitable
1098
1099 @item @emph{Return value}:
1100 The return value is of type real with the kind type parameter of the
1101 argument if the optional @var{KIND} is absent; otherwise, the kind
1102 type parameter will be given by @var{KIND}.  If @var{A} is greater than
1103 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1104 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1105
1106 @item @emph{Example}:
1107 @smallexample
1108 program test_anint
1109   real(4) x4
1110   real(8) x8
1111   x4 = 1.234E0_4
1112   x8 = 4.321_8
1113   print *, anint(x4), dnint(x8)
1114   x8 = anint(x4,8)
1115 end program test_anint
1116 @end smallexample
1117
1118 @item @emph{Specific names}:
1119 @multitable @columnfractions .20 .20 .20 .25
1120 @item Name            @tab Argument         @tab Return type      @tab Standard
1121 @item @code{AINT(A)}  @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
1122 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1123 @end multitable
1124 @end table
1125
1126
1127
1128 @node ANY
1129 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1130 @fnindex ANY
1131 @cindex array, apply condition
1132 @cindex array, condition testing
1133
1134 @table @asis
1135 @item @emph{Description}:
1136 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1137 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1138
1139 @item @emph{Standard}:
1140 Fortran 95 and later
1141
1142 @item @emph{Class}:
1143 Transformational function
1144
1145 @item @emph{Syntax}:
1146 @code{RESULT = ANY(MASK [, DIM])}
1147
1148 @item @emph{Arguments}:
1149 @multitable @columnfractions .15 .70
1150 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1151 it shall not be scalar.
1152 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1153 with a value that lies between one and the rank of @var{MASK}.
1154 @end multitable
1155
1156 @item @emph{Return value}:
1157 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1158 the kind type parameter is the same as the kind type parameter of
1159 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1160 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1161 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1162
1163 @table @asis
1164 @item (A)
1165 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1166 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1167 @item (B)
1168 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1169 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1170 is determined by applying @code{ANY} to the array sections.
1171 @end table
1172
1173 @item @emph{Example}:
1174 @smallexample
1175 program test_any
1176   logical l
1177   l = any((/.true., .true., .true./))
1178   print *, l
1179   call section
1180   contains
1181     subroutine section
1182       integer a(2,3), b(2,3)
1183       a = 1
1184       b = 1
1185       b(2,2) = 2
1186       print *, any(a .eq. b, 1)
1187       print *, any(a .eq. b, 2)
1188     end subroutine section
1189 end program test_any
1190 @end smallexample
1191 @end table
1192
1193
1194
1195 @node ASIN
1196 @section @code{ASIN} --- Arcsine function
1197 @fnindex ASIN
1198 @fnindex DASIN
1199 @cindex trigonometric function, sine, inverse
1200 @cindex sine, inverse
1201
1202 @table @asis
1203 @item @emph{Description}:
1204 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1205
1206 @item @emph{Standard}:
1207 Fortran 77 and later, for a complex argument Fortran 2008 or later
1208
1209 @item @emph{Class}:
1210 Elemental function
1211
1212 @item @emph{Syntax}:
1213 @code{RESULT = ASIN(X)}
1214
1215 @item @emph{Arguments}:
1216 @multitable @columnfractions .15 .70
1217 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1218 less than or equal to one - or be @code{COMPLEX}.
1219 @end multitable
1220
1221 @item @emph{Return value}:
1222 The return value is of the same type and kind as @var{X}.
1223 The real part of the result is in radians and lies in the range
1224 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1225
1226 @item @emph{Example}:
1227 @smallexample
1228 program test_asin
1229   real(8) :: x = 0.866_8
1230   x = asin(x)
1231 end program test_asin
1232 @end smallexample
1233
1234 @item @emph{Specific names}:
1235 @multitable @columnfractions .20 .20 .20 .25
1236 @item Name            @tab Argument          @tab Return type       @tab Standard
1237 @item @code{ASIN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1238 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1239 @end multitable
1240
1241 @item @emph{See also}:
1242 Inverse function: @ref{SIN}
1243
1244 @end table
1245
1246
1247
1248 @node ASINH
1249 @section @code{ASINH} --- Inverse hyperbolic sine function
1250 @fnindex ASINH
1251 @fnindex DASINH
1252 @cindex area hyperbolic sine
1253 @cindex inverse hyperbolic sine
1254 @cindex hyperbolic function, sine, inverse
1255 @cindex sine, hyperbolic, inverse
1256
1257 @table @asis
1258 @item @emph{Description}:
1259 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1260
1261 @item @emph{Standard}:
1262 Fortran 2008 and later
1263
1264 @item @emph{Class}:
1265 Elemental function
1266
1267 @item @emph{Syntax}:
1268 @code{RESULT = ASINH(X)}
1269
1270 @item @emph{Arguments}:
1271 @multitable @columnfractions .15 .70
1272 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1273 @end multitable
1274
1275 @item @emph{Return value}:
1276 The return value is of the same type and kind as  @var{X}. If @var{X} is
1277 complex, the imaginary part of the result is in radians and lies between
1278 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1279
1280 @item @emph{Example}:
1281 @smallexample
1282 PROGRAM test_asinh
1283   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1284   WRITE (*,*) ASINH(x)
1285 END PROGRAM
1286 @end smallexample
1287
1288 @item @emph{Specific names}:
1289 @multitable @columnfractions .20 .20 .20 .25
1290 @item Name             @tab Argument          @tab Return type       @tab Standard
1291 @item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1292 @end multitable
1293
1294 @item @emph{See also}:
1295 Inverse function: @ref{SINH}
1296 @end table
1297
1298
1299
1300 @node ASSOCIATED
1301 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1302 @fnindex ASSOCIATED
1303 @cindex pointer, status
1304 @cindex association status
1305
1306 @table @asis
1307 @item @emph{Description}:
1308 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1309 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1310
1311 @item @emph{Standard}:
1312 Fortran 95 and later
1313
1314 @item @emph{Class}:
1315 Inquiry function
1316
1317 @item @emph{Syntax}:
1318 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1319
1320 @item @emph{Arguments}:
1321 @multitable @columnfractions .15 .70
1322 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1323 and it can be of any type.
1324 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1325 a target.  It must have the same type, kind type parameter, and
1326 array rank as @var{POINTER}.
1327 @end multitable
1328 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1329 undefined.
1330
1331 @item @emph{Return value}:
1332 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1333 There are several cases:
1334 @table @asis
1335 @item (A) When the optional @var{TARGET} is not present then
1336 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1337 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1338 @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
1339 disassociated, the result is false.
1340 @item (C) If @var{TARGET} is present and an array target, the result is true if
1341 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1342 are arrays whose elements are not zero-sized storage sequences, and
1343 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1344 order.
1345 As in case(B), the result is false, if @var{POINTER} is disassociated.
1346 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1347 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1348 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1349 units.
1350 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1351 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1352 target associated with @var{POINTER} and the target associated with @var{TARGET}
1353 have the same shape, are not zero-sized arrays, are arrays whose elements are
1354 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1355 the same storage units in array element order.
1356 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1357 @end table
1358
1359 @item @emph{Example}:
1360 @smallexample
1361 program test_associated
1362    implicit none
1363    real, target  :: tgt(2) = (/1., 2./)
1364    real, pointer :: ptr(:)
1365    ptr => tgt
1366    if (associated(ptr)     .eqv. .false.) call abort
1367    if (associated(ptr,tgt) .eqv. .false.) call abort
1368 end program test_associated
1369 @end smallexample
1370
1371 @item @emph{See also}:
1372 @ref{NULL}
1373 @end table
1374
1375
1376
1377 @node ATAN
1378 @section @code{ATAN} --- Arctangent function
1379 @fnindex ATAN
1380 @fnindex DATAN
1381 @cindex trigonometric function, tangent, inverse
1382 @cindex tangent, inverse
1383
1384 @table @asis
1385 @item @emph{Description}:
1386 @code{ATAN(X)} computes the arctangent of @var{X}.
1387
1388 @item @emph{Standard}:
1389 Fortran 77 and later, for a complex argument and for two arguments
1390 Fortran 2008 or later
1391
1392 @item @emph{Class}:
1393 Elemental function
1394
1395 @item @emph{Syntax}:
1396 @code{RESULT = ATAN(X)}
1397 @code{RESULT = ATAN(Y, X)}
1398
1399 @item @emph{Arguments}:
1400 @multitable @columnfractions .15 .70
1401 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1402 if @var{Y} is present, @var{X} shall be REAL.
1403 @item @var{Y} shall be of the same type and kind as @var{X}.
1404 @end multitable
1405
1406 @item @emph{Return value}:
1407 The return value is of the same type and kind as @var{X}.
1408 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1409 Otherwise, it the arcus tangent of @var{X}, where the real part of
1410 the result is in radians and lies in the range
1411 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1412
1413 @item @emph{Example}:
1414 @smallexample
1415 program test_atan
1416   real(8) :: x = 2.866_8
1417   x = atan(x)
1418 end program test_atan
1419 @end smallexample
1420
1421 @item @emph{Specific names}:
1422 @multitable @columnfractions .20 .20 .20 .25
1423 @item Name            @tab Argument          @tab Return type       @tab Standard
1424 @item @code{ATAN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1425 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1426 @end multitable
1427
1428 @item @emph{See also}:
1429 Inverse function: @ref{TAN}
1430
1431 @end table
1432
1433
1434
1435 @node ATAN2
1436 @section @code{ATAN2} --- Arctangent function
1437 @fnindex ATAN2
1438 @fnindex DATAN2
1439 @cindex trigonometric function, tangent, inverse
1440 @cindex tangent, inverse
1441
1442 @table @asis
1443 @item @emph{Description}:
1444 @code{ATAN2(Y, X)} computes the principal value of the argument
1445 function of the complex number @math{X + i Y}. This function can
1446 be used to transform from Cartesian into polar coordinates and
1447 allows to determine the angle in the correct quadrant.
1448
1449 @item @emph{Standard}:
1450 Fortran 77 and later
1451
1452 @item @emph{Class}:
1453 Elemental function
1454
1455 @item @emph{Syntax}:
1456 @code{RESULT = ATAN2(Y, X)}
1457
1458 @item @emph{Arguments}:
1459 @multitable @columnfractions .15 .70
1460 @item @var{Y} @tab The type shall be @code{REAL}.
1461 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1462 If @var{Y} is zero, then @var{X} must be nonzero.
1463 @end multitable
1464
1465 @item @emph{Return value}:
1466 The return value has the same type and kind type parameter as @var{Y}.
1467 It is the principal value of the complex number @math{X + i Y}.  If
1468 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1469 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1470 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1471 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1472 is @math{\pi/2}.
1473
1474 @item @emph{Example}:
1475 @smallexample
1476 program test_atan2
1477   real(4) :: x = 1.e0_4, y = 0.5e0_4
1478   x = atan2(y,x)
1479 end program test_atan2
1480 @end smallexample
1481
1482 @item @emph{Specific names}:
1483 @multitable @columnfractions .20 .20 .20 .25
1484 @item Name                @tab Argument            @tab Return type    @tab Standard
1485 @item @code{ATAN2(X, Y)}  @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1486 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1487 @end multitable
1488 @end table
1489
1490
1491
1492 @node ATANH
1493 @section @code{ATANH} --- Inverse hyperbolic tangent function
1494 @fnindex ATANH
1495 @fnindex DATANH
1496 @cindex area hyperbolic tangent
1497 @cindex inverse hyperbolic tangent
1498 @cindex hyperbolic function, tangent, inverse
1499 @cindex tangent, hyperbolic, inverse
1500
1501 @table @asis
1502 @item @emph{Description}:
1503 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1504
1505 @item @emph{Standard}:
1506 Fortran 2008 and later
1507
1508 @item @emph{Class}:
1509 Elemental function
1510
1511 @item @emph{Syntax}:
1512 @code{RESULT = ATANH(X)}
1513
1514 @item @emph{Arguments}:
1515 @multitable @columnfractions .15 .70
1516 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1517 @end multitable
1518
1519 @item @emph{Return value}:
1520 The return value has same type and kind as @var{X}. If @var{X} is
1521 complex, the imaginary part of the result is in radians and lies between
1522 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1523
1524 @item @emph{Example}:
1525 @smallexample
1526 PROGRAM test_atanh
1527   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1528   WRITE (*,*) ATANH(x)
1529 END PROGRAM
1530 @end smallexample
1531
1532 @item @emph{Specific names}:
1533 @multitable @columnfractions .20 .20 .20 .25
1534 @item Name             @tab Argument          @tab Return type       @tab Standard
1535 @item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1536 @end multitable
1537
1538 @item @emph{See also}:
1539 Inverse function: @ref{TANH}
1540 @end table
1541
1542
1543
1544 @node BESSEL_J0
1545 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1546 @fnindex BESSEL_J0
1547 @fnindex BESJ0
1548 @fnindex DBESJ0
1549 @cindex Bessel function, first kind
1550
1551 @table @asis
1552 @item @emph{Description}:
1553 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1554 order 0 of @var{X}. This function is available under the name
1555 @code{BESJ0} as a GNU extension.
1556
1557 @item @emph{Standard}:
1558 Fortran 2008 and later
1559
1560 @item @emph{Class}:
1561 Elemental function
1562
1563 @item @emph{Syntax}:
1564 @code{RESULT = BESSEL_J0(X)}
1565
1566 @item @emph{Arguments}:
1567 @multitable @columnfractions .15 .70
1568 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1569 @end multitable
1570
1571 @item @emph{Return value}:
1572 The return value is of type @code{REAL} and lies in the
1573 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1574 kind as @var{X}.
1575
1576 @item @emph{Example}:
1577 @smallexample
1578 program test_besj0
1579   real(8) :: x = 0.0_8
1580   x = bessel_j0(x)
1581 end program test_besj0
1582 @end smallexample
1583
1584 @item @emph{Specific names}:
1585 @multitable @columnfractions .20 .20 .20 .25
1586 @item Name            @tab Argument          @tab Return type       @tab Standard
1587 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1588 @end multitable
1589 @end table
1590
1591
1592
1593 @node BESSEL_J1
1594 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1595 @fnindex BESSEL_J1
1596 @fnindex BESJ1
1597 @fnindex DBESJ1
1598 @cindex Bessel function, first kind
1599
1600 @table @asis
1601 @item @emph{Description}:
1602 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1603 order 1 of @var{X}. This function is available under the name
1604 @code{BESJ1} as a GNU extension.
1605
1606 @item @emph{Standard}:
1607 Fortran 2008
1608
1609 @item @emph{Class}:
1610 Elemental function
1611
1612 @item @emph{Syntax}:
1613 @code{RESULT = BESSEL_J1(X)}
1614
1615 @item @emph{Arguments}:
1616 @multitable @columnfractions .15 .70
1617 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1618 @end multitable
1619
1620 @item @emph{Return value}:
1621 The return value is of type @code{REAL} and it lies in the
1622 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1623 kind as @var{X}.
1624
1625 @item @emph{Example}:
1626 @smallexample
1627 program test_besj1
1628   real(8) :: x = 1.0_8
1629   x = bessel_j1(x)
1630 end program test_besj1
1631 @end smallexample
1632
1633 @item @emph{Specific names}:
1634 @multitable @columnfractions .20 .20 .20 .25
1635 @item Name             @tab Argument          @tab Return type       @tab Standard
1636 @item @code{DBESJ1(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1637 @end multitable
1638 @end table
1639
1640
1641
1642 @node BESSEL_JN
1643 @section @code{BESSEL_JN} --- Bessel function of the first kind
1644 @fnindex BESSEL_JN
1645 @fnindex BESJN
1646 @fnindex DBESJN
1647 @cindex Bessel function, first kind
1648
1649 @table @asis
1650 @item @emph{Description}:
1651 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1652 order @var{N} of @var{X}. This function is available under the name
1653 @code{BESJN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1654 their ranks and shapes shall conform.
1655
1656 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1657 of the first kind of the orders @var{N1} to @var{N2}.
1658
1659 @item @emph{Standard}:
1660 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1661
1662 @item @emph{Class}:
1663 Elemental function, except for the transformational function
1664 @code{BESSEL_JN(N1, N2, X)}
1665
1666 @item @emph{Syntax}:
1667 @code{RESULT = BESSEL_JN(N, X)}
1668 @code{RESULT = BESSEL_JN(N1, N2, X)}
1669
1670 @item @emph{Arguments}:
1671 @multitable @columnfractions .15 .70
1672 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1673 @item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1674 @item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1675 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1676 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1677 @end multitable
1678
1679 @item @emph{Return value}:
1680 The return value is a scalar of type @code{REAL}. It has the same
1681 kind as @var{X}.
1682
1683 @item @emph{Note}:
1684 The transformational function uses a recurrence algorithm which might,
1685 for some values of @var{X}, lead to different results than calls to
1686 the elemental function.
1687
1688 @item @emph{Example}:
1689 @smallexample
1690 program test_besjn
1691   real(8) :: x = 1.0_8
1692   x = bessel_jn(5,x)
1693 end program test_besjn
1694 @end smallexample
1695
1696 @item @emph{Specific names}:
1697 @multitable @columnfractions .20 .20 .20 .25
1698 @item Name                @tab Argument            @tab Return type       @tab Standard
1699 @item @code{DBESJN(N, X)} @tab @code{INTEGER N}    @tab @code{REAL(8)}    @tab GNU extension
1700 @item                     @tab @code{REAL(8) X}    @tab                   @tab
1701 @end multitable
1702 @end table
1703
1704
1705
1706 @node BESSEL_Y0
1707 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1708 @fnindex BESSEL_Y0
1709 @fnindex BESY0
1710 @fnindex DBESY0
1711 @cindex Bessel function, second kind
1712
1713 @table @asis
1714 @item @emph{Description}:
1715 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1716 order 0 of @var{X}. This function is available under the name
1717 @code{BESY0} as a GNU extension.
1718
1719 @item @emph{Standard}:
1720 Fortran 2008 and later
1721
1722 @item @emph{Class}:
1723 Elemental function
1724
1725 @item @emph{Syntax}:
1726 @code{RESULT = BESSEL_Y0(X)}
1727
1728 @item @emph{Arguments}:
1729 @multitable @columnfractions .15 .70
1730 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1731 @end multitable
1732
1733 @item @emph{Return value}:
1734 The return value is a scalar of type @code{REAL}. It has the same
1735 kind as @var{X}.
1736
1737 @item @emph{Example}:
1738 @smallexample
1739 program test_besy0
1740   real(8) :: x = 0.0_8
1741   x = bessel_y0(x)
1742 end program test_besy0
1743 @end smallexample
1744
1745 @item @emph{Specific names}:
1746 @multitable @columnfractions .20 .20 .20 .25
1747 @item Name            @tab Argument          @tab Return type       @tab Standard
1748 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1749 @end multitable
1750 @end table
1751
1752
1753
1754 @node BESSEL_Y1
1755 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1756 @fnindex BESSEL_Y1
1757 @fnindex BESY1
1758 @fnindex DBESY1
1759 @cindex Bessel function, second kind
1760
1761 @table @asis
1762 @item @emph{Description}:
1763 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1764 order 1 of @var{X}. This function is available under the name
1765 @code{BESY1} as a GNU extension.
1766
1767 @item @emph{Standard}:
1768 Fortran 2008 and later
1769
1770 @item @emph{Class}:
1771 Elemental function
1772
1773 @item @emph{Syntax}:
1774 @code{RESULT = BESSEL_Y1(X)}
1775
1776 @item @emph{Arguments}:
1777 @multitable @columnfractions .15 .70
1778 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1779 @end multitable
1780
1781 @item @emph{Return value}:
1782 The return value is a scalar of type @code{REAL}. It has the same
1783 kind as @var{X}.
1784
1785 @item @emph{Example}:
1786 @smallexample
1787 program test_besy1
1788   real(8) :: x = 1.0_8
1789   x = bessel_y1(x)
1790 end program test_besy1
1791 @end smallexample
1792
1793 @item @emph{Specific names}:
1794 @multitable @columnfractions .20 .20 .20 .25
1795 @item Name            @tab Argument          @tab Return type       @tab Standard
1796 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1797 @end multitable
1798 @end table
1799
1800
1801
1802 @node BESSEL_YN
1803 @section @code{BESSEL_YN} --- Bessel function of the second kind
1804 @fnindex BESSEL_YN
1805 @fnindex BESYN
1806 @fnindex DBESYN
1807 @cindex Bessel function, second kind
1808
1809 @table @asis
1810 @item @emph{Description}:
1811 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1812 order @var{N} of @var{X}. This function is available under the name
1813 @code{BESYN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1814 their ranks and shapes shall conform.
1815
1816 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1817 of the first kind of the orders @var{N1} to @var{N2}.
1818
1819 @item @emph{Standard}:
1820 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1821
1822 @item @emph{Class}:
1823 Elemental function, except for the transformational function
1824 @code{BESSEL_YN(N1, N2, X)}
1825
1826 @item @emph{Syntax}:
1827 @code{RESULT = BESSEL_YN(N, X)}
1828 @code{RESULT = BESSEL_YN(N1, N2, X)}
1829
1830 @item @emph{Arguments}:
1831 @multitable @columnfractions .15 .70
1832 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER} .
1833 @item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1834 @item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1835 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1836 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1837 @end multitable
1838
1839 @item @emph{Return value}:
1840 The return value is a scalar of type @code{REAL}. It has the same
1841 kind as @var{X}.
1842
1843 @item @emph{Note}:
1844 The transformational function uses a recurrence algorithm which might,
1845 for some values of @var{X}, lead to different results than calls to
1846 the elemental function.
1847
1848 @item @emph{Example}:
1849 @smallexample
1850 program test_besyn
1851   real(8) :: x = 1.0_8
1852   x = bessel_yn(5,x)
1853 end program test_besyn
1854 @end smallexample
1855
1856 @item @emph{Specific names}:
1857 @multitable @columnfractions .20 .20 .20 .25
1858 @item Name               @tab Argument            @tab Return type     @tab Standard
1859 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1860 @item                    @tab @code{REAL(8) X} @tab                 @tab
1861 @end multitable
1862 @end table
1863
1864
1865
1866 @node BGE
1867 @section @code{BGE} --- Bitwise greater than or equal to
1868 @fnindex BGE
1869 @cindex bitwise comparison
1870
1871 @table @asis
1872 @item @emph{Description}:
1873 Determines whether an integral is a bitwise greater than or equal to
1874 another.
1875
1876 @item @emph{Standard}:
1877 Fortran 2008 and later
1878
1879 @item @emph{Class}:
1880 Elemental function
1881
1882 @item @emph{Syntax}:
1883 @code{RESULT = BGE(I, J)}
1884
1885 @item @emph{Arguments}:
1886 @multitable @columnfractions .15 .70
1887 @item @var{I} @tab Shall be of @code{INTEGER} type.
1888 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1889 as @var{I}.
1890 @end multitable
1891
1892 @item @emph{Return value}:
1893 The return value is of type @code{LOGICAL} and of the default kind.
1894
1895 @item @emph{See also}:
1896 @ref{BGT}, @ref{BLE}, @ref{BLT}
1897 @end table
1898
1899
1900
1901 @node BGT
1902 @section @code{BGT} --- Bitwise greater than
1903 @fnindex BGT
1904 @cindex bitwise comparison
1905
1906 @table @asis
1907 @item @emph{Description}:
1908 Determines whether an integral is a bitwise greater than another.
1909
1910 @item @emph{Standard}:
1911 Fortran 2008 and later
1912
1913 @item @emph{Class}:
1914 Elemental function
1915
1916 @item @emph{Syntax}:
1917 @code{RESULT = BGT(I, J)}
1918
1919 @item @emph{Arguments}:
1920 @multitable @columnfractions .15 .70
1921 @item @var{I} @tab Shall be of @code{INTEGER} type.
1922 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1923 as @var{I}.
1924 @end multitable
1925
1926 @item @emph{Return value}:
1927 The return value is of type @code{LOGICAL} and of the default kind.
1928
1929 @item @emph{See also}:
1930 @ref{BGE}, @ref{BLE}, @ref{BLT}
1931 @end table
1932
1933
1934
1935 @node BIT_SIZE
1936 @section @code{BIT_SIZE} --- Bit size inquiry function
1937 @fnindex BIT_SIZE
1938 @cindex bits, number of
1939 @cindex size of a variable, in bits
1940
1941 @table @asis
1942 @item @emph{Description}:
1943 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1944 represented by the type of @var{I}.  The result of @code{BIT_SIZE(I)} is
1945 independent of the actual value of @var{I}.
1946
1947 @item @emph{Standard}:
1948 Fortran 95 and later
1949
1950 @item @emph{Class}:
1951 Inquiry function
1952
1953 @item @emph{Syntax}:
1954 @code{RESULT = BIT_SIZE(I)}
1955
1956 @item @emph{Arguments}:
1957 @multitable @columnfractions .15 .70
1958 @item @var{I} @tab The type shall be @code{INTEGER}.
1959 @end multitable
1960
1961 @item @emph{Return value}:
1962 The return value is of type @code{INTEGER}
1963
1964 @item @emph{Example}:
1965 @smallexample
1966 program test_bit_size
1967     integer :: i = 123
1968     integer :: size
1969     size = bit_size(i)
1970     print *, size
1971 end program test_bit_size
1972 @end smallexample
1973 @end table
1974
1975
1976
1977 @node BLE
1978 @section @code{BLE} --- Bitwise less than or equal to
1979 @fnindex BLE
1980 @cindex bitwise comparison
1981
1982 @table @asis
1983 @item @emph{Description}:
1984 Determines whether an integral is a bitwise less than or equal to
1985 another.
1986
1987 @item @emph{Standard}:
1988 Fortran 2008 and later
1989
1990 @item @emph{Class}:
1991 Elemental function
1992
1993 @item @emph{Syntax}:
1994 @code{RESULT = BLE(I, J)}
1995
1996 @item @emph{Arguments}:
1997 @multitable @columnfractions .15 .70
1998 @item @var{I} @tab Shall be of @code{INTEGER} type.
1999 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2000 as @var{I}.
2001 @end multitable
2002
2003 @item @emph{Return value}:
2004 The return value is of type @code{LOGICAL} and of the default kind.
2005
2006 @item @emph{See also}:
2007 @ref{BGT}, @ref{BGE}, @ref{BLT}
2008 @end table
2009
2010
2011
2012 @node BLT
2013 @section @code{BLT} --- Bitwise less than
2014 @fnindex BLT
2015 @cindex bitwise comparison
2016
2017 @table @asis
2018 @item @emph{Description}:
2019 Determines whether an integral is a bitwise less than another.
2020
2021 @item @emph{Standard}:
2022 Fortran 2008 and later
2023
2024 @item @emph{Class}:
2025 Elemental function
2026
2027 @item @emph{Syntax}:
2028 @code{RESULT = BLT(I, J)}
2029
2030 @item @emph{Arguments}:
2031 @multitable @columnfractions .15 .70
2032 @item @var{I} @tab Shall be of @code{INTEGER} type.
2033 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2034 as @var{I}.
2035 @end multitable
2036
2037 @item @emph{Return value}:
2038 The return value is of type @code{LOGICAL} and of the default kind.
2039
2040 @item @emph{See also}:
2041 @ref{BGE}, @ref{BGT}, @ref{BLE}
2042 @end table
2043
2044
2045
2046 @node BTEST
2047 @section @code{BTEST} --- Bit test function
2048 @fnindex BTEST
2049 @cindex bits, testing
2050
2051 @table @asis
2052 @item @emph{Description}:
2053 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2054 in @var{I} is set.  The counting of the bits starts at 0.
2055
2056 @item @emph{Standard}:
2057 Fortran 95 and later
2058
2059 @item @emph{Class}:
2060 Elemental function
2061
2062 @item @emph{Syntax}:
2063 @code{RESULT = BTEST(I, POS)}
2064
2065 @item @emph{Arguments}:
2066 @multitable @columnfractions .15 .70
2067 @item @var{I} @tab The type shall be @code{INTEGER}.
2068 @item @var{POS} @tab The type shall be @code{INTEGER}.
2069 @end multitable
2070
2071 @item @emph{Return value}:
2072 The return value is of type @code{LOGICAL}
2073
2074 @item @emph{Example}:
2075 @smallexample
2076 program test_btest
2077     integer :: i = 32768 + 1024 + 64
2078     integer :: pos
2079     logical :: bool
2080     do pos=0,16
2081         bool = btest(i, pos)
2082         print *, pos, bool
2083     end do
2084 end program test_btest
2085 @end smallexample
2086 @end table
2087
2088
2089 @node C_ASSOCIATED
2090 @section @code{C_ASSOCIATED} --- Status of a C pointer
2091 @fnindex C_ASSOCIATED
2092 @cindex association status, C pointer
2093 @cindex pointer, C association status
2094
2095 @table @asis
2096 @item @emph{Description}:
2097 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2098 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2099
2100 @item @emph{Standard}:
2101 Fortran 2003 and later
2102
2103 @item @emph{Class}:
2104 Inquiry function
2105
2106 @item @emph{Syntax}:
2107 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2108
2109 @item @emph{Arguments}:
2110 @multitable @columnfractions .15 .70
2111 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2112 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2113 @end multitable
2114
2115 @item @emph{Return value}:
2116 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2117 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2118 point to different addresses.
2119
2120 @item @emph{Example}:
2121 @smallexample
2122 subroutine association_test(a,b)
2123   use iso_c_binding, only: c_associated, c_loc, c_ptr
2124   implicit none
2125   real, pointer :: a
2126   type(c_ptr) :: b
2127   if(c_associated(b, c_loc(a))) &
2128      stop 'b and a do not point to same target'
2129 end subroutine association_test
2130 @end smallexample
2131
2132 @item @emph{See also}:
2133 @ref{C_LOC}, @ref{C_FUNLOC}
2134 @end table
2135
2136
2137 @node C_FUNLOC
2138 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2139 @fnindex C_FUNLOC
2140 @cindex pointer, C address of procedures
2141
2142 @table @asis
2143 @item @emph{Description}:
2144 @code{C_FUNLOC(x)} determines the C address of the argument.
2145
2146 @item @emph{Standard}:
2147 Fortran 2003 and later
2148
2149 @item @emph{Class}:
2150 Inquiry function
2151
2152 @item @emph{Syntax}:
2153 @code{RESULT = C_FUNLOC(x)}
2154
2155 @item @emph{Arguments}:
2156 @multitable @columnfractions .15 .70
2157 @item @var{x} @tab Interoperable function or pointer to such function.
2158 @end multitable
2159
2160 @item @emph{Return value}:
2161 The return value is of type @code{C_FUNPTR} and contains the C address
2162 of the argument.
2163
2164 @item @emph{Example}:
2165 @smallexample
2166 module x
2167   use iso_c_binding
2168   implicit none
2169 contains
2170   subroutine sub(a) bind(c)
2171     real(c_float) :: a
2172     a = sqrt(a)+5.0
2173   end subroutine sub
2174 end module x
2175 program main
2176   use iso_c_binding
2177   use x
2178   implicit none
2179   interface
2180     subroutine my_routine(p) bind(c,name='myC_func')
2181       import :: c_funptr
2182       type(c_funptr), intent(in) :: p
2183     end subroutine
2184   end interface
2185   call my_routine(c_funloc(sub))
2186 end program main
2187 @end smallexample
2188
2189 @item @emph{See also}:
2190 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2191 @end table
2192
2193
2194 @node C_F_PROCPOINTER
2195 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2196 @fnindex C_F_PROCPOINTER
2197 @cindex pointer, C address of pointers
2198
2199 @table @asis
2200 @item @emph{Description}:
2201 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2202 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2203
2204 @item @emph{Standard}:
2205 Fortran 2003 and later
2206
2207 @item @emph{Class}:
2208 Subroutine
2209
2210 @item @emph{Syntax}:
2211 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2212
2213 @item @emph{Arguments}:
2214 @multitable @columnfractions .15 .70
2215 @item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2216 @code{INTENT(IN)}.
2217 @item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2218 @code{INTENT(OUT)}.
2219 @end multitable
2220
2221 @item @emph{Example}:
2222 @smallexample
2223 program main
2224   use iso_c_binding
2225   implicit none
2226   abstract interface
2227     function func(a)
2228       import :: c_float
2229       real(c_float), intent(in) :: a
2230       real(c_float) :: func
2231     end function
2232   end interface
2233   interface
2234      function getIterFunc() bind(c,name="getIterFunc")
2235        import :: c_funptr
2236        type(c_funptr) :: getIterFunc
2237      end function
2238   end interface
2239   type(c_funptr) :: cfunptr
2240   procedure(func), pointer :: myFunc
2241   cfunptr = getIterFunc()
2242   call c_f_procpointer(cfunptr, myFunc)
2243 end program main
2244 @end smallexample
2245
2246 @item @emph{See also}:
2247 @ref{C_LOC}, @ref{C_F_POINTER}
2248 @end table
2249
2250
2251 @node C_F_POINTER
2252 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2253 @fnindex C_F_POINTER
2254 @cindex pointer, convert C to Fortran
2255
2256 @table @asis
2257 @item @emph{Description}:
2258 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2259 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2260 shape.
2261
2262 @item @emph{Standard}:
2263 Fortran 2003 and later
2264
2265 @item @emph{Class}:
2266 Subroutine
2267
2268 @item @emph{Syntax}:
2269 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2270
2271 @item @emph{Arguments}:
2272 @multitable @columnfractions .15 .70
2273 @item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2274 @code{INTENT(IN)}.
2275 @item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2276 @code{INTENT(OUT)}.
2277 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2278 with @code{INTENT(IN)}. It shall be present
2279 if and only if @var{fptr} is an array. The size
2280 must be equal to the rank of @var{fptr}.
2281 @end multitable
2282
2283 @item @emph{Example}:
2284 @smallexample
2285 program main
2286   use iso_c_binding
2287   implicit none
2288   interface
2289     subroutine my_routine(p) bind(c,name='myC_func')
2290       import :: c_ptr
2291       type(c_ptr), intent(out) :: p
2292     end subroutine
2293   end interface
2294   type(c_ptr) :: cptr
2295   real,pointer :: a(:)
2296   call my_routine(cptr)
2297   call c_f_pointer(cptr, a, [12])
2298 end program main
2299 @end smallexample
2300
2301 @item @emph{See also}:
2302 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2303 @end table
2304
2305
2306 @node C_LOC
2307 @section @code{C_LOC} --- Obtain the C address of an object
2308 @fnindex C_LOC
2309 @cindex procedure pointer, convert C to Fortran
2310
2311 @table @asis
2312 @item @emph{Description}:
2313 @code{C_LOC(X)} determines the C address of the argument.
2314
2315 @item @emph{Standard}:
2316 Fortran 2003 and later
2317
2318 @item @emph{Class}:
2319 Inquiry function
2320
2321 @item @emph{Syntax}:
2322 @code{RESULT = C_LOC(X)}
2323
2324 @item @emph{Arguments}:
2325 @multitable @columnfractions .10 .75
2326 @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.
2327
2328 @end multitable
2329
2330 @item @emph{Return value}:
2331 The return value is of type @code{C_PTR} and contains the C address
2332 of the argument.
2333
2334 @item @emph{Example}:
2335 @smallexample
2336 subroutine association_test(a,b)
2337   use iso_c_binding, only: c_associated, c_loc, c_ptr
2338   implicit none
2339   real, pointer :: a
2340   type(c_ptr) :: b
2341   if(c_associated(b, c_loc(a))) &
2342      stop 'b and a do not point to same target'
2343 end subroutine association_test
2344 @end smallexample
2345
2346 @item @emph{See also}:
2347 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2348 @end table
2349
2350
2351 @node C_SIZEOF
2352 @section @code{C_SIZEOF} --- Size in bytes of an expression
2353 @fnindex C_SIZEOF
2354 @cindex expression size
2355 @cindex size of an expression
2356
2357 @table @asis
2358 @item @emph{Description}:
2359 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2360 expression @code{X} occupies.
2361
2362 @item @emph{Standard}:
2363 Fortran 2008
2364
2365 @item @emph{Class}:
2366 Intrinsic function
2367
2368 @item @emph{Syntax}:
2369 @code{N = C_SIZEOF(X)}
2370
2371 @item @emph{Arguments}:
2372 @multitable @columnfractions .15 .70
2373 @item @var{X} @tab The argument shall be an interoperable data entity.
2374 @end multitable
2375
2376 @item @emph{Return value}:
2377 The return value is of type integer and of the system-dependent kind
2378 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2379 number of bytes occupied by the argument.  If the argument has the
2380 @code{POINTER} attribute, the number of bytes of the storage area pointed
2381 to is returned.  If the argument is of a derived type with @code{POINTER}
2382 or @code{ALLOCATABLE} components, the return value doesn't account for
2383 the sizes of the data pointed to by these components.
2384
2385 @item @emph{Example}:
2386 @smallexample
2387    use iso_c_binding
2388    integer(c_int) :: i
2389    real(c_float) :: r, s(5)
2390    print *, (c_sizeof(s)/c_sizeof(r) == 5)
2391    end
2392 @end smallexample
2393 The example will print @code{.TRUE.} unless you are using a platform
2394 where default @code{REAL} variables are unusually padded.
2395
2396 @item @emph{See also}:
2397 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2398 @end table
2399
2400
2401 @node CEILING
2402 @section @code{CEILING} --- Integer ceiling function
2403 @fnindex CEILING
2404 @cindex ceiling
2405 @cindex rounding, ceiling
2406
2407 @table @asis
2408 @item @emph{Description}:
2409 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2410
2411 @item @emph{Standard}:
2412 Fortran 95 and later
2413
2414 @item @emph{Class}:
2415 Elemental function
2416
2417 @item @emph{Syntax}:
2418 @code{RESULT = CEILING(A [, KIND])}
2419
2420 @item @emph{Arguments}:
2421 @multitable @columnfractions .15 .70
2422 @item @var{A} @tab The type shall be @code{REAL}.
2423 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2424 expression indicating the kind parameter of the result.
2425 @end multitable
2426
2427 @item @emph{Return value}:
2428 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2429 and a default-kind @code{INTEGER} otherwise.
2430
2431 @item @emph{Example}:
2432 @smallexample
2433 program test_ceiling
2434     real :: x = 63.29
2435     real :: y = -63.59
2436     print *, ceiling(x) ! returns 64
2437     print *, ceiling(y) ! returns -63
2438 end program test_ceiling
2439 @end smallexample
2440
2441 @item @emph{See also}:
2442 @ref{FLOOR}, @ref{NINT}
2443
2444 @end table
2445
2446
2447
2448 @node CHAR
2449 @section @code{CHAR} --- Character conversion function
2450 @fnindex CHAR
2451 @cindex conversion, to character
2452
2453 @table @asis
2454 @item @emph{Description}:
2455 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2456
2457 @item @emph{Standard}:
2458 Fortran 77 and later
2459
2460 @item @emph{Class}:
2461 Elemental function
2462
2463 @item @emph{Syntax}:
2464 @code{RESULT = CHAR(I [, KIND])}
2465
2466 @item @emph{Arguments}:
2467 @multitable @columnfractions .15 .70
2468 @item @var{I} @tab The type shall be @code{INTEGER}.
2469 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2470 expression indicating the kind parameter of the result.
2471 @end multitable
2472
2473 @item @emph{Return value}:
2474 The return value is of type @code{CHARACTER(1)}
2475
2476 @item @emph{Example}:
2477 @smallexample
2478 program test_char
2479     integer :: i = 74
2480     character(1) :: c
2481     c = char(i)
2482     print *, i, c ! returns 'J'
2483 end program test_char
2484 @end smallexample
2485
2486 @item @emph{Specific names}:
2487 @multitable @columnfractions .20 .20 .20 .25
2488 @item Name           @tab Argument         @tab Return type             @tab Standard
2489 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2490 @end multitable
2491
2492 @item @emph{Note}:
2493 See @ref{ICHAR} for a discussion of converting between numerical values
2494 and formatted string representations.
2495
2496 @item @emph{See also}:
2497 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2498
2499 @end table
2500
2501
2502
2503 @node CHDIR
2504 @section @code{CHDIR} --- Change working directory
2505 @fnindex CHDIR
2506 @cindex system, working directory
2507
2508 @table @asis
2509 @item @emph{Description}:
2510 Change current working directory to a specified path.
2511
2512 This intrinsic is provided in both subroutine and function forms; however,
2513 only one form can be used in any given program unit.
2514
2515 @item @emph{Standard}:
2516 GNU extension
2517
2518 @item @emph{Class}:
2519 Subroutine, function
2520
2521 @item @emph{Syntax}:
2522 @multitable @columnfractions .80
2523 @item @code{CALL CHDIR(NAME [, STATUS])}
2524 @item @code{STATUS = CHDIR(NAME)}
2525 @end multitable
2526
2527 @item @emph{Arguments}:
2528 @multitable @columnfractions .15 .70
2529 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2530 kind and shall specify a valid path within the file system.
2531 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2532 kind.  Returns 0 on success, and a system specific and nonzero error code
2533 otherwise.
2534 @end multitable
2535
2536 @item @emph{Example}:
2537 @smallexample
2538 PROGRAM test_chdir
2539   CHARACTER(len=255) :: path
2540   CALL getcwd(path)
2541   WRITE(*,*) TRIM(path)
2542   CALL chdir("/tmp")
2543   CALL getcwd(path)
2544   WRITE(*,*) TRIM(path)
2545 END PROGRAM
2546 @end smallexample
2547
2548 @item @emph{See also}:
2549 @ref{GETCWD}
2550 @end table
2551
2552
2553
2554 @node CHMOD
2555 @section @code{CHMOD} --- Change access permissions of files
2556 @fnindex CHMOD
2557 @cindex file system, change access mode
2558
2559 @table @asis
2560 @item @emph{Description}:
2561 @code{CHMOD} changes the permissions of a file. This function invokes
2562 @code{/bin/chmod} and might therefore not work on all platforms.
2563
2564 This intrinsic is provided in both subroutine and function forms; however,
2565 only one form can be used in any given program unit.
2566
2567 @item @emph{Standard}:
2568 GNU extension
2569
2570 @item @emph{Class}:
2571 Subroutine, function
2572
2573 @item @emph{Syntax}:
2574 @multitable @columnfractions .80
2575 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2576 @item @code{STATUS = CHMOD(NAME, MODE)}
2577 @end multitable
2578
2579 @item @emph{Arguments}:
2580 @multitable @columnfractions .15 .70
2581
2582 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2583 file name. Trailing blanks are ignored unless the character
2584 @code{achar(0)} is present, then all characters up to and excluding
2585 @code{achar(0)} are used as the file name.
2586
2587 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2588 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2589 argument of @code{/bin/chmod}.
2590
2591 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2592 @code{0} on success and nonzero otherwise.
2593 @end multitable
2594
2595 @item @emph{Return value}:
2596 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2597 otherwise.
2598
2599 @item @emph{Example}:
2600 @code{CHMOD} as subroutine
2601 @smallexample
2602 program chmod_test
2603   implicit none
2604   integer :: status
2605   call chmod('test.dat','u+x',status)
2606   print *, 'Status: ', status
2607 end program chmod_test
2608 @end smallexample
2609 @code{CHMOD} as function:
2610 @smallexample
2611 program chmod_test
2612   implicit none
2613   integer :: status
2614   status = chmod('test.dat','u+x')
2615   print *, 'Status: ', status
2616 end program chmod_test
2617 @end smallexample
2618
2619 @end table
2620
2621
2622
2623 @node CMPLX
2624 @section @code{CMPLX} --- Complex conversion function
2625 @fnindex CMPLX
2626 @cindex complex numbers, conversion to
2627 @cindex conversion, to complex
2628
2629 @table @asis
2630 @item @emph{Description}:
2631 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2632 the real component.  If @var{Y} is present it is converted to the imaginary
2633 component.  If @var{Y} is not present then the imaginary component is set to
2634 0.0.  If @var{X} is complex then @var{Y} must not be present.
2635
2636 @item @emph{Standard}:
2637 Fortran 77 and later
2638
2639 @item @emph{Class}:
2640 Elemental function
2641
2642 @item @emph{Syntax}:
2643 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2644
2645 @item @emph{Arguments}:
2646 @multitable @columnfractions .15 .70
2647 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2648 or @code{COMPLEX}.
2649 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2650 @code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
2651 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2652 expression indicating the kind parameter of the result.
2653 @end multitable
2654
2655 @item @emph{Return value}:
2656 The return value is of @code{COMPLEX} type, with a kind equal to
2657 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2658 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2659 @var{X} and @var{Y}.
2660
2661 @item @emph{Example}:
2662 @smallexample
2663 program test_cmplx
2664     integer :: i = 42
2665     real :: x = 3.14
2666     complex :: z
2667     z = cmplx(i, x)
2668     print *, z, cmplx(x)
2669 end program test_cmplx
2670 @end smallexample
2671
2672 @item @emph{See also}:
2673 @ref{COMPLEX}
2674 @end table
2675
2676
2677
2678 @node COMMAND_ARGUMENT_COUNT
2679 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2680 @fnindex COMMAND_ARGUMENT_COUNT
2681 @cindex command-line arguments
2682 @cindex command-line arguments, number of
2683 @cindex arguments, to program
2684
2685 @table @asis
2686 @item @emph{Description}:
2687 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2688 command line when the containing program was invoked.
2689
2690 @item @emph{Standard}:
2691 Fortran 2003 and later
2692
2693 @item @emph{Class}:
2694 Inquiry function
2695
2696 @item @emph{Syntax}:
2697 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2698
2699 @item @emph{Arguments}:
2700 @multitable @columnfractions .15 .70
2701 @item None
2702 @end multitable
2703
2704 @item @emph{Return value}:
2705 The return value is an @code{INTEGER} of default kind.
2706
2707 @item @emph{Example}:
2708 @smallexample
2709 program test_command_argument_count
2710     integer :: count
2711     count = command_argument_count()
2712     print *, count
2713 end program test_command_argument_count
2714 @end smallexample
2715
2716 @item @emph{See also}:
2717 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2718 @end table
2719
2720
2721
2722 @node COMPLEX
2723 @section @code{COMPLEX} --- Complex conversion function
2724 @fnindex COMPLEX
2725 @cindex complex numbers, conversion to
2726 @cindex conversion, to complex
2727
2728 @table @asis
2729 @item @emph{Description}:
2730 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2731 to the real component and @var{Y} is converted to the imaginary
2732 component.
2733
2734 @item @emph{Standard}:
2735 GNU extension
2736
2737 @item @emph{Class}:
2738 Elemental function
2739
2740 @item @emph{Syntax}:
2741 @code{RESULT = COMPLEX(X, Y)}
2742
2743 @item @emph{Arguments}:
2744 @multitable @columnfractions .15 .70
2745 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2746 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2747 @end multitable
2748
2749 @item @emph{Return value}:
2750 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2751 value is of default @code{COMPLEX} type.
2752
2753 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2754 type and one is of @code{INTEGER} type, then the return value is of
2755 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2756 argument with the highest precision.
2757
2758 @item @emph{Example}:
2759 @smallexample
2760 program test_complex
2761     integer :: i = 42
2762     real :: x = 3.14
2763     print *, complex(i, x)
2764 end program test_complex
2765 @end smallexample
2766
2767 @item @emph{See also}:
2768 @ref{CMPLX}
2769 @end table
2770
2771
2772
2773 @node CONJG
2774 @section @code{CONJG} --- Complex conjugate function
2775 @fnindex CONJG
2776 @fnindex DCONJG
2777 @cindex complex conjugate
2778
2779 @table @asis
2780 @item @emph{Description}:
2781 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2782 then the result is @code{(x, -y)}
2783
2784 @item @emph{Standard}:
2785 Fortran 77 and later, has overloads that are GNU extensions
2786
2787 @item @emph{Class}:
2788 Elemental function
2789
2790 @item @emph{Syntax}:
2791 @code{Z = CONJG(Z)}
2792
2793 @item @emph{Arguments}:
2794 @multitable @columnfractions .15 .70
2795 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2796 @end multitable
2797
2798 @item @emph{Return value}:
2799 The return value is of type @code{COMPLEX}.
2800
2801 @item @emph{Example}:
2802 @smallexample
2803 program test_conjg
2804     complex :: z = (2.0, 3.0)
2805     complex(8) :: dz = (2.71_8, -3.14_8)
2806     z= conjg(z)
2807     print *, z
2808     dz = dconjg(dz)
2809     print *, dz
2810 end program test_conjg
2811 @end smallexample
2812
2813 @item @emph{Specific names}:
2814 @multitable @columnfractions .20 .20 .20 .25
2815 @item Name             @tab Argument             @tab Return type       @tab Standard
2816 @item @code{CONJG(Z)}  @tab @code{COMPLEX Z}     @tab @code{COMPLEX}    @tab GNU extension
2817 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)} @tab GNU extension
2818 @end multitable
2819 @end table
2820
2821
2822
2823 @node COS
2824 @section @code{COS} --- Cosine function
2825 @fnindex COS
2826 @fnindex DCOS
2827 @fnindex CCOS
2828 @fnindex ZCOS
2829 @fnindex CDCOS
2830 @cindex trigonometric function, cosine
2831 @cindex cosine
2832
2833 @table @asis
2834 @item @emph{Description}:
2835 @code{COS(X)} computes the cosine of @var{X}.
2836
2837 @item @emph{Standard}:
2838 Fortran 77 and later, has overloads that are GNU extensions
2839
2840 @item @emph{Class}:
2841 Elemental function
2842
2843 @item @emph{Syntax}:
2844 @code{RESULT = COS(X)}
2845
2846 @item @emph{Arguments}:
2847 @multitable @columnfractions .15 .70
2848 @item @var{X} @tab The type shall be @code{REAL} or
2849 @code{COMPLEX}.
2850 @end multitable
2851
2852 @item @emph{Return value}:
2853 The return value is of the same type and kind as @var{X}. The real part
2854 of the result is in radians. If @var{X} is of the type @code{REAL},
2855 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2856
2857 @item @emph{Example}:
2858 @smallexample
2859 program test_cos
2860   real :: x = 0.0
2861   x = cos(x)
2862 end program test_cos
2863 @end smallexample
2864
2865 @item @emph{Specific names}:
2866 @multitable @columnfractions .20 .20 .20 .25
2867 @item Name            @tab Argument            @tab Return type       @tab Standard
2868 @item @code{COS(X)}   @tab @code{REAL(4) X}    @tab @code{REAL(4)}    @tab Fortran 77 and later
2869 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
2870 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2871 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2872 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2873 @end multitable
2874
2875 @item @emph{See also}:
2876 Inverse function: @ref{ACOS}
2877
2878 @end table
2879
2880
2881
2882 @node COSH
2883 @section @code{COSH} --- Hyperbolic cosine function
2884 @fnindex COSH
2885 @fnindex DCOSH
2886 @cindex hyperbolic cosine
2887 @cindex hyperbolic function, cosine
2888 @cindex cosine, hyperbolic
2889
2890 @table @asis
2891 @item @emph{Description}:
2892 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2893
2894 @item @emph{Standard}:
2895 Fortran 77 and later, for a complex argument Fortran 2008 or later
2896
2897 @item @emph{Class}:
2898 Elemental function
2899
2900 @item @emph{Syntax}:
2901 @code{X = COSH(X)}
2902
2903 @item @emph{Arguments}:
2904 @multitable @columnfractions .15 .70
2905 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2906 @end multitable
2907
2908 @item @emph{Return value}:
2909 The return value has same type and kind as @var{X}. If @var{X} is
2910 complex, the imaginary part of the result is in radians. If @var{X}
2911 is @code{REAL}, the return value has a lower bound of one,
2912 @math{\cosh (x) \geq 1}.
2913
2914 @item @emph{Example}:
2915 @smallexample
2916 program test_cosh
2917   real(8) :: x = 1.0_8
2918   x = cosh(x)
2919 end program test_cosh
2920 @end smallexample
2921
2922 @item @emph{Specific names}:
2923 @multitable @columnfractions .20 .20 .20 .25
2924 @item Name            @tab Argument          @tab Return type       @tab Standard
2925 @item @code{COSH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
2926 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
2927 @end multitable
2928
2929 @item @emph{See also}:
2930 Inverse function: @ref{ACOSH}
2931
2932 @end table
2933
2934
2935
2936 @node COUNT
2937 @section @code{COUNT} --- Count function
2938 @fnindex COUNT
2939 @cindex array, conditionally count elements
2940 @cindex array, element counting
2941 @cindex array, number of elements
2942
2943 @table @asis
2944 @item @emph{Description}:
2945
2946 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2947 or, if the @var{DIM} argument is supplied, counts the number of
2948 elements along each row of the array in the @var{DIM} direction.
2949 If the array has zero size, or all of the elements of @var{MASK} are
2950 @code{.FALSE.}, then the result is @code{0}.
2951
2952 @item @emph{Standard}:
2953 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2954
2955 @item @emph{Class}:
2956 Transformational function
2957
2958 @item @emph{Syntax}:
2959 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2960
2961 @item @emph{Arguments}:
2962 @multitable @columnfractions .15 .70
2963 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2964 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
2965 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2966 expression indicating the kind parameter of the result.
2967 @end multitable
2968
2969 @item @emph{Return value}:
2970 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2971 @var{KIND} is absent, the return value is of default integer kind.
2972 If @var{DIM} is present, the result is an array with a rank one less
2973 than the rank of @var{ARRAY}, and a size corresponding to the shape
2974 of @var{ARRAY} with the @var{DIM} dimension removed.
2975
2976 @item @emph{Example}:
2977 @smallexample
2978 program test_count
2979     integer, dimension(2,3) :: a, b
2980     logical, dimension(2,3) :: mask
2981     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2982     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2983     print '(3i3)', a(1,:)
2984     print '(3i3)', a(2,:)
2985     print *
2986     print '(3i3)', b(1,:)
2987     print '(3i3)', b(2,:)
2988     print *
2989     mask = a.ne.b
2990     print '(3l3)', mask(1,:)
2991     print '(3l3)', mask(2,:)
2992     print *
2993     print '(3i3)', count(mask)
2994     print *
2995     print '(3i3)', count(mask, 1)
2996     print *
2997     print '(3i3)', count(mask, 2)
2998 end program test_count
2999 @end smallexample
3000 @end table
3001
3002
3003
3004 @node CPU_TIME
3005 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3006 @fnindex CPU_TIME
3007 @cindex time, elapsed
3008
3009 @table @asis
3010 @item @emph{Description}:
3011 Returns a @code{REAL} value representing the elapsed CPU time in
3012 seconds.  This is useful for testing segments of code to determine
3013 execution time.
3014
3015 If a time source is available, time will be reported with microsecond
3016 resolution. If no time source is available, @var{TIME} is set to
3017 @code{-1.0}.
3018
3019 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3020 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3021 value is meaningless, only differences between subsequent calls to
3022 this subroutine, as shown in the example below, should be used.
3023
3024
3025 @item @emph{Standard}:
3026 Fortran 95 and later
3027
3028 @item @emph{Class}:
3029 Subroutine
3030
3031 @item @emph{Syntax}:
3032 @code{CALL CPU_TIME(TIME)}
3033
3034 @item @emph{Arguments}:
3035 @multitable @columnfractions .15 .70
3036 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3037 @end multitable
3038
3039 @item @emph{Return value}:
3040 None
3041
3042 @item @emph{Example}:
3043 @smallexample
3044 program test_cpu_time
3045     real :: start, finish
3046     call cpu_time(start)
3047         ! put code to test here
3048     call cpu_time(finish)
3049     print '("Time = ",f6.3," seconds.")',finish-start
3050 end program test_cpu_time
3051 @end smallexample
3052
3053 @item @emph{See also}:
3054 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3055 @end table
3056
3057
3058
3059 @node CSHIFT
3060 @section @code{CSHIFT} --- Circular shift elements of an array
3061 @fnindex CSHIFT
3062 @cindex array, shift circularly
3063 @cindex array, permutation
3064 @cindex array, rotate
3065
3066 @table @asis
3067 @item @emph{Description}:
3068 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3069 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
3070 taken to be @code{1}.  @var{DIM} is a scalar of type @code{INTEGER} in the
3071 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3072 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3073 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
3074 sections of @var{ARRAY} along the given dimension are shifted.  Elements
3075 shifted out one end of each rank one section are shifted back in the other end.
3076
3077 @item @emph{Standard}:
3078 Fortran 95 and later
3079
3080 @item @emph{Class}:
3081 Transformational function
3082
3083 @item @emph{Syntax}:
3084 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3085
3086 @item @emph{Arguments}:
3087 @multitable @columnfractions .15 .70
3088 @item @var{ARRAY}  @tab Shall be an array of any type.
3089 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3090 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3091 @end multitable
3092
3093 @item @emph{Return value}:
3094 Returns an array of same type and rank as the @var{ARRAY} argument.
3095
3096 @item @emph{Example}:
3097 @smallexample
3098 program test_cshift
3099     integer, dimension(3,3) :: a
3100     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3101     print '(3i3)', a(1,:)
3102     print '(3i3)', a(2,:)
3103     print '(3i3)', a(3,:)
3104     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3105     print *
3106     print '(3i3)', a(1,:)
3107     print '(3i3)', a(2,:)
3108     print '(3i3)', a(3,:)
3109 end program test_cshift
3110 @end smallexample
3111 @end table
3112
3113
3114
3115 @node CTIME
3116 @section @code{CTIME} --- Convert a time into a string
3117 @fnindex CTIME
3118 @cindex time, conversion to string
3119 @cindex conversion, to string
3120
3121 @table @asis
3122 @item @emph{Description}:
3123 @code{CTIME} converts a system time value, such as returned by
3124 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
3125
3126 This intrinsic is provided in both subroutine and function forms; however,
3127 only one form can be used in any given program unit.
3128
3129 @item @emph{Standard}:
3130 GNU extension
3131
3132 @item @emph{Class}:
3133 Subroutine, function
3134
3135 @item @emph{Syntax}:
3136 @multitable @columnfractions .80
3137 @item @code{CALL CTIME(TIME, RESULT)}.
3138 @item @code{RESULT = CTIME(TIME)}, (not recommended).
3139 @end multitable
3140
3141 @item @emph{Arguments}:
3142 @multitable @columnfractions .15 .70
3143 @item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
3144 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
3145 of default kind.
3146 @end multitable
3147
3148 @item @emph{Return value}:
3149 The converted date and time as a string.
3150
3151 @item @emph{Example}:
3152 @smallexample
3153 program test_ctime
3154     integer(8) :: i
3155     character(len=30) :: date
3156     i = time8()
3157
3158     ! Do something, main part of the program
3159
3160     call ctime(i,date)
3161     print *, 'Program was started on ', date
3162 end program test_ctime
3163 @end smallexample
3164
3165 @item @emph{See Also}:
3166 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3167 @end table
3168
3169
3170
3171 @node DATE_AND_TIME
3172 @section @code{DATE_AND_TIME} --- Date and time subroutine
3173 @fnindex DATE_AND_TIME
3174 @cindex date, current
3175 @cindex current date
3176 @cindex time, current
3177 @cindex current time
3178
3179 @table @asis
3180 @item @emph{Description}:
3181 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3182 time information from the real-time system clock.  @var{DATE} is
3183 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
3184 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3185 representing the difference with respect to Coordinated Universal Time (UTC).
3186 Unavailable time and date parameters return blanks.
3187
3188 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3189
3190 @multitable @columnfractions .15 .30 .40
3191 @item @tab @code{VALUE(1)}: @tab The year
3192 @item @tab @code{VALUE(2)}: @tab The month
3193 @item @tab @code{VALUE(3)}: @tab The day of the month
3194 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3195 @item @tab @code{VALUE(5)}: @tab The hour of the day
3196 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3197 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3198 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3199 @end multitable
3200
3201 @item @emph{Standard}:
3202 Fortran 95 and later
3203
3204 @item @emph{Class}:
3205 Subroutine
3206
3207 @item @emph{Syntax}:
3208 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3209
3210 @item @emph{Arguments}:
3211 @multitable @columnfractions .15 .70
3212 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3213 or larger, and of default kind.
3214 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3215 or larger, and of default kind.
3216 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3217 or larger, and of default kind.
3218 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3219 @end multitable
3220
3221 @item @emph{Return value}:
3222 None
3223
3224 @item @emph{Example}:
3225 @smallexample
3226 program test_time_and_date
3227     character(8)  :: date
3228     character(10) :: time
3229     character(5)  :: zone
3230     integer,dimension(8) :: values
3231     ! using keyword arguments
3232     call date_and_time(date,time,zone,values)
3233     call date_and_time(DATE=date,ZONE=zone)
3234     call date_and_time(TIME=time)
3235     call date_and_time(VALUES=values)
3236     print '(a,2x,a,2x,a)', date, time, zone
3237     print '(8i5))', values
3238 end program test_time_and_date
3239 @end smallexample
3240
3241 @item @emph{See also}:
3242 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3243 @end table
3244
3245
3246
3247 @node DBLE
3248 @section @code{DBLE} --- Double conversion function
3249 @fnindex DBLE
3250 @cindex conversion, to real
3251
3252 @table @asis
3253 @item @emph{Description}:
3254 @code{DBLE(A)} Converts @var{A} to double precision real type.
3255
3256 @item @emph{Standard}:
3257 Fortran 77 and later
3258
3259 @item @emph{Class}:
3260 Elemental function
3261
3262 @item @emph{Syntax}:
3263 @code{RESULT = DBLE(A)}
3264
3265 @item @emph{Arguments}:
3266 @multitable @columnfractions .15 .70
3267 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3268 or @code{COMPLEX}.
3269 @end multitable
3270
3271 @item @emph{Return value}:
3272 The return value is of type double precision real.
3273
3274 @item @emph{Example}:
3275 @smallexample
3276 program test_dble
3277     real    :: x = 2.18
3278     integer :: i = 5
3279     complex :: z = (2.3,1.14)
3280     print *, dble(x), dble(i), dble(z)
3281 end program test_dble
3282 @end smallexample
3283
3284 @item @emph{See also}:
3285 @ref{REAL}
3286 @end table
3287
3288
3289
3290 @node DCMPLX
3291 @section @code{DCMPLX} --- Double complex conversion function
3292 @fnindex DCMPLX
3293 @cindex complex numbers, conversion to
3294 @cindex conversion, to complex
3295
3296 @table @asis
3297 @item @emph{Description}:
3298 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3299 converted to the real component.  If @var{Y} is present it is converted to the
3300 imaginary component.  If @var{Y} is not present then the imaginary component is
3301 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3302
3303 @item @emph{Standard}:
3304 GNU extension
3305
3306 @item @emph{Class}:
3307 Elemental function
3308
3309 @item @emph{Syntax}:
3310 @code{RESULT = DCMPLX(X [, Y])}
3311
3312 @item @emph{Arguments}:
3313 @multitable @columnfractions .15 .70
3314 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3315 or @code{COMPLEX}.
3316 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3317 @code{INTEGER} or @code{REAL}.
3318 @end multitable
3319
3320 @item @emph{Return value}:
3321 The return value is of type @code{COMPLEX(8)}
3322
3323 @item @emph{Example}:
3324 @smallexample
3325 program test_dcmplx
3326     integer :: i = 42
3327     real :: x = 3.14
3328     complex :: z
3329     z = cmplx(i, x)
3330     print *, dcmplx(i)
3331     print *, dcmplx(x)
3332     print *, dcmplx(z)
3333     print *, dcmplx(x,i)
3334 end program test_dcmplx
3335 @end smallexample
3336 @end table
3337
3338
3339 @node DIGITS
3340 @section @code{DIGITS} --- Significant binary digits function
3341 @fnindex DIGITS
3342 @cindex model representation, significant digits
3343
3344 @table @asis
3345 @item @emph{Description}:
3346 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3347 model representation of @var{X}.  For example, on a system using a 32-bit
3348 floating point representation, a default real number would likely return 24.
3349
3350 @item @emph{Standard}:
3351 Fortran 95 and later
3352
3353 @item @emph{Class}:
3354 Inquiry function
3355
3356 @item @emph{Syntax}:
3357 @code{RESULT = DIGITS(X)}
3358
3359 @item @emph{Arguments}:
3360 @multitable @columnfractions .15 .70
3361 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3362 @end multitable
3363
3364 @item @emph{Return value}:
3365 The return value is of type @code{INTEGER}.
3366
3367 @item @emph{Example}:
3368 @smallexample
3369 program test_digits
3370     integer :: i = 12345
3371     real :: x = 3.143
3372     real(8) :: y = 2.33
3373     print *, digits(i)
3374     print *, digits(x)
3375     print *, digits(y)
3376 end program test_digits
3377 @end smallexample
3378 @end table
3379
3380
3381
3382 @node DIM
3383 @section @code{DIM} --- Positive difference
3384 @fnindex DIM
3385 @fnindex IDIM
3386 @fnindex DDIM
3387 @cindex positive difference
3388
3389 @table @asis
3390 @item @emph{Description}:
3391 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3392 otherwise returns zero.
3393
3394 @item @emph{Standard}:
3395 Fortran 77 and later
3396
3397 @item @emph{Class}:
3398 Elemental function
3399
3400 @item @emph{Syntax}:
3401 @code{RESULT = DIM(X, Y)}
3402
3403 @item @emph{Arguments}:
3404 @multitable @columnfractions .15 .70
3405 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3406 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3407 @end multitable
3408
3409 @item @emph{Return value}:
3410 The return value is of type @code{INTEGER} or @code{REAL}.
3411
3412 @item @emph{Example}:
3413 @smallexample
3414 program test_dim
3415     integer :: i
3416     real(8) :: x
3417     i = dim(4, 15)
3418     x = dim(4.345_8, 2.111_8)
3419     print *, i
3420     print *, x
3421 end program test_dim
3422 @end smallexample
3423
3424 @item @emph{Specific names}:
3425 @multitable @columnfractions .20 .20 .20 .25
3426 @item Name             @tab Argument               @tab Return type       @tab Standard
3427 @item @code{DIM(X,Y)}  @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3428 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3429 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3430 @end multitable
3431 @end table
3432
3433
3434
3435 @node DOT_PRODUCT
3436 @section @code{DOT_PRODUCT} --- Dot product function
3437 @fnindex DOT_PRODUCT
3438 @cindex dot product
3439 @cindex vector product
3440 @cindex product, vector
3441
3442 @table @asis
3443 @item @emph{Description}:
3444 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3445 of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3446 either numeric or logical and must be arrays of rank one and of equal size. If
3447 the vectors are @code{INTEGER} or @code{REAL}, the result is
3448 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3449 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3450 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3451
3452 @item @emph{Standard}:
3453 Fortran 95 and later
3454
3455 @item @emph{Class}:
3456 Transformational function
3457
3458 @item @emph{Syntax}:
3459 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3460
3461 @item @emph{Arguments}:
3462 @multitable @columnfractions .15 .70
3463 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3464 @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.
3465 @end multitable
3466
3467 @item @emph{Return value}:
3468 If the arguments are numeric, the return value is a scalar of numeric type,
3469 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3470 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3471
3472 @item @emph{Example}:
3473 @smallexample
3474 program test_dot_prod
3475     integer, dimension(3) :: a, b
3476     a = (/ 1, 2, 3 /)
3477     b = (/ 4, 5, 6 /)
3478     print '(3i3)', a
3479     print *
3480     print '(3i3)', b
3481     print *
3482     print *, dot_product(a,b)
3483 end program test_dot_prod
3484 @end smallexample
3485 @end table
3486
3487
3488
3489 @node DPROD
3490 @section @code{DPROD} --- Double product function
3491 @fnindex DPROD
3492 @cindex product, double-precision
3493
3494 @table @asis
3495 @item @emph{Description}:
3496 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3497
3498 @item @emph{Standard}:
3499 Fortran 77 and later
3500
3501 @item @emph{Class}:
3502 Elemental function
3503
3504 @item @emph{Syntax}:
3505 @code{RESULT = DPROD(X, Y)}
3506
3507 @item @emph{Arguments}:
3508 @multitable @columnfractions .15 .70
3509 @item @var{X} @tab The type shall be @code{REAL}.
3510 @item @var{Y} @tab The type shall be @code{REAL}.
3511 @end multitable
3512
3513 @item @emph{Return value}:
3514 The return value is of type @code{REAL(8)}.
3515
3516 @item @emph{Example}:
3517 @smallexample
3518 program test_dprod
3519     real :: x = 5.2
3520     real :: y = 2.3
3521     real(8) :: d
3522     d = dprod(x,y)
3523     print *, d
3524 end program test_dprod
3525 @end smallexample
3526
3527 @item @emph{Specific names}:
3528 @multitable @columnfractions .20 .20 .20 .25
3529 @item Name              @tab Argument               @tab Return type       @tab Standard
3530 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3531 @end multitable
3532
3533 @end table
3534
3535
3536 @node DREAL
3537 @section @code{DREAL} --- Double real part function
3538 @fnindex DREAL
3539 @cindex complex numbers, real part
3540
3541 @table @asis
3542 @item @emph{Description}:
3543 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3544
3545 @item @emph{Standard}:
3546 GNU extension
3547
3548 @item @emph{Class}:
3549 Elemental function
3550
3551 @item @emph{Syntax}:
3552 @code{RESULT = DREAL(A)}
3553
3554 @item @emph{Arguments}:
3555 @multitable @columnfractions .15 .70
3556 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3557 @end multitable
3558
3559 @item @emph{Return value}:
3560 The return value is of type @code{REAL(8)}.
3561
3562 @item @emph{Example}:
3563 @smallexample
3564 program test_dreal
3565     complex(8) :: z = (1.3_8,7.2_8)
3566     print *, dreal(z)
3567 end program test_dreal
3568 @end smallexample
3569
3570 @item @emph{See also}:
3571 @ref{AIMAG}
3572
3573 @end table
3574
3575
3576
3577 @node DSHIFTL
3578 @section @code{DSHIFTL} --- Combined left shift
3579 @fnindex DSHIFTL
3580 @cindex left shift, combined
3581 @cindex shift, left
3582
3583 @table @asis
3584 @item @emph{Description}:
3585 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3586 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3587 bits of @var{J}, and the remaining bits are the rightmost bits of
3588 @var{I}.
3589
3590 @item @emph{Standard}:
3591 Fortran 2008 and later
3592
3593 @item @emph{Class}:
3594 Elemental function
3595
3596 @item @emph{Syntax}:
3597 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3598
3599 @item @emph{Arguments}:
3600 @multitable @columnfractions .15 .70
3601 @item @var{I} @tab Shall be of type @code{INTEGER}.
3602 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3603 as @var{I}.
3604 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3605 @end multitable
3606
3607 @item @emph{Return value}:
3608 The return value has same type and kind as @var{I}.
3609
3610 @item @emph{See also}:
3611 @ref{DSHIFTR}
3612
3613 @end table
3614
3615
3616
3617 @node DSHIFTR
3618 @section @code{DSHIFTR} --- Combined right shift
3619 @fnindex DSHIFTR
3620 @cindex right shift, combined
3621 @cindex shift, right
3622
3623 @table @asis
3624 @item @emph{Description}:
3625 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3626 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3627 bits of @var{I}, and the remaining bits are the leftmost bits of
3628 @var{J}.
3629
3630 @item @emph{Standard}:
3631 Fortran 2008 and later
3632
3633 @item @emph{Class}:
3634 Elemental function
3635
3636 @item @emph{Syntax}:
3637 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3638
3639 @item @emph{Arguments}:
3640 @multitable @columnfractions .15 .70
3641 @item @var{I} @tab Shall be of type @code{INTEGER}.
3642 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3643 as @var{I}.
3644 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3645 @end multitable
3646
3647 @item @emph{Return value}:
3648 The return value has same type and kind as @var{I}.
3649
3650 @item @emph{See also}:
3651 @ref{DSHIFTL}
3652
3653 @end table
3654
3655
3656
3657 @node DTIME
3658 @section @code{DTIME} --- Execution time subroutine (or function)
3659 @fnindex DTIME
3660 @cindex time, elapsed
3661 @cindex elapsed time
3662
3663 @table @asis
3664 @item @emph{Description}:
3665 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3666 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3667 returns the user and system components of this time in @code{VALUES(1)} and
3668 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3669 VALUES(2)}.
3670
3671 Subsequent invocations of @code{DTIME} return values accumulated since the
3672 previous invocation.
3673
3674 On some systems, the underlying timings are represented using types with
3675 sufficiently small limits that overflows (wrap around) are possible, such as
3676 32-bit types. Therefore, the values returned by this intrinsic might be, or
3677 become, negative, or numerically less than previous values, during a single
3678 run of the compiled program.
3679
3680 Please note, that this implementation is thread safe if used within OpenMP
3681 directives, i.e., its state will be consistent while called from multiple
3682 threads. However, if @code{DTIME} is called from multiple threads, the result
3683 is still the time since the last invocation. This may not give the intended
3684 results. If possible, use @code{CPU_TIME} instead.
3685
3686 This intrinsic is provided in both subroutine and function forms; however,
3687 only one form can be used in any given program unit.
3688
3689 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3690
3691 @multitable @columnfractions .15 .30 .40
3692 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3693 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3694 @item @tab @code{TIME}: @tab Run time since start in seconds.
3695 @end multitable
3696
3697 @item @emph{Standard}:
3698 GNU extension
3699
3700 @item @emph{Class}:
3701 Subroutine, function
3702
3703 @item @emph{Syntax}:
3704 @multitable @columnfractions .80
3705 @item @code{CALL DTIME(VALUES, TIME)}.
3706 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3707 @end multitable
3708
3709 @item @emph{Arguments}:
3710 @multitable @columnfractions .15 .70
3711 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3712 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3713 @end multitable
3714
3715 @item @emph{Return value}:
3716 Elapsed time in seconds since the last invocation or since the start of program
3717 execution if not called before.
3718
3719 @item @emph{Example}:
3720 @smallexample
3721 program test_dtime
3722     integer(8) :: i, j
3723     real, dimension(2) :: tarray
3724     real :: result
3725     call dtime(tarray, result)
3726     print *, result
3727     print *, tarray(1)
3728     print *, tarray(2)
3729     do i=1,100000000    ! Just a delay
3730         j = i * i - i
3731     end do
3732     call dtime(tarray, result)
3733     print *, result
3734     print *, tarray(1)
3735     print *, tarray(2)
3736 end program test_dtime
3737 @end smallexample
3738
3739 @item @emph{See also}:
3740 @ref{CPU_TIME}
3741
3742 @end table
3743
3744
3745
3746 @node EOSHIFT
3747 @section @code{EOSHIFT} --- End-off shift elements of an array
3748 @fnindex EOSHIFT
3749 @cindex array, shift
3750
3751 @table @asis
3752 @item @emph{Description}:
3753 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3754 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3755 omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
3756 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3757 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3758 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3759 then all complete rank one sections of @var{ARRAY} along the given dimension are
3760 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3761 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3762 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3763 following are copied in depending on the type of @var{ARRAY}.
3764
3765 @multitable @columnfractions .15 .80
3766 @item @emph{Array Type} @tab @emph{Boundary Value}
3767 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3768 @item Logical  @tab @code{.FALSE.}.
3769 @item Character(@var{len}) @tab @var{len} blanks.
3770 @end multitable
3771
3772 @item @emph{Standard}:
3773 Fortran 95 and later
3774
3775 @item @emph{Class}:
3776 Transformational function
3777
3778 @item @emph{Syntax}:
3779 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3780
3781 @item @emph{Arguments}:
3782 @multitable @columnfractions .15 .70
3783 @item @var{ARRAY}  @tab May be any type, not scalar.
3784 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3785 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3786 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3787 @end multitable
3788
3789 @item @emph{Return value}:
3790 Returns an array of same type and rank as the @var{ARRAY} argument.
3791
3792 @item @emph{Example}:
3793 @smallexample
3794 program test_eoshift
3795     integer, dimension(3,3) :: a
3796     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3797     print '(3i3)', a(1,:)
3798     print '(3i3)', a(2,:)
3799     print '(3i3)', a(3,:)
3800     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3801     print *
3802     print '(3i3)', a(1,:)
3803     print '(3i3)', a(2,:)
3804     print '(3i3)', a(3,:)
3805 end program test_eoshift
3806 @end smallexample
3807 @end table
3808
3809
3810
3811 @node EPSILON
3812 @section @code{EPSILON} --- Epsilon function
3813 @fnindex EPSILON
3814 @cindex model representation, epsilon
3815
3816 @table @asis
3817 @item @emph{Description}:
3818 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3819 as @var{X} such that @math{1 + E > 1}.
3820
3821 @item @emph{Standard}:
3822 Fortran 95 and later
3823
3824 @item @emph{Class}:
3825 Inquiry function
3826
3827 @item @emph{Syntax}:
3828 @code{RESULT = EPSILON(X)}
3829
3830 @item @emph{Arguments}:
3831 @multitable @columnfractions .15 .70
3832 @item @var{X} @tab The type shall be @code{REAL}.
3833 @end multitable
3834
3835 @item @emph{Return value}:
3836 The return value is of same type as the argument.
3837
3838 @item @emph{Example}:
3839 @smallexample
3840 program test_epsilon
3841     real :: x = 3.143
3842     real(8) :: y = 2.33
3843     print *, EPSILON(x)
3844     print *, EPSILON(y)
3845 end program test_epsilon
3846 @end smallexample
3847 @end table
3848
3849
3850
3851 @node ERF
3852 @section @code{ERF} --- Error function
3853 @fnindex ERF
3854 @cindex error function
3855
3856 @table @asis
3857 @item @emph{Description}:
3858 @code{ERF(X)} computes the error function of @var{X}.
3859
3860 @item @emph{Standard}:
3861 Fortran 2008 and later
3862
3863 @item @emph{Class}:
3864 Elemental function
3865
3866 @item @emph{Syntax}:
3867 @code{RESULT = ERF(X)}
3868
3869 @item @emph{Arguments}:
3870 @multitable @columnfractions .15 .70
3871 @item @var{X} @tab The type shall be @code{REAL}.
3872 @end multitable
3873
3874 @item @emph{Return value}:
3875 The return value is of type @code{REAL}, of the same kind as
3876 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3877
3878 @item @emph{Example}:
3879 @smallexample
3880 program test_erf
3881   real(8) :: x = 0.17_8
3882   x = erf(x)
3883 end program test_erf
3884 @end smallexample
3885
3886 @item @emph{Specific names}:
3887 @multitable @columnfractions .20 .20 .20 .25
3888 @item Name            @tab Argument          @tab Return type       @tab Standard
3889 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3890 @end multitable
3891 @end table
3892
3893
3894
3895 @node ERFC
3896 @section @code{ERFC} --- Error function
3897 @fnindex ERFC
3898 @cindex error function, complementary
3899
3900 @table @asis
3901 @item @emph{Description}:
3902 @code{ERFC(X)} computes the complementary error function of @var{X}.
3903
3904 @item @emph{Standard}:
3905 Fortran 2008 and later
3906
3907 @item @emph{Class}:
3908 Elemental function
3909
3910 @item @emph{Syntax}:
3911 @code{RESULT = ERFC(X)}
3912
3913 @item @emph{Arguments}:
3914 @multitable @columnfractions .15 .70
3915 @item @var{X} @tab The type shall be @code{REAL}.
3916 @end multitable
3917
3918 @item @emph{Return value}:
3919 The return value is of type @code{REAL} and of the same kind as @var{X}.
3920 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3921
3922 @item @emph{Example}:
3923 @smallexample
3924 program test_erfc
3925   real(8) :: x = 0.17_8
3926   x = erfc(x)
3927 end program test_erfc
3928 @end smallexample
3929
3930 @item @emph{Specific names}:
3931 @multitable @columnfractions .20 .20 .20 .25
3932 @item Name            @tab Argument          @tab Return type       @tab Standard
3933 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3934 @end multitable
3935 @end table
3936
3937
3938
3939 @node ERFC_SCALED
3940 @section @code{ERFC_SCALED} --- Error function
3941 @fnindex ERFC_SCALED
3942 @cindex error function, complementary, exponentially-scaled
3943
3944 @table @asis
3945 @item @emph{Description}:
3946 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3947 error function of @var{X}.
3948
3949 @item @emph{Standard}:
3950 Fortran 2008 and later
3951
3952 @item @emph{Class}:
3953 Elemental function
3954
3955 @item @emph{Syntax}:
3956 @code{RESULT = ERFC_SCALED(X)}
3957
3958 @item @emph{Arguments}:
3959 @multitable @columnfractions .15 .70
3960 @item @var{X} @tab The type shall be @code{REAL}.
3961 @end multitable
3962
3963 @item @emph{Return value}:
3964 The return value is of type @code{REAL} and of the same kind as @var{X}.
3965
3966 @item @emph{Example}:
3967 @smallexample
3968 program test_erfc_scaled
3969   real(8) :: x = 0.17_8
3970   x = erfc_scaled(x)
3971 end program test_erfc_scaled
3972 @end smallexample
3973 @end table
3974
3975
3976
3977 @node ETIME
3978 @section @code{ETIME} --- Execution time subroutine (or function)
3979 @fnindex ETIME
3980 @cindex time, elapsed
3981
3982 @table @asis
3983 @item @emph{Description}:
3984 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3985 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3986 returns the user and system components of this time in @code{VALUES(1)} and
3987 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3988
3989 On some systems, the underlying timings are represented using types with
3990 sufficiently small limits that overflows (wrap around) are possible, such as
3991 32-bit types. Therefore, the values returned by this intrinsic might be, or
3992 become, negative, or numerically less than previous values, during a single
3993 run of the compiled program.
3994
3995 This intrinsic is provided in both subroutine and function forms; however,
3996 only one form can be used in any given program unit.
3997
3998 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3999
4000 @multitable @columnfractions .15 .30 .60
4001 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4002 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4003 @item @tab @code{TIME}: @tab Run time since start in seconds.
4004 @end multitable
4005
4006 @item @emph{Standard}:
4007 GNU extension
4008
4009 @item @emph{Class}:
4010 Subroutine, function
4011
4012 @item @emph{Syntax}:
4013 @multitable @columnfractions .80
4014 @item @code{CALL ETIME(VALUES, TIME)}.
4015 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4016 @end multitable
4017
4018 @item @emph{Arguments}:
4019 @multitable @columnfractions .15 .70
4020 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4021 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4022 @end multitable
4023
4024 @item @emph{Return value}:
4025 Elapsed time in seconds since the start of program execution.
4026
4027 @item @emph{Example}:
4028 @smallexample
4029 program test_etime
4030     integer(8) :: i, j
4031     real, dimension(2) :: tarray
4032     real :: result
4033     call ETIME(tarray, result)
4034     print *, result
4035     print *, tarray(1)
4036     print *, tarray(2)
4037     do i=1,100000000    ! Just a delay
4038         j = i * i - i
4039     end do
4040     call ETIME(tarray, result)
4041     print *, result
4042     print *, tarray(1)
4043     print *, tarray(2)
4044 end program test_etime
4045 @end smallexample
4046
4047 @item @emph{See also}:
4048 @ref{CPU_TIME}
4049
4050 @end table
4051
4052
4053
4054 @node EXECUTE_COMMAND_LINE
4055 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4056 @fnindex EXECUTE_COMMAND_LINE
4057 @cindex system, system call
4058 @cindex command line
4059
4060 @table @asis
4061 @item @emph{Description}:
4062 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4063 asynchronously.
4064
4065 The @code{COMMAND} argument is passed to the shell and executed, using
4066 the C library's @code{system()} call.  (The shell is @code{sh} on Unix
4067 systems, and @code{cmd.exe} on Windows.)  If @code{WAIT} is present and
4068 has the value false, the execution of the command is asynchronous if the
4069 system supports it; otherwise, the command is executed synchronously.
4070
4071 The three last arguments allow the user to get status information.  After
4072 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4073 the command, as returned by @code{system}.  @code{CMDSTAT} is set to zero
4074 if the command line was executed (whatever its exit status was).
4075 @code{CMDMSG} is assigned an error message if an error has occurred.
4076
4077
4078 @item @emph{Standard}:
4079 Fortran 2008 and later
4080
4081 @item @emph{Class}:
4082 Subroutine
4083
4084 @item @emph{Syntax}:
4085 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4086
4087 @item @emph{Arguments}:
4088 @multitable @columnfractions .15 .70
4089 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4090 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4091 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4092 default kind.
4093 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4094 default kind.
4095 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4096 default kind.
4097 @end multitable
4098
4099 @item @emph{Example}:
4100 @smallexample
4101 program test_exec
4102   integer :: i
4103
4104   call execute_command_line ("external_prog.exe", exitstat=i)
4105   print *, "Exit status of external_prog.exe was ", i
4106
4107   call execute_command_line ("reindex_files.exe", wait=.false.)
4108   print *, "Now reindexing files in the background"
4109
4110 end program test_exec
4111 @end smallexample
4112
4113
4114 @item @emph{Note}:
4115
4116 Because this intrinsic is implemented in terms of the @code{system()}
4117 function call, its behavior with respect to signaling is processor
4118 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4119 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4120 such, if the parent process is terminated, the child process might not be
4121 terminated alongside.
4122
4123
4124 @item @emph{See also}:
4125 @ref{SYSTEM}
4126 @end table
4127
4128
4129
4130 @node EXIT
4131 @section @code{EXIT} --- Exit the program with status.
4132 @fnindex EXIT
4133 @cindex program termination
4134 @cindex terminate program
4135
4136 @table @asis
4137 @item @emph{Description}:
4138 @code{EXIT} causes immediate termination of the program with status.  If status
4139 is omitted it returns the canonical @emph{success} for the system.  All Fortran
4140 I/O units are closed.
4141
4142 @item @emph{Standard}:
4143 GNU extension
4144
4145 @item @emph{Class}:
4146 Subroutine
4147
4148 @item @emph{Syntax}:
4149 @code{CALL EXIT([STATUS])}
4150
4151 @item @emph{Arguments}:
4152 @multitable @columnfractions .15 .70
4153 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4154 @end multitable
4155
4156 @item @emph{Return value}:
4157 @code{STATUS} is passed to the parent process on exit.
4158
4159 @item @emph{Example}:
4160 @smallexample
4161 program test_exit
4162   integer :: STATUS = 0
4163   print *, 'This program is going to exit.'
4164   call EXIT(STATUS)
4165 end program test_exit
4166 @end smallexample
4167
4168 @item @emph{See also}:
4169 @ref{ABORT}, @ref{KILL}
4170 @end table
4171
4172
4173
4174 @node EXP
4175 @section @code{EXP} --- Exponential function
4176 @fnindex EXP
4177 @fnindex DEXP
4178 @fnindex CEXP
4179 @fnindex ZEXP
4180 @fnindex CDEXP
4181 @cindex exponential function
4182 @cindex logarithmic function, inverse
4183
4184 @table @asis
4185 @item @emph{Description}:
4186 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4187
4188 @item @emph{Standard}:
4189 Fortran 77 and later, has overloads that are GNU extensions
4190
4191 @item @emph{Class}:
4192 Elemental function
4193
4194 @item @emph{Syntax}:
4195 @code{RESULT = EXP(X)}
4196
4197 @item @emph{Arguments}:
4198 @multitable @columnfractions .15 .70
4199 @item @var{X} @tab The type shall be @code{REAL} or
4200 @code{COMPLEX}.
4201 @end multitable
4202
4203 @item @emph{Return value}:
4204 The return value has same type and kind as @var{X}.
4205
4206 @item @emph{Example}:
4207 @smallexample
4208 program test_exp
4209   real :: x = 1.0
4210   x = exp(x)
4211 end program test_exp
4212 @end smallexample
4213
4214 @item @emph{Specific names}:
4215 @multitable @columnfractions .20 .20 .20 .25
4216 @item Name            @tab Argument             @tab Return type         @tab Standard
4217 @item @code{EXP(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}      @tab Fortran 77 and later
4218 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
4219 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
4220 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4221 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4222 @end multitable
4223 @end table
4224
4225
4226
4227 @node EXPONENT
4228 @section @code{EXPONENT} --- Exponent function
4229 @fnindex EXPONENT
4230 @cindex real number, exponent
4231 @cindex floating point, exponent
4232
4233 @table @asis
4234 @item @emph{Description}:
4235 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4236 is zero the value returned is zero.
4237
4238 @item @emph{Standard}:
4239 Fortran 95 and later
4240
4241 @item @emph{Class}:
4242 Elemental function
4243
4244 @item @emph{Syntax}:
4245 @code{RESULT = EXPONENT(X)}
4246
4247 @item @emph{Arguments}:
4248 @multitable @columnfractions .15 .70
4249 @item @var{X} @tab The type shall be @code{REAL}.
4250 @end multitable
4251
4252 @item @emph{Return value}:
4253 The return value is of type default @code{INTEGER}.
4254
4255 @item @emph{Example}:
4256 @smallexample
4257 program test_exponent
4258   real :: x = 1.0
4259   integer :: i
4260   i = exponent(x)
4261   print *, i
4262   print *, exponent(0.0)
4263 end program test_exponent
4264 @end smallexample
4265 @end table
4266
4267
4268
4269 @node EXTENDS_TYPE_OF
4270 @section @code{EXTENDS_TYPE_OF} ---  Query dynamic type for extension
4271 @fnindex EXTENDS_TYPE_OF
4272
4273 @table @asis
4274 @item @emph{Description}:
4275 Query dynamic type for extension.
4276
4277 @item @emph{Standard}:
4278 Fortran 2003 and later
4279
4280 @item @emph{Class}:
4281 Inquiry function
4282
4283 @item @emph{Syntax}:
4284 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4285
4286 @item @emph{Arguments}:
4287 @multitable @columnfractions .15 .70
4288 @item @var{A} @tab Shall be an object of extensible declared type or
4289 unlimited polymorphic.
4290 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4291 unlimited polymorphic.
4292 @end multitable
4293
4294 @item @emph{Return value}:
4295 The return value is a scalar of type default logical. It is true if and only if
4296 the dynamic type of A is an extension type of the dynamic type of MOLD.
4297
4298
4299 @item @emph{See also}:
4300 @ref{SAME_TYPE_AS}
4301 @end table
4302
4303
4304
4305 @node FDATE
4306 @section @code{FDATE} --- Get the current time as a string
4307 @fnindex FDATE
4308 @cindex time, current
4309 @cindex current time
4310 @cindex date, current
4311 @cindex current date
4312
4313 @table @asis
4314 @item @emph{Description}:
4315 @code{FDATE(DATE)} returns the current date (using the same format as
4316 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4317 TIME())}.
4318
4319 This intrinsic is provided in both subroutine and function forms; however,
4320 only one form can be used in any given program unit.
4321
4322 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
4323 default kind.
4324
4325 @item @emph{Standard}:
4326 GNU extension
4327
4328 @item @emph{Class}:
4329 Subroutine, function
4330
4331 @item @emph{Syntax}:
4332 @multitable @columnfractions .80
4333 @item @code{CALL FDATE(DATE)}.
4334 @item @code{DATE = FDATE()}, (not recommended).
4335 @end multitable
4336
4337 @item @emph{Arguments}:
4338 @multitable @columnfractions .15 .70
4339 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4340 default kind
4341 @end multitable
4342
4343 @item @emph{Return value}:
4344 The current date as a string.
4345
4346 @item @emph{Example}:
4347 @smallexample
4348 program test_fdate
4349     integer(8) :: i, j
4350     character(len=30) :: date
4351     call fdate(date)
4352     print *, 'Program started on ', date
4353     do i = 1, 100000000 ! Just a delay
4354         j = i * i - i
4355     end do
4356     call fdate(date)
4357     print *, 'Program ended on ', date
4358 end program test_fdate
4359 @end smallexample
4360 @end table
4361
4362
4363
4364 @node FGET
4365 @section @code{FGET} --- Read a single character in stream mode from stdin
4366 @fnindex FGET
4367 @cindex read character, stream mode
4368 @cindex stream mode, read character
4369 @cindex file operation, read character
4370
4371 @table @asis
4372 @item @emph{Description}:
4373 Read a single character in stream mode from stdin by bypassing normal
4374 formatted output. Stream I/O should not be mixed with normal record-oriented
4375 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4376
4377 This intrinsic is provided in both subroutine and function forms; however,
4378 only one form can be used in any given program unit.
4379
4380 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4381 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4382 Programmers should consider the use of new stream IO feature in new code
4383 for future portability. See also @ref{Fortran 2003 status}.
4384
4385 @item @emph{Standard}:
4386 GNU extension
4387
4388 @item @emph{Class}:
4389 Subroutine, function
4390
4391 @item @emph{Syntax}:
4392 @multitable @columnfractions .80
4393 @item @code{CALL FGET(C [, STATUS])}
4394 @item @code{STATUS = FGET(C)}
4395 @end multitable
4396
4397 @item @emph{Arguments}:
4398 @multitable @columnfractions .15 .70
4399 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4400 kind.
4401 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4402 Returns 0 on success, -1 on end-of-file, and a system specific positive
4403 error code otherwise.
4404 @end multitable
4405
4406 @item @emph{Example}:
4407 @smallexample
4408 PROGRAM test_fget
4409   INTEGER, PARAMETER :: strlen = 100
4410   INTEGER :: status, i = 1
4411   CHARACTER(len=strlen) :: str = ""
4412
4413   WRITE (*,*) 'Enter text:'
4414   DO
4415     CALL fget(str(i:i), status)
4416     if (status /= 0 .OR. i > strlen) exit
4417     i = i + 1
4418   END DO
4419   WRITE (*,*) TRIM(str)
4420 END PROGRAM
4421 @end smallexample
4422
4423 @item @emph{See also}:
4424 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4425 @end table
4426
4427
4428
4429 @node FGETC
4430 @section @code{FGETC} --- Read a single character in stream mode
4431 @fnindex FGETC
4432 @cindex read character, stream mode
4433 @cindex stream mode, read character
4434 @cindex file operation, read character
4435
4436 @table @asis
4437 @item @emph{Description}:
4438 Read a single character in stream mode by bypassing normal formatted output.
4439 Stream I/O should not be mixed with normal record-oriented (formatted or
4440 unformatted) I/O on the same unit; the results are unpredictable.
4441
4442 This intrinsic is provided in both subroutine and function forms; however,
4443 only one form can be used in any given program unit.
4444
4445 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4446 with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4447 Programmers should consider the use of new stream IO feature in new code
4448 for future portability. See also @ref{Fortran 2003 status}.
4449
4450 @item @emph{Standard}:
4451 GNU extension
4452
4453 @item @emph{Class}:
4454 Subroutine, function
4455
4456 @item @emph{Syntax}:
4457 @multitable @columnfractions .80
4458 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4459 @item @code{STATUS = FGETC(UNIT, C)}
4460 @end multitable
4461
4462 @item @emph{Arguments}:
4463 @multitable @columnfractions .15 .70
4464 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4465 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4466 kind.
4467 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4468 Returns 0 on success, -1 on end-of-file and a system specific positive
4469 error code otherwise.
4470 @end multitable
4471
4472 @item @emph{Example}:
4473 @smallexample
4474 PROGRAM test_fgetc
4475   INTEGER :: fd = 42, status
4476   CHARACTER :: c
4477
4478   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4479   DO
4480     CALL fgetc(fd, c, status)
4481     IF (status /= 0) EXIT
4482     call fput(c)
4483   END DO
4484   CLOSE(UNIT=fd)
4485 END PROGRAM
4486 @end smallexample
4487
4488 @item @emph{See also}:
4489 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4490 @end table
4491
4492
4493
4494 @node FLOOR
4495 @section @code{FLOOR} --- Integer floor function
4496 @fnindex FLOOR
4497 @cindex floor
4498 @cindex rounding, floor
4499
4500 @table @asis
4501 @item @emph{Description}:
4502 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4503
4504 @item @emph{Standard}:
4505 Fortran 95 and later
4506
4507 @item @emph{Class}:
4508 Elemental function
4509
4510 @item @emph{Syntax}:
4511 @code{RESULT = FLOOR(A [, KIND])}
4512
4513 @item @emph{Arguments}:
4514 @multitable @columnfractions .15 .70
4515 @item @var{A} @tab The type shall be @code{REAL}.
4516 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4517 expression indicating the kind parameter of the result.
4518 @end multitable
4519
4520 @item @emph{Return value}:
4521 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4522 and of default-kind @code{INTEGER} otherwise.
4523
4524 @item @emph{Example}:
4525 @smallexample
4526 program test_floor
4527     real :: x = 63.29
4528     real :: y = -63.59
4529     print *, floor(x) ! returns 63
4530     print *, floor(y) ! returns -64
4531 end program test_floor
4532 @end smallexample
4533
4534 @item @emph{See also}:
4535 @ref{CEILING}, @ref{NINT}
4536
4537 @end table
4538
4539
4540
4541 @node FLUSH
4542 @section @code{FLUSH} --- Flush I/O unit(s)
4543 @fnindex FLUSH
4544 @cindex file operation, flush
4545
4546 @table @asis
4547 @item @emph{Description}:
4548 Flushes Fortran unit(s) currently open for output. Without the optional
4549 argument, all units are flushed, otherwise just the unit specified.
4550
4551 @item @emph{Standard}:
4552 GNU extension
4553
4554 @item @emph{Class}:
4555 Subroutine
4556
4557 @item @emph{Syntax}:
4558 @code{CALL FLUSH(UNIT)}
4559
4560 @item @emph{Arguments}:
4561 @multitable @columnfractions .15 .70
4562 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4563 @end multitable
4564
4565 @item @emph{Note}:
4566 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4567 statement that should be preferred over the @code{FLUSH} intrinsic.
4568
4569 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4570 have identical effect: they flush the runtime library's I/O buffer so
4571 that the data becomes visible to other processes. This does not guarantee
4572 that the data is committed to disk.
4573
4574 On POSIX systems, you can request that all data is transferred  to  the
4575 storage device by calling the @code{fsync} function, with the POSIX file
4576 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4577 @code{FNUM}). The following example shows how:
4578
4579 @smallexample
4580   ! Declare the interface for POSIX fsync function
4581   interface
4582     function fsync (fd) bind(c,name="fsync")
4583     use iso_c_binding, only: c_int
4584       integer(c_int), value :: fd
4585       integer(c_int) :: fsync
4586     end function fsync
4587   end interface
4588
4589   ! Variable declaration
4590   integer :: ret
4591
4592   ! Opening unit 10
4593   open (10,file="foo")
4594
4595   ! ...
4596   ! Perform I/O on unit 10
4597   ! ...
4598
4599   ! Flush and sync
4600   flush(10)
4601   ret = fsync(fnum(10))
4602
4603   ! Handle possible error
4604   if (ret /= 0) stop "Error calling FSYNC"
4605 @end smallexample
4606
4607 @end table
4608
4609
4610
4611 @node FNUM
4612 @section @code{FNUM} --- File number function
4613 @fnindex FNUM
4614 @cindex file operation, file number
4615
4616 @table @asis
4617 @item @emph{Description}:
4618 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4619 open Fortran I/O unit @code{UNIT}.
4620
4621 @item @emph{Standard}:
4622 GNU extension
4623
4624 @item @emph{Class}:
4625 Function
4626
4627 @item @emph{Syntax}:
4628 @code{RESULT = FNUM(UNIT)}
4629
4630 @item @emph{Arguments}:
4631 @multitable @columnfractions .15 .70
4632 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4633 @end multitable
4634
4635 @item @emph{Return value}:
4636 The return value is of type @code{INTEGER}
4637
4638 @item @emph{Example}:
4639 @smallexample
4640 program test_fnum
4641   integer :: i
4642   open (unit=10, status = "scratch")
4643   i = fnum(10)
4644   print *, i
4645   close (10)
4646 end program test_fnum
4647 @end smallexample
4648 @end table
4649
4650
4651
4652 @node FPUT
4653 @section @code{FPUT} --- Write a single character in stream mode to stdout
4654 @fnindex FPUT
4655 @cindex write character, stream mode
4656 @cindex stream mode, write character
4657 @cindex file operation, write character
4658
4659 @table @asis
4660 @item @emph{Description}:
4661 Write a single character in stream mode to stdout by bypassing normal
4662 formatted output. Stream I/O should not be mixed with normal record-oriented
4663 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4664
4665 This intrinsic is provided in both subroutine and function forms; however,
4666 only one form can be used in any given program unit.
4667
4668 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4669 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4670 Programmers should consider the use of new stream IO feature in new code
4671 for future portability. See also @ref{Fortran 2003 status}.
4672
4673 @item @emph{Standard}:
4674 GNU extension
4675
4676 @item @emph{Class}:
4677 Subroutine, function
4678
4679 @item @emph{Syntax}:
4680 @multitable @columnfractions .80
4681 @item @code{CALL FPUT(C [, STATUS])}
4682 @item @code{STATUS = FPUT(C)}
4683 @end multitable
4684
4685 @item @emph{Arguments}:
4686 @multitable @columnfractions .15 .70
4687 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4688 kind.
4689 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4690 Returns 0 on success, -1 on end-of-file and a system specific positive
4691 error code otherwise.
4692 @end multitable
4693
4694 @item @emph{Example}:
4695 @smallexample
4696 PROGRAM test_fput
4697   CHARACTER(len=10) :: str = "gfortran"
4698   INTEGER :: i
4699   DO i = 1, len_trim(str)
4700     CALL fput(str(i:i))
4701   END DO
4702 END PROGRAM
4703 @end smallexample
4704
4705 @item @emph{See also}:
4706 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4707 @end table
4708
4709
4710
4711 @node FPUTC
4712 @section @code{FPUTC} --- Write a single character in stream mode
4713 @fnindex FPUTC
4714 @cindex write character, stream mode
4715 @cindex stream mode, write character
4716 @cindex file operation, write character
4717
4718 @table @asis
4719 @item @emph{Description}:
4720 Write a single character in stream mode by bypassing normal formatted
4721 output. Stream I/O should not be mixed with normal record-oriented
4722 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4723
4724 This intrinsic is provided in both subroutine and function forms; however,
4725 only one form can be used in any given program unit.
4726
4727 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4728 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4729 Programmers should consider the use of new stream IO feature in new code
4730 for future portability. See also @ref{Fortran 2003 status}.
4731
4732 @item @emph{Standard}:
4733 GNU extension
4734
4735 @item @emph{Class}:
4736 Subroutine, function
4737
4738 @item @emph{Syntax}:
4739 @multitable @columnfractions .80
4740 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4741 @item @code{STATUS = FPUTC(UNIT, C)}
4742 @end multitable
4743
4744 @item @emph{Arguments}:
4745 @multitable @columnfractions .15 .70
4746 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4747 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4748 kind.
4749 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4750 Returns 0 on success, -1 on end-of-file and a system specific positive
4751 error code otherwise.
4752 @end multitable
4753
4754 @item @emph{Example}:
4755 @smallexample
4756 PROGRAM test_fputc
4757   CHARACTER(len=10) :: str = "gfortran"
4758   INTEGER :: fd = 42, i
4759
4760   OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4761   DO i = 1, len_trim(str)
4762     CALL fputc(fd, str(i:i))
4763   END DO
4764   CLOSE(fd)
4765 END PROGRAM
4766 @end smallexample
4767
4768 @item @emph{See also}:
4769 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4770 @end table
4771
4772
4773
4774 @node FRACTION
4775 @section @code{FRACTION} --- Fractional part of the model representation
4776 @fnindex FRACTION
4777 @cindex real number, fraction
4778 @cindex floating point, fraction
4779
4780 @table @asis
4781 @item @emph{Description}:
4782 @code{FRACTION(X)} returns the fractional part of the model
4783 representation of @code{X}.
4784
4785 @item @emph{Standard}:
4786 Fortran 95 and later
4787
4788 @item @emph{Class}:
4789 Elemental function
4790
4791 @item @emph{Syntax}:
4792 @code{Y = FRACTION(X)}
4793
4794 @item @emph{Arguments}:
4795 @multitable @columnfractions .15 .70
4796 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4797 @end multitable
4798
4799 @item @emph{Return value}:
4800 The return value is of the same type and kind as the argument.
4801 The fractional part of the model representation of @code{X} is returned;
4802 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4803
4804 @item @emph{Example}:
4805 @smallexample
4806 program test_fraction
4807   real :: x
4808   x = 178.1387e-4
4809   print *, fraction(x), x * radix(x)**(-exponent(x))
4810 end program test_fraction
4811 @end smallexample
4812
4813 @end table
4814
4815
4816
4817 @node FREE
4818 @section @code{FREE} --- Frees memory
4819 @fnindex FREE
4820 @cindex pointer, cray
4821
4822 @table @asis
4823 @item @emph{Description}:
4824 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4825 intrinsic is an extension intended to be used with Cray pointers, and is
4826 provided in GNU Fortran to allow user to compile legacy code. For
4827 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4828 @code{DEALLOCATE}.
4829
4830 @item @emph{Standard}:
4831 GNU extension
4832
4833 @item @emph{Class}:
4834 Subroutine
4835
4836 @item @emph{Syntax}:
4837 @code{CALL FREE(PTR)}
4838
4839 @item @emph{Arguments}:
4840 @multitable @columnfractions .15 .70
4841 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4842 location of the memory that should be de-allocated.
4843 @end multitable
4844
4845 @item @emph{Return value}:
4846 None
4847
4848 @item @emph{Example}:
4849 See @code{MALLOC} for an example.
4850
4851 @item @emph{See also}:
4852 @ref{MALLOC}
4853 @end table
4854
4855
4856
4857 @node FSEEK
4858 @section @code{FSEEK} --- Low level file positioning subroutine
4859 @fnindex FSEEK
4860 @cindex file operation, seek
4861 @cindex file operation, position
4862
4863 @table @asis
4864 @item @emph{Description}:
4865 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4866 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4867 if set to 1, @var{OFFSET} is taken to be relative to the current position
4868 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4869 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4870 fails silently.
4871
4872 This intrinsic routine is not fully backwards compatible with @command{g77}.
4873 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4874 @var{STATUS} variable. If FSEEK is used in old code, change
4875 @smallexample
4876   CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4877 @end smallexample
4878 to
4879 @smallexample
4880   INTEGER :: status
4881   CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4882   IF (status /= 0) GOTO label
4883 @end smallexample
4884
4885 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4886 Programmers should consider the use of new stream IO feature in new code
4887 for future portability. See also @ref{Fortran 2003 status}.
4888
4889 @item @emph{Standard}:
4890 GNU extension
4891
4892 @item @emph{Class}:
4893 Subroutine
4894
4895 @item @emph{Syntax}:
4896 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4897
4898 @item @emph{Arguments}:
4899 @multitable @columnfractions .15 .70
4900 @item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
4901 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4902 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4903 Its value shall be either 0, 1 or 2.
4904 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4905 @code{INTEGER(4)}.
4906 @end multitable
4907
4908 @item @emph{Example}:
4909 @smallexample
4910 PROGRAM test_fseek
4911   INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4912   INTEGER :: fd, offset, ierr
4913
4914   ierr   = 0
4915   offset = 5
4916   fd     = 10
4917
4918   OPEN(UNIT=fd, FILE="fseek.test")
4919   CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
4920   print *, FTELL(fd), ierr
4921
4922   CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
4923   print *, FTELL(fd), ierr
4924
4925   CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
4926   print *, FTELL(fd), ierr
4927
4928   CLOSE(UNIT=fd)
4929 END PROGRAM
4930 @end smallexample
4931
4932 @item @emph{See also}:
4933 @ref{FTELL}
4934 @end table
4935
4936
4937
4938 @node FSTAT
4939 @section @code{FSTAT} --- Get file status
4940 @fnindex FSTAT
4941 @cindex file system, file status
4942
4943 @table @asis
4944 @item @emph{Description}:
4945 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4946 already opened file is obtained.
4947
4948 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4949
4950 This intrinsic is provided in both subroutine and function forms; however,
4951 only one form can be used in any given program unit.
4952
4953 @item @emph{Standard}:
4954 GNU extension
4955
4956 @item @emph{Class}:
4957 Subroutine, function
4958
4959 @item @emph{Syntax}:
4960 @multitable @columnfractions .80
4961 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4962 @item @code{STATUS = FSTAT(UNIT, VALUES)}
4963 @end multitable
4964
4965 @item @emph{Arguments}:
4966 @multitable @columnfractions .15 .70
4967 @item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
4968 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4969 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4970 on success and a system specific error code otherwise.
4971 @end multitable
4972
4973 @item @emph{Example}:
4974 See @ref{STAT} for an example.
4975
4976 @item @emph{See also}:
4977 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4978 @end table
4979
4980
4981
4982 @node FTELL
4983 @section @code{FTELL} --- Current stream position
4984 @fnindex FTELL
4985 @cindex file operation, position
4986
4987 @table @asis
4988 @item @emph{Description}:
4989 Retrieves the current position within an open file.
4990
4991 This intrinsic is provided in both subroutine and function forms; however,
4992 only one form can be used in any given program unit.
4993
4994 @item @emph{Standard}:
4995 GNU extension
4996
4997 @item @emph{Class}:
4998 Subroutine, function
4999
5000 @item @emph{Syntax}:
5001 @multitable @columnfractions .80
5002 @item @code{CALL FTELL(UNIT, OFFSET)}
5003 @item @code{OFFSET = FTELL(UNIT)}
5004 @end multitable
5005
5006 @item @emph{Arguments}:
5007 @multitable @columnfractions .15 .70
5008 @item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
5009 @item @var{UNIT}    @tab Shall of type @code{INTEGER}.
5010 @end multitable
5011
5012 @item @emph{Return value}:
5013 In either syntax, @var{OFFSET} is set to the current offset of unit
5014 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5015
5016 @item @emph{Example}:
5017 @smallexample
5018 PROGRAM test_ftell
5019   INTEGER :: i
5020   OPEN(10, FILE="temp.dat")
5021   CALL ftell(10,i)
5022   WRITE(*,*) i
5023 END PROGRAM
5024 @end smallexample
5025
5026 @item @emph{See also}:
5027 @ref{FSEEK}
5028 @end table
5029
5030
5031
5032 @node GAMMA
5033 @section @code{GAMMA} --- Gamma function
5034 @fnindex GAMMA
5035 @fnindex DGAMMA
5036 @cindex Gamma function
5037 @cindex Factorial function
5038
5039 @table @asis
5040 @item @emph{Description}:
5041 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5042 integer values of @var{X} the Gamma function simplifies to the factorial
5043 function @math{\Gamma(x)=(x-1)!}.
5044
5045 @tex
5046 $$
5047 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5048 $$
5049 @end tex
5050
5051 @item @emph{Standard}:
5052 Fortran 2008 and later
5053
5054 @item @emph{Class}:
5055 Elemental function
5056
5057 @item @emph{Syntax}:
5058 @code{X = GAMMA(X)}
5059
5060 @item @emph{Arguments}:
5061 @multitable @columnfractions .15 .70
5062 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5063 nor a negative integer.
5064 @end multitable
5065
5066 @item @emph{Return value}:
5067 The return value is of type @code{REAL} of the same kind as @var{X}.
5068
5069 @item @emph{Example}:
5070 @smallexample
5071 program test_gamma
5072   real :: x = 1.0
5073   x = gamma(x) ! returns 1.0
5074 end program test_gamma
5075 @end smallexample
5076
5077 @item @emph{Specific names}:
5078 @multitable @columnfractions .20 .20 .20 .25
5079 @item Name             @tab Argument         @tab Return type       @tab Standard
5080 @item @code{GAMMA(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
5081 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
5082 @end multitable
5083
5084 @item @emph{See also}:
5085 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5086
5087 @end table
5088
5089
5090
5091 @node GERROR
5092 @section @code{GERROR} --- Get last system error message
5093 @fnindex GERROR
5094 @cindex system, error handling
5095
5096 @table @asis
5097 @item @emph{Description}:
5098 Returns the system error message corresponding to the last system error.
5099 This resembles the functionality of @code{strerror(3)} in C.
5100
5101 @item @emph{Standard}:
5102 GNU extension
5103
5104 @item @emph{Class}:
5105 Subroutine
5106
5107 @item @emph{Syntax}:
5108 @code{CALL GERROR(RESULT)}
5109
5110 @item @emph{Arguments}:
5111 @multitable @columnfractions .15 .70
5112 @item @var{RESULT}  @tab Shall of type @code{CHARACTER} and of default
5113 @end multitable
5114
5115 @item @emph{Example}:
5116 @smallexample
5117 PROGRAM test_gerror
5118   CHARACTER(len=100) :: msg
5119   CALL gerror(msg)
5120   WRITE(*,*) msg
5121 END PROGRAM
5122 @end smallexample
5123
5124 @item @emph{See also}:
5125 @ref{IERRNO}, @ref{PERROR}
5126 @end table
5127
5128
5129
5130 @node GETARG
5131 @section @code{GETARG} --- Get command line arguments
5132 @fnindex GETARG
5133 @cindex command-line arguments
5134 @cindex arguments, to program
5135
5136 @table @asis
5137 @item @emph{Description}:
5138 Retrieve the @var{POS}-th argument that was passed on the
5139 command line when the containing program was invoked.
5140
5141 This intrinsic routine is provided for backwards compatibility with
5142 GNU Fortran 77.  In new code, programmers should consider the use of
5143 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5144 standard.
5145
5146 @item @emph{Standard}:
5147 GNU extension
5148
5149 @item @emph{Class}:
5150 Subroutine
5151
5152 @item @emph{Syntax}:
5153 @code{CALL GETARG(POS, VALUE)}
5154
5155 @item @emph{Arguments}:
5156 @multitable @columnfractions .15 .70
5157 @item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
5158 the default integer kind; @math{@var{POS} \geq 0}
5159 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5160 kind.
5161 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5162 @end multitable
5163
5164 @item @emph{Return value}:
5165 After @code{GETARG} returns, the @var{VALUE} argument holds the
5166 @var{POS}th command line argument. If @var{VALUE} can not hold the
5167 argument, it is truncated to fit the length of @var{VALUE}. If there are
5168 less than @var{POS} arguments specified at the command line, @var{VALUE}
5169 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5170 to the name of the program (on systems that support this feature).
5171
5172 @item @emph{Example}:
5173 @smallexample
5174 PROGRAM test_getarg
5175   INTEGER :: i
5176   CHARACTER(len=32) :: arg
5177
5178   DO i = 1, iargc()
5179     CALL getarg(i, arg)
5180     WRITE (*,*) arg
5181   END DO
5182 END PROGRAM
5183 @end smallexample
5184
5185 @item @emph{See also}:
5186 GNU Fortran 77 compatibility function: @ref{IARGC}
5187
5188 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5189 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5190 @end table
5191
5192
5193
5194 @node GET_COMMAND
5195 @section @code{GET_COMMAND} --- Get the entire command line
5196 @fnindex GET_COMMAND
5197 @cindex command-line arguments
5198 @cindex arguments, to program
5199
5200 @table @asis
5201 @item @emph{Description}:
5202 Retrieve the entire command line that was used to invoke the program.
5203
5204 @item @emph{Standard}:
5205 Fortran 2003 and later
5206
5207 @item @emph{Class}:
5208 Subroutine
5209
5210 @item @emph{Syntax}:
5211 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5212
5213 @item @emph{Arguments}:
5214 @multitable @columnfractions .15 .70
5215 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5216 of default kind.
5217 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5218 default kind.
5219 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5220 default kind.
5221 @end multitable
5222
5223 @item @emph{Return value}:
5224 If @var{COMMAND} is present, stores the entire command line that was used
5225 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5226 assigned the length of the command line. If @var{STATUS} is present, it
5227 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5228 short to store the command line, or a positive value in case of an error.
5229
5230 @item @emph{Example}:
5231 @smallexample
5232 PROGRAM test_get_command
5233   CHARACTER(len=255) :: cmd
5234   CALL get_command(cmd)
5235   WRITE (*,*) TRIM(cmd)
5236 END PROGRAM
5237 @end smallexample
5238
5239 @item @emph{See also}:
5240 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5241 @end table
5242
5243
5244
5245 @node GET_COMMAND_ARGUMENT
5246 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5247 @fnindex GET_COMMAND_ARGUMENT
5248 @cindex command-line arguments
5249 @cindex arguments, to program
5250
5251 @table @asis
5252 @item @emph{Description}:
5253 Retrieve the @var{NUMBER}-th argument that was passed on the
5254 command line when the containing program was invoked.
5255
5256 @item @emph{Standard}:
5257 Fortran 2003 and later
5258
5259 @item @emph{Class}:
5260 Subroutine
5261
5262 @item @emph{Syntax}:
5263 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5264
5265 @item @emph{Arguments}:
5266 @multitable @columnfractions .15 .70
5267 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5268 default kind, @math{@var{NUMBER} \geq 0}
5269 @item @var{VALUE}  @tab Shall be a scalar of type @code{CHARACTER}
5270 and of default kind.
5271 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
5272 and of default kind.
5273 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
5274 and of default kind.
5275 @end multitable
5276
5277 @item @emph{Return value}:
5278 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5279 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5280 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5281 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5282 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5283 systems that support this feature). The @var{LENGTH} argument contains the
5284 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5285 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5286 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5287 zero.
5288
5289 @item @emph{Example}:
5290 @smallexample
5291 PROGRAM test_get_command_argument
5292   INTEGER :: i
5293   CHARACTER(len=32) :: arg
5294
5295   i = 0
5296   DO
5297     CALL get_command_argument(i, arg)
5298     IF (LEN_TRIM(arg) == 0) EXIT
5299
5300     WRITE (*,*) TRIM(arg)
5301     i = i+1
5302   END DO
5303 END PROGRAM
5304 @end smallexample
5305
5306 @item @emph{See also}:
5307 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5308 @end table
5309
5310
5311
5312 @node GETCWD
5313 @section @code{GETCWD} --- Get current working directory
5314 @fnindex GETCWD
5315 @cindex system, working directory
5316
5317 @table @asis
5318 @item @emph{Description}:
5319 Get current working directory.
5320
5321 This intrinsic is provided in both subroutine and function forms; however,
5322 only one form can be used in any given program unit.
5323
5324 @item @emph{Standard}:
5325 GNU extension
5326
5327 @item @emph{Class}:
5328 Subroutine, function
5329
5330 @item @emph{Syntax}:
5331 @multitable @columnfractions .80
5332 @item @code{CALL GETCWD(C [, STATUS])}
5333 @item @code{STATUS = GETCWD(C)}
5334 @end multitable
5335
5336 @item @emph{Arguments}:
5337 @multitable @columnfractions .15 .70
5338 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5339 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5340 a system specific and nonzero error code otherwise.
5341 @end multitable
5342
5343 @item @emph{Example}:
5344 @smallexample
5345 PROGRAM test_getcwd
5346   CHARACTER(len=255) :: cwd
5347   CALL getcwd(cwd)
5348   WRITE(*,*) TRIM(cwd)
5349 END PROGRAM
5350 @end smallexample
5351
5352 @item @emph{See also}:
5353 @ref{CHDIR}
5354 @end table
5355
5356
5357
5358 @node GETENV
5359 @section @code{GETENV} --- Get an environmental variable
5360 @fnindex GETENV
5361 @cindex environment variable
5362
5363 @table @asis
5364 @item @emph{Description}:
5365 Get the @var{VALUE} of the environmental variable @var{NAME}.
5366
5367 This intrinsic routine is provided for backwards compatibility with
5368 GNU Fortran 77.  In new code, programmers should consider the use of
5369 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5370 2003 standard.
5371
5372 @item @emph{Standard}:
5373 GNU extension
5374
5375 @item @emph{Class}:
5376 Subroutine
5377
5378 @item @emph{Syntax}:
5379 @code{CALL GETENV(NAME, VALUE)}
5380
5381 @item @emph{Arguments}:
5382 @multitable @columnfractions .15 .70
5383 @item @var{NAME}  @tab Shall be of type @code{CHARACTER} and of default kind.
5384 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5385 @end multitable
5386
5387 @item @emph{Return value}:
5388 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5389 not large enough to hold the data, it is truncated. If @var{NAME}
5390 is not set, @var{VALUE} will be filled with blanks.
5391
5392 @item @emph{Example}:
5393 @smallexample
5394 PROGRAM test_getenv
5395   CHARACTER(len=255) :: homedir
5396   CALL getenv("HOME", homedir)
5397   WRITE (*,*) TRIM(homedir)
5398 END PROGRAM
5399 @end smallexample
5400
5401 @item @emph{See also}:
5402 @ref{GET_ENVIRONMENT_VARIABLE}
5403 @end table
5404
5405
5406
5407 @node GET_ENVIRONMENT_VARIABLE
5408 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5409 @fnindex GET_ENVIRONMENT_VARIABLE
5410 @cindex environment variable
5411
5412 @table @asis
5413 @item @emph{Description}:
5414 Get the @var{VALUE} of the environmental variable @var{NAME}.
5415
5416 @item @emph{Standard}:
5417 Fortran 2003 and later
5418
5419 @item @emph{Class}:
5420 Subroutine
5421
5422 @item @emph{Syntax}:
5423 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5424
5425 @item @emph{Arguments}:
5426 @multitable @columnfractions .15 .70
5427 @item @var{NAME}      @tab Shall be a scalar of type @code{CHARACTER}
5428 and of default kind.
5429 @item @var{VALUE}     @tab Shall be a scalar of type @code{CHARACTER}
5430 and of default kind.
5431 @item @var{LENGTH}    @tab Shall be a scalar of type @code{INTEGER}
5432 and of default kind.
5433 @item @var{STATUS}    @tab Shall be a scalar of type @code{INTEGER}
5434 and of default kind.
5435 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5436 and of default kind.
5437 @end multitable
5438
5439 @item @emph{Return value}:
5440 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5441 not large enough to hold the data, it is truncated. If @var{NAME}
5442 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5443 contains the length needed for storing the environment variable @var{NAME}
5444 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5445 but too short for the environment variable; it is 1 if the environment
5446 variable does not exist and 2 if the processor does not support environment
5447 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5448 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5449 are significant; otherwise they are not part of the environment variable
5450 name.
5451
5452 @item @emph{Example}:
5453 @smallexample
5454 PROGRAM test_getenv
5455   CHARACTER(len=255) :: homedir
5456   CALL get_environment_variable("HOME", homedir)
5457   WRITE (*,*) TRIM(homedir)
5458 END PROGRAM
5459 @end smallexample
5460 @end table
5461
5462
5463
5464 @node GETGID
5465 @section @code{GETGID} --- Group ID function
5466 @fnindex GETGID
5467 @cindex system, group ID
5468
5469 @table @asis
5470 @item @emph{Description}:
5471 Returns the numerical group ID of the current process.
5472
5473 @item @emph{Standard}:
5474 GNU extension
5475
5476 @item @emph{Class}:
5477 Function
5478
5479 @item @emph{Syntax}:
5480 @code{RESULT = GETGID()}
5481
5482 @item @emph{Return value}:
5483 The return value of @code{GETGID} is an @code{INTEGER} of the default
5484 kind.
5485
5486
5487 @item @emph{Example}:
5488 See @code{GETPID} for an example.
5489
5490 @item @emph{See also}:
5491 @ref{GETPID}, @ref{GETUID}
5492 @end table
5493
5494
5495
5496 @node GETLOG
5497 @section @code{GETLOG} --- Get login name
5498 @fnindex GETLOG
5499 @cindex system, login name
5500 @cindex login name
5501
5502 @table @asis
5503 @item @emph{Description}:
5504 Gets the username under which the program is running.
5505
5506 @item @emph{Standard}:
5507 GNU extension
5508
5509 @item @emph{Class}:
5510 Subroutine
5511
5512 @item @emph{Syntax}:
5513 @code{CALL GETLOG(C)}
5514
5515 @item @emph{Arguments}:
5516 @multitable @columnfractions .15 .70
5517 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5518 @end multitable
5519
5520 @item @emph{Return value}:
5521 Stores the current user name in @var{LOGIN}.  (On systems where POSIX
5522 functions @code{geteuid} and @code{getpwuid} are not available, and
5523 the @code{getlogin} function is not implemented either, this will
5524 return a blank string.)
5525
5526 @item @emph{Example}:
5527 @smallexample
5528 PROGRAM TEST_GETLOG
5529   CHARACTER(32) :: login
5530   CALL GETLOG(login)
5531   WRITE(*,*) login
5532 END PROGRAM
5533 @end smallexample
5534
5535 @item @emph{See also}:
5536 @ref{GETUID}
5537 @end table
5538
5539
5540
5541 @node GETPID
5542 @section @code{GETPID} --- Process ID function
5543 @fnindex GETPID
5544 @cindex system, process ID
5545 @cindex process ID
5546
5547 @table @asis
5548 @item @emph{Description}:
5549 Returns the numerical process identifier of the current process.
5550
5551 @item @emph{Standard}:
5552 GNU extension
5553
5554 @item @emph{Class}:
5555 Function
5556
5557 @item @emph{Syntax}:
5558 @code{RESULT = GETPID()}
5559
5560 @item @emph{Return value}:
5561 The return value of @code{GETPID} is an @code{INTEGER} of the default
5562 kind.
5563
5564
5565 @item @emph{Example}:
5566 @smallexample
5567 program info
5568   print *, "The current process ID is ", getpid()
5569   print *, "Your numerical user ID is ", getuid()
5570   print *, "Your numerical group ID is ", getgid()
5571 end program info
5572 @end smallexample
5573
5574 @item @emph{See also}:
5575 @ref{GETGID}, @ref{GETUID}
5576 @end table
5577
5578
5579
5580 @node GETUID
5581 @section @code{GETUID} --- User ID function
5582 @fnindex GETUID
5583 @cindex system, user ID
5584 @cindex user id
5585
5586 @table @asis
5587 @item @emph{Description}:
5588 Returns the numerical user ID of the current process.
5589
5590 @item @emph{Standard}:
5591 GNU extension
5592
5593 @item @emph{Class}:
5594 Function
5595
5596 @item @emph{Syntax}:
5597 @code{RESULT = GETUID()}
5598
5599 @item @emph{Return value}:
5600 The return value of @code{GETUID} is an @code{INTEGER} of the default
5601 kind.
5602
5603
5604 @item @emph{Example}:
5605 See @code{GETPID} for an example.
5606
5607 @item @emph{See also}:
5608 @ref{GETPID}, @ref{GETLOG}
5609 @end table
5610
5611
5612
5613 @node GMTIME
5614 @section @code{GMTIME} --- Convert time to GMT info
5615 @fnindex GMTIME
5616 @cindex time, conversion to GMT info
5617
5618 @table @asis
5619 @item @emph{Description}:
5620 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5621 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5622 to the UTC time zone (Universal Coordinated Time, also known in some
5623 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5624
5625 @item @emph{Standard}:
5626 GNU extension
5627
5628 @item @emph{Class}:
5629 Subroutine
5630
5631 @item @emph{Syntax}:
5632 @code{CALL GMTIME(TIME, VALUES)}
5633
5634 @item @emph{Arguments}:
5635 @multitable @columnfractions .15 .70
5636 @item @var{TIME}   @tab An @code{INTEGER} scalar expression
5637 corresponding to a system time, with @code{INTENT(IN)}.
5638 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5639 with @code{INTENT(OUT)}.
5640 @end multitable
5641
5642 @item @emph{Return value}:
5643 The elements of @var{VALUES} are assigned as follows:
5644 @enumerate
5645 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5646 seconds
5647 @item Minutes after the hour, range 0--59
5648 @item Hours past midnight, range 0--23
5649 @item Day of month, range 0--31
5650 @item Number of months since January, range 0--12
5651 @item Years since 1900
5652 @item Number of days since Sunday, range 0--6
5653 @item Days since January 1
5654 @item Daylight savings indicator: positive if daylight savings is in
5655 effect, zero if not, and negative if the information is not available.
5656 @end enumerate
5657
5658 @item @emph{See also}:
5659 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5660
5661 @end table
5662
5663
5664
5665 @node HOSTNM
5666 @section @code{HOSTNM} --- Get system host name
5667 @fnindex HOSTNM
5668 @cindex system, host name
5669
5670 @table @asis
5671 @item @emph{Description}:
5672 Retrieves the host name of the system on which the program is running.
5673
5674 This intrinsic is provided in both subroutine and function forms; however,
5675 only one form can be used in any given program unit.
5676
5677 @item @emph{Standard}:
5678 GNU extension
5679
5680 @item @emph{Class}:
5681 Subroutine, function
5682
5683 @item @emph{Syntax}:
5684 @multitable @columnfractions .80
5685 @item @code{CALL HOSTNM(C [, STATUS])}
5686 @item @code{STATUS = HOSTNM(NAME)}
5687 @end multitable
5688
5689 @item @emph{Arguments}:
5690 @multitable @columnfractions .15 .70
5691 @item @var{C}    @tab Shall of type @code{CHARACTER} and of default kind.
5692 @item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
5693 Returns 0 on success, or a system specific error code otherwise.
5694 @end multitable
5695
5696 @item @emph{Return value}:
5697 In either syntax, @var{NAME} is set to the current hostname if it can
5698 be obtained, or to a blank string otherwise.
5699
5700 @end table
5701
5702
5703
5704 @node HUGE
5705 @section @code{HUGE} --- Largest number of a kind
5706 @fnindex HUGE
5707 @cindex limits, largest number
5708 @cindex model representation, largest number
5709
5710 @table @asis
5711 @item @emph{Description}:
5712 @code{HUGE(X)} returns the largest number that is not an infinity in
5713 the model of the type of @code{X}.
5714
5715 @item @emph{Standard}:
5716 Fortran 95 and later
5717
5718 @item @emph{Class}:
5719 Inquiry function
5720
5721 @item @emph{Syntax}:
5722 @code{RESULT = HUGE(X)}
5723
5724 @item @emph{Arguments}:
5725 @multitable @columnfractions .15 .70
5726 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5727 @end multitable
5728
5729 @item @emph{Return value}:
5730 The return value is of the same type and kind as @var{X}
5731
5732 @item @emph{Example}:
5733 @smallexample
5734 program test_huge_tiny
5735   print *, huge(0), huge(0.0), huge(0.0d0)
5736   print *, tiny(0.0), tiny(0.0d0)
5737 end program test_huge_tiny
5738 @end smallexample
5739 @end table
5740
5741
5742
5743 @node HYPOT
5744 @section @code{HYPOT} --- Euclidean distance function
5745 @fnindex HYPOT
5746 @cindex Euclidean distance
5747
5748 @table @asis
5749 @item @emph{Description}:
5750 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5751 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5752
5753 @item @emph{Standard}:
5754 Fortran 2008 and later
5755
5756 @item @emph{Class}:
5757 Elemental function
5758
5759 @item @emph{Syntax}:
5760 @code{RESULT = HYPOT(X, Y)}
5761
5762 @item @emph{Arguments}:
5763 @multitable @columnfractions .15 .70
5764 @item @var{X} @tab The type shall be @code{REAL}.
5765 @item @var{Y} @tab The type and kind type parameter shall be the same as
5766 @var{X}.
5767 @end multitable
5768
5769 @item @emph{Return value}:
5770 The return value has the same type and kind type parameter as @var{X}.
5771
5772 @item @emph{Example}:
5773 @smallexample
5774 program test_hypot
5775   real(4) :: x = 1.e0_4, y = 0.5e0_4
5776   x = hypot(x,y)
5777 end program test_hypot
5778 @end smallexample
5779 @end table
5780
5781
5782
5783 @node IACHAR
5784 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5785 @fnindex IACHAR
5786 @cindex @acronym{ASCII} collating sequence
5787 @cindex collating sequence, @acronym{ASCII}
5788 @cindex conversion, to integer
5789
5790 @table @asis
5791 @item @emph{Description}:
5792 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5793 in the first character position of @code{C}.
5794
5795 @item @emph{Standard}:
5796 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5797
5798 @item @emph{Class}:
5799 Elemental function
5800
5801 @item @emph{Syntax}:
5802 @code{RESULT = IACHAR(C [, KIND])}
5803
5804 @item @emph{Arguments}:
5805 @multitable @columnfractions .15 .70
5806 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5807 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5808 expression indicating the kind parameter of the result.
5809 @end multitable
5810
5811 @item @emph{Return value}:
5812 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5813 @var{KIND} is absent, the return value is of default integer kind.
5814
5815 @item @emph{Example}:
5816 @smallexample
5817 program test_iachar
5818   integer i
5819   i = iachar(' ')
5820 end program test_iachar
5821 @end smallexample
5822
5823 @item @emph{Note}:
5824 See @ref{ICHAR} for a discussion of converting between numerical values
5825 and formatted string representations.
5826
5827 @item @emph{See also}:
5828 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5829
5830 @end table
5831
5832
5833
5834 @node IALL
5835 @section @code{IALL} --- Bitwise AND of array elements
5836 @fnindex IALL
5837 @cindex array, AND
5838 @cindex bits, AND of array elements
5839
5840 @table @asis
5841 @item @emph{Description}:
5842 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
5843 if the corresponding element in @var{MASK} is @code{TRUE}.
5844
5845 @item @emph{Standard}:
5846 Fortran 2008 and later
5847
5848 @item @emph{Class}:
5849 Transformational function
5850
5851 @item @emph{Syntax}:
5852 @multitable @columnfractions .80
5853 @item @code{RESULT = IALL(ARRAY[, MASK])}
5854 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
5855 @end multitable
5856
5857 @item @emph{Arguments}:
5858 @multitable @columnfractions .15 .70
5859 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
5860 @item @var{DIM}   @tab (Optional) shall be a scalar of type
5861 @code{INTEGER} with a value in the range from 1 to n, where n
5862 equals the rank of @var{ARRAY}.
5863 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
5864 and either be a scalar or an array of the same shape as @var{ARRAY}.
5865 @end multitable
5866
5867 @item @emph{Return value}:
5868 The result is of the same type as @var{ARRAY}.
5869
5870 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
5871 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
5872 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
5873 dimension @var{DIM} dropped is returned.
5874
5875 @item @emph{Example}:
5876 @smallexample
5877 PROGRAM test_iall
5878   INTEGER(1) :: a(2)
5879
5880   a(1) = b'00100100'
5881   a(1) = b'01101010'
5882
5883   ! prints 00100000
5884   PRINT '(b8.8)', IALL(a)
5885 END PROGRAM
5886 @end smallexample
5887
5888 @item @emph{See also}:
5889 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
5890 @end table
5891
5892
5893
5894 @node IAND
5895 @section @code{IAND} --- Bitwise logical and
5896 @fnindex IAND
5897 @cindex bitwise logical and
5898 @cindex logical and, bitwise
5899
5900 @table @asis
5901 @item @emph{Description}:
5902 Bitwise logical @code{AND}.
5903
5904 @item @emph{Standard}:
5905 Fortran 95 and later
5906
5907 @item @emph{Class}:
5908 Elemental function
5909
5910 @item @emph{Syntax}:
5911 @code{RESULT = IAND(I, J)}
5912
5913 @item @emph{Arguments}:
5914 @multitable @columnfractions .15 .70
5915 @item @var{I} @tab The type shall be @code{INTEGER}.
5916 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5917 kind as @var{I}.  (As a GNU extension, different kinds are also
5918 permitted.)
5919 @end multitable
5920
5921 @item @emph{Return value}:
5922 The return type is @code{INTEGER}, of the same kind as the
5923 arguments.  (If the argument kinds differ, it is of the same kind as
5924 the larger argument.)
5925
5926 @item @emph{Example}:
5927 @smallexample
5928 PROGRAM test_iand
5929   INTEGER :: a, b
5930   DATA a / Z'F' /, b / Z'3' /
5931   WRITE (*,*) IAND(a, b)
5932 END PROGRAM
5933 @end smallexample
5934
5935 @item @emph{See also}:
5936 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5937
5938 @end table
5939
5940
5941
5942 @node IANY
5943 @section @code{IANY} --- Bitwise XOR of array elements
5944 @fnindex IANY
5945 @cindex array, OR
5946 @cindex bits, OR of array elements
5947
5948 @table @asis
5949 @item @emph{Description}:
5950 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
5951 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
5952
5953 @item @emph{Standard}:
5954 Fortran 2008 and later
5955
5956 @item @emph{Class}:
5957 Transformational function
5958
5959 @item @emph{Syntax}:
5960 @multitable @columnfractions .80
5961 @item @code{RESULT = IANY(ARRAY[, MASK])}
5962 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
5963 @end multitable
5964
5965 @item @emph{Arguments}:
5966 @multitable @columnfractions .15 .70
5967 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
5968 @item @var{DIM}   @tab (Optional) shall be a scalar of type
5969 @code{INTEGER} with a value in the range from 1 to n, where n
5970 equals the rank of @var{ARRAY}.
5971 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
5972 and either be a scalar or an array of the same shape as @var{ARRAY}.
5973 @end multitable
5974
5975 @item @emph{Return value}:
5976 The result is of the same type as @var{ARRAY}.
5977
5978 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
5979 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
5980 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
5981 dimension @var{DIM} dropped is returned.
5982
5983 @item @emph{Example}:
5984 @smallexample
5985 PROGRAM test_iany
5986   INTEGER(1) :: a(2)
5987
5988   a(1) = b'00100100'
5989   a(1) = b'01101010'
5990
5991   ! prints 01111011
5992   PRINT '(b8.8)', IANY(a)
5993 END PROGRAM
5994 @end smallexample
5995
5996 @item @emph{See also}:
5997 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
5998 @end table
5999
6000
6001
6002 @node IARGC
6003 @section @code{IARGC} --- Get the number of command line arguments
6004 @fnindex IARGC
6005 @cindex command-line arguments
6006 @cindex command-line arguments, number of
6007 @cindex arguments, to program
6008
6009 @table @asis
6010 @item @emph{Description}:
6011 @code{IARGC()} returns the number of arguments passed on the
6012 command line when the containing program was invoked.
6013
6014 This intrinsic routine is provided for backwards compatibility with
6015 GNU Fortran 77.  In new code, programmers should consider the use of
6016 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6017 standard.
6018
6019 @item @emph{Standard}:
6020 GNU extension
6021
6022 @item @emph{Class}:
6023 Function
6024
6025 @item @emph{Syntax}:
6026 @code{RESULT = IARGC()}
6027
6028 @item @emph{Arguments}:
6029 None.
6030
6031 @item @emph{Return value}:
6032 The number of command line arguments, type @code{INTEGER(4)}.
6033
6034 @item @emph{Example}:
6035 See @ref{GETARG}
6036
6037 @item @emph{See also}:
6038 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6039
6040 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6041 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6042 @end table
6043
6044
6045
6046 @node IBCLR
6047 @section @code{IBCLR} --- Clear bit
6048 @fnindex IBCLR
6049 @cindex bits, unset
6050 @cindex bits, clear
6051
6052 @table @asis
6053 @item @emph{Description}:
6054 @code{IBCLR} returns the value of @var{I} with the bit at position
6055 @var{POS} set to zero.
6056
6057 @item @emph{Standard}:
6058 Fortran 95 and later
6059
6060 @item @emph{Class}:
6061 Elemental function
6062
6063 @item @emph{Syntax}:
6064 @code{RESULT = IBCLR(I, POS)}
6065
6066 @item @emph{Arguments}:
6067 @multitable @columnfractions .15 .70
6068 @item @var{I} @tab The type shall be @code{INTEGER}.
6069 @item @var{POS} @tab The type shall be @code{INTEGER}.
6070 @end multitable
6071
6072 @item @emph{Return value}:
6073 The return value is of type @code{INTEGER} and of the same kind as
6074 @var{I}.
6075
6076 @item @emph{See also}:
6077 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6078
6079 @end table
6080
6081
6082
6083 @node IBITS
6084 @section @code{IBITS} --- Bit extraction
6085 @fnindex IBITS
6086 @cindex bits, get
6087 @cindex bits, extract
6088
6089 @table @asis
6090 @item @emph{Description}:
6091 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6092 starting from bit position @var{POS} and extending left for @var{LEN}
6093 bits.  The result is right-justified and the remaining bits are
6094 zeroed.  The value of @code{POS+LEN} must be less than or equal to the
6095 value @code{BIT_SIZE(I)}.
6096
6097 @item @emph{Standard}:
6098 Fortran 95 and later
6099
6100 @item @emph{Class}:
6101 Elemental function
6102
6103 @item @emph{Syntax}:
6104 @code{RESULT = IBITS(I, POS, LEN)}
6105
6106 @item @emph{Arguments}:
6107 @multitable @columnfractions .15 .70
6108 @item @var{I}   @tab The type shall be @code{INTEGER}.
6109 @item @var{POS} @tab The type shall be @code{INTEGER}.
6110 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6111 @end multitable
6112
6113 @item @emph{Return value}:
6114 The return value is of type @code{INTEGER} and of the same kind as
6115 @var{I}.
6116
6117 @item @emph{See also}:
6118 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6119 @end table
6120
6121
6122
6123 @node IBSET
6124 @section @code{IBSET} --- Set bit
6125 @fnindex IBSET
6126 @cindex bits, set
6127
6128 @table @asis
6129 @item @emph{Description}:
6130 @code{IBSET} returns the value of @var{I} with the bit at position
6131 @var{POS} set to one.
6132
6133 @item @emph{Standard}:
6134 Fortran 95 and later
6135
6136 @item @emph{Class}:
6137 Elemental function
6138
6139 @item @emph{Syntax}:
6140 @code{RESULT = IBSET(I, POS)}
6141
6142 @item @emph{Arguments}:
6143 @multitable @columnfractions .15 .70
6144 @item @var{I} @tab The type shall be @code{INTEGER}.
6145 @item @var{POS} @tab The type shall be @code{INTEGER}.
6146 @end multitable
6147
6148 @item @emph{Return value}:
6149 The return value is of type @code{INTEGER} and of the same kind as
6150 @var{I}.
6151
6152 @item @emph{See also}:
6153 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6154
6155 @end table
6156
6157
6158
6159 @node ICHAR
6160 @section @code{ICHAR} --- Character-to-integer conversion function
6161 @fnindex ICHAR
6162 @cindex conversion, to integer
6163
6164 @table @asis
6165 @item @emph{Description}:
6166 @code{ICHAR(C)} returns the code for the character in the first character
6167 position of @code{C} in the system's native character set.
6168 The correspondence between characters and their codes is not necessarily
6169 the same across different GNU Fortran implementations.
6170
6171 @item @emph{Standard}:
6172 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6173
6174 @item @emph{Class}:
6175 Elemental function
6176
6177 @item @emph{Syntax}:
6178 @code{RESULT = ICHAR(C [, KIND])}
6179
6180 @item @emph{Arguments}:
6181 @multitable @columnfractions .15 .70
6182 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6183 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6184 expression indicating the kind parameter of the result.
6185 @end multitable
6186
6187 @item @emph{Return value}:
6188 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6189 @var{KIND} is absent, the return value is of default integer kind.
6190
6191 @item @emph{Example}:
6192 @smallexample
6193 program test_ichar
6194   integer i
6195   i = ichar(' ')
6196 end program test_ichar
6197 @end smallexample
6198
6199 @item @emph{Specific names}:
6200 @multitable @columnfractions .20 .20 .20 .25
6201 @item Name             @tab Argument             @tab Return type       @tab Standard
6202 @item @code{ICHAR(C)}  @tab @code{CHARACTER C}   @tab @code{INTEGER(4)}    @tab Fortran 77 and later
6203 @end multitable
6204
6205 @item @emph{Note}:
6206 No intrinsic exists to convert between a numeric value and a formatted
6207 character string representation -- for instance, given the
6208 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6209 @code{REAL} value with the value 154, or vice versa. Instead, this
6210 functionality is provided by internal-file I/O, as in the following
6211 example:
6212 @smallexample
6213 program read_val
6214   integer value
6215   character(len=10) string, string2
6216   string = '154'
6217
6218   ! Convert a string to a numeric value
6219   read (string,'(I10)') value
6220   print *, value
6221
6222   ! Convert a value to a formatted string
6223   write (string2,'(I10)') value
6224   print *, string2
6225 end program read_val
6226 @end smallexample
6227
6228 @item @emph{See also}:
6229 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6230
6231 @end table
6232
6233
6234
6235 @node IDATE
6236 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6237 @fnindex IDATE
6238 @cindex date, current
6239 @cindex current date
6240
6241 @table @asis
6242 @item @emph{Description}:
6243 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6244 current local time. The day (in the range 1-31), month (in the range 1-12),
6245 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6246 The year has four significant digits.
6247
6248 @item @emph{Standard}:
6249 GNU extension
6250
6251 @item @emph{Class}:
6252 Subroutine
6253
6254 @item @emph{Syntax}:
6255 @code{CALL IDATE(VALUES)}
6256
6257 @item @emph{Arguments}:
6258 @multitable @columnfractions .15 .70
6259 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6260 the kind shall be the default integer kind.
6261 @end multitable
6262
6263 @item @emph{Return value}:
6264 Does not return anything.
6265
6266 @item @emph{Example}:
6267 @smallexample
6268 program test_idate
6269   integer, dimension(3) :: tarray
6270   call idate(tarray)
6271   print *, tarray(1)
6272   print *, tarray(2)
6273   print *, tarray(3)
6274 end program test_idate
6275 @end smallexample
6276 @end table
6277
6278
6279
6280 @node IEOR
6281 @section @code{IEOR} --- Bitwise logical exclusive or
6282 @fnindex IEOR
6283 @cindex bitwise logical exclusive or
6284 @cindex logical exclusive or, bitwise
6285
6286 @table @asis
6287 @item @emph{Description}:
6288 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6289 @var{J}.
6290
6291 @item @emph{Standard}:
6292 Fortran 95 and later
6293
6294 @item @emph{Class}:
6295 Elemental function
6296
6297 @item @emph{Syntax}:
6298 @code{RESULT = IEOR(I, J)}
6299
6300 @item @emph{Arguments}:
6301 @multitable @columnfractions .15 .70
6302 @item @var{I} @tab The type shall be @code{INTEGER}.
6303 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6304 kind as @var{I}.  (As a GNU extension, different kinds are also
6305 permitted.)
6306 @end multitable
6307
6308 @item @emph{Return value}:
6309 The return type is @code{INTEGER}, of the same kind as the
6310 arguments.  (If the argument kinds differ, it is of the same kind as
6311 the larger argument.)
6312
6313 @item @emph{See also}:
6314 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6315 @end table
6316
6317
6318
6319 @node IERRNO
6320 @section @code{IERRNO} --- Get the last system error number
6321 @fnindex IERRNO
6322 @cindex system, error handling
6323
6324 @table @asis
6325 @item @emph{Description}:
6326 Returns the last system error number, as given by the C @code{errno()}
6327 function.
6328
6329 @item @emph{Standard}:
6330 GNU extension
6331
6332 @item @emph{Class}:
6333 Function
6334
6335 @item @emph{Syntax}:
6336 @code{RESULT = IERRNO()}
6337
6338 @item @emph{Arguments}:
6339 None.
6340
6341 @item @emph{Return value}:
6342 The return value is of type @code{INTEGER} and of the default integer
6343 kind.
6344
6345 @item @emph{See also}:
6346 @ref{PERROR}
6347 @end table
6348
6349
6350
6351 @node IMAGE_INDEX
6352 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6353 @fnindex IMAGE_INDEX
6354 @cindex coarray, @code{IMAGE_INDEX}
6355 @cindex images, cosubscript to image index conversion
6356
6357 @table @asis
6358 @item @emph{Description}:
6359 Returns the image index belonging to a cosubscript.
6360
6361 @item @emph{Standard}:
6362 Fortran 2008 and later
6363
6364 @item @emph{Class}:
6365 Inquiry function.
6366
6367 @item @emph{Syntax}:
6368 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6369
6370 @item @emph{Arguments}: None.
6371 @multitable @columnfractions .15 .70
6372 @item @var{COARRAY} @tab Coarray of any type.
6373 @item @var{SUB}     @tab default integer rank-1 array of a size equal to
6374 the corank of @var{COARRAY}.
6375 @end multitable
6376
6377
6378 @item @emph{Return value}:
6379 Scalar default integer with the value of the image index which corresponds
6380 to the cosubscripts. For invalid cosubscripts the result is zero.
6381
6382 @item @emph{Example}:
6383 @smallexample
6384 INTEGER :: array[2,-1:4,8,*]
6385 ! Writes  28 (or 0 if there are fewer than 28 images)
6386 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6387 @end smallexample
6388
6389 @item @emph{See also}:
6390 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6391 @end table
6392
6393
6394
6395 @node INDEX intrinsic
6396 @section @code{INDEX} --- Position of a substring within a string
6397 @fnindex INDEX
6398 @cindex substring position
6399 @cindex string, find substring
6400
6401 @table @asis
6402 @item @emph{Description}:
6403 Returns the position of the start of the first occurrence of string
6404 @var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
6405 @var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
6406 the @var{BACK} argument is present and true, the return value is the
6407 start of the last occurrence rather than the first.
6408
6409 @item @emph{Standard}:
6410 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6411
6412 @item @emph{Class}:
6413 Elemental function
6414
6415 @item @emph{Syntax}:
6416 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6417
6418 @item @emph{Arguments}:
6419 @multitable @columnfractions .15 .70
6420 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6421 @code{INTENT(IN)}
6422 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6423 @code{INTENT(IN)}
6424 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6425 @code{INTENT(IN)}
6426 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6427 expression indicating the kind parameter of the result.
6428 @end multitable
6429
6430 @item @emph{Return value}:
6431 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6432 @var{KIND} is absent, the return value is of default integer kind.
6433
6434 @item @emph{Specific names}:
6435 @multitable @columnfractions .20 .20 .20 .25
6436 @item Name                            @tab Argument           @tab Return type       @tab Standard
6437 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER}   @tab @code{INTEGER(4)} @tab Fortran 77 and later
6438 @end multitable
6439
6440 @item @emph{See also}:
6441 @ref{SCAN}, @ref{VERIFY}
6442 @end table
6443
6444
6445
6446 @node INT
6447 @section @code{INT} --- Convert to integer type
6448 @fnindex INT
6449 @fnindex IFIX
6450 @fnindex IDINT
6451 @cindex conversion, to integer
6452
6453 @table @asis
6454 @item @emph{Description}:
6455 Convert to integer type
6456
6457 @item @emph{Standard}:
6458 Fortran 77 and later
6459
6460 @item @emph{Class}:
6461 Elemental function
6462
6463 @item @emph{Syntax}:
6464 @code{RESULT = INT(A [, KIND))}
6465
6466 @item @emph{Arguments}:
6467 @multitable @columnfractions .15 .70
6468 @item @var{A}    @tab Shall be of type @code{INTEGER},
6469 @code{REAL}, or @code{COMPLEX}.
6470 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6471 expression indicating the kind parameter of the result.
6472 @end multitable
6473
6474 @item @emph{Return value}:
6475 These functions return a @code{INTEGER} variable or array under
6476 the following rules:
6477
6478 @table @asis
6479 @item (A)
6480 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6481 @item (B)
6482 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6483 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6484 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6485 @item (C)
6486 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6487 @end table
6488
6489 @item @emph{Example}:
6490 @smallexample
6491 program test_int
6492   integer :: i = 42
6493   complex :: z = (-3.7, 1.0)
6494   print *, int(i)
6495   print *, int(z), int(z,8)
6496 end program
6497 @end smallexample
6498
6499 @item @emph{Specific names}:
6500 @multitable @columnfractions .20 .20 .20 .25
6501 @item Name            @tab Argument          @tab Return type       @tab Standard
6502 @item @code{INT(A)}   @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6503 @item @code{IFIX(A)}  @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6504 @item @code{IDINT(A)} @tab @code{REAL(8) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6505 @end multitable
6506
6507 @end table
6508
6509
6510 @node INT2
6511 @section @code{INT2} --- Convert to 16-bit integer type
6512 @fnindex INT2
6513 @fnindex SHORT
6514 @cindex conversion, to integer
6515
6516 @table @asis
6517 @item @emph{Description}:
6518 Convert to a @code{KIND=2} integer type. This is equivalent to the
6519 standard @code{INT} intrinsic with an optional argument of
6520 @code{KIND=2}, and is only included for backwards compatibility.
6521
6522 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6523
6524 @item @emph{Standard}:
6525 GNU extension
6526
6527 @item @emph{Class}:
6528 Elemental function
6529
6530 @item @emph{Syntax}:
6531 @code{RESULT = INT2(A)}
6532
6533 @item @emph{Arguments}:
6534 @multitable @columnfractions .15 .70
6535 @item @var{A}    @tab Shall be of type @code{INTEGER},
6536 @code{REAL}, or @code{COMPLEX}.
6537 @end multitable
6538
6539 @item @emph{Return value}:
6540 The return value is a @code{INTEGER(2)} variable.
6541
6542 @item @emph{See also}:
6543 @ref{INT}, @ref{INT8}, @ref{LONG}
6544 @end table
6545
6546
6547
6548 @node INT8
6549 @section @code{INT8} --- Convert to 64-bit integer type
6550 @fnindex INT8
6551 @cindex conversion, to integer
6552
6553 @table @asis
6554 @item @emph{Description}:
6555 Convert to a @code{KIND=8} integer type. This is equivalent to the
6556 standard @code{INT} intrinsic with an optional argument of
6557 @code{KIND=8}, and is only included for backwards compatibility.
6558
6559 @item @emph{Standard}:
6560 GNU extension
6561
6562 @item @emph{Class}:
6563 Elemental function
6564
6565 @item @emph{Syntax}:
6566 @code{RESULT = INT8(A)}
6567
6568 @item @emph{Arguments}:
6569 @multitable @columnfractions .15 .70
6570 @item @var{A}    @tab Shall be of type @code{INTEGER},
6571 @code{REAL}, or @code{COMPLEX}.
6572 @end multitable
6573
6574 @item @emph{Return value}:
6575 The return value is a @code{INTEGER(8)} variable.
6576
6577 @item @emph{See also}:
6578 @ref{INT}, @ref{INT2}, @ref{LONG}
6579 @end table
6580
6581
6582
6583 @node IOR
6584 @section @code{IOR} --- Bitwise logical or
6585 @fnindex IOR
6586 @cindex bitwise logical or
6587 @cindex logical or, bitwise
6588
6589 @table @asis
6590 @item @emph{Description}:
6591 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6592 @var{J}.
6593
6594 @item @emph{Standard}:
6595 Fortran 95 and later
6596
6597 @item @emph{Class}:
6598 Elemental function
6599
6600 @item @emph{Syntax}:
6601 @code{RESULT = IOR(I, J)}
6602
6603 @item @emph{Arguments}:
6604 @multitable @columnfractions .15 .70
6605 @item @var{I} @tab The type shall be @code{INTEGER}.
6606 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6607 kind as @var{I}.  (As a GNU extension, different kinds are also
6608 permitted.)
6609 @end multitable
6610
6611 @item @emph{Return value}:
6612 The return type is @code{INTEGER}, of the same kind as the
6613 arguments.  (If the argument kinds differ, it is of the same kind as
6614 the larger argument.)
6615
6616 @item @emph{See also}:
6617 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6618 @end table
6619
6620
6621
6622 @node IPARITY
6623 @section @code{IPARITY} --- Bitwise XOR of array elements
6624 @fnindex IPARITY
6625 @cindex array, parity
6626 @cindex array, XOR
6627 @cindex bits, XOR of array elements
6628
6629 @table @asis
6630 @item @emph{Description}:
6631 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6632 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6633
6634 @item @emph{Standard}:
6635 Fortran 2008 and later
6636
6637 @item @emph{Class}:
6638 Transformational function
6639
6640 @item @emph{Syntax}:
6641 @multitable @columnfractions .80
6642 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6643 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6644 @end multitable
6645
6646 @item @emph{Arguments}:
6647 @multitable @columnfractions .15 .70
6648 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6649 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6650 @code{INTEGER} with a value in the range from 1 to n, where n
6651 equals the rank of @var{ARRAY}.
6652 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6653 and either be a scalar or an array of the same shape as @var{ARRAY}.
6654 @end multitable
6655
6656 @item @emph{Return value}:
6657 The result is of the same type as @var{ARRAY}.
6658
6659 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6660 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6661 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6662 dimension @var{DIM} dropped is returned.
6663
6664 @item @emph{Example}:
6665 @smallexample
6666 PROGRAM test_iparity
6667   INTEGER(1) :: a(2)
6668
6669   a(1) = b'00100100'
6670   a(1) = b'01101010'
6671
6672   ! prints 10111011
6673   PRINT '(b8.8)', IPARITY(a)
6674 END PROGRAM
6675 @end smallexample
6676
6677 @item @emph{See also}:
6678 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6679 @end table
6680
6681
6682
6683 @node IRAND
6684 @section @code{IRAND} --- Integer pseudo-random number
6685 @fnindex IRAND
6686 @cindex random number generation
6687
6688 @table @asis
6689 @item @emph{Description}:
6690 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6691 distribution between 0 and a system-dependent limit (which is in most
6692 cases 2147483647). If @var{FLAG} is 0, the next number
6693 in the current sequence is returned; if @var{FLAG} is 1, the generator
6694 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6695 it is used as a new seed with @code{SRAND}.
6696
6697 This intrinsic routine is provided for backwards compatibility with
6698 GNU Fortran 77. It implements a simple modulo generator as provided
6699 by @command{g77}. For new code, one should consider the use of
6700 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6701
6702 @item @emph{Standard}:
6703 GNU extension
6704
6705 @item @emph{Class}:
6706 Function
6707
6708 @item @emph{Syntax}:
6709 @code{RESULT = IRAND(I)}
6710
6711 @item @emph{Arguments}:
6712 @multitable @columnfractions .15 .70
6713 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6714 @end multitable
6715
6716 @item @emph{Return value}:
6717 The return value is of @code{INTEGER(kind=4)} type.
6718
6719 @item @emph{Example}:
6720 @smallexample
6721 program test_irand
6722   integer,parameter :: seed = 86456
6723
6724   call srand(seed)
6725   print *, irand(), irand(), irand(), irand()
6726   print *, irand(seed), irand(), irand(), irand()
6727 end program test_irand
6728 @end smallexample
6729
6730 @end table
6731
6732
6733
6734 @node IS_IOSTAT_END
6735 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6736 @fnindex IS_IOSTAT_END
6737 @cindex @code{IOSTAT}, end of file
6738
6739 @table @asis
6740 @item @emph{Description}:
6741 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6742 status ``end of file''. The function is equivalent to comparing the variable
6743 with the @code{IOSTAT_END} parameter of the intrinsic module
6744 @code{ISO_FORTRAN_ENV}.
6745
6746 @item @emph{Standard}:
6747 Fortran 2003 and later
6748
6749 @item @emph{Class}:
6750 Elemental function
6751
6752 @item @emph{Syntax}:
6753 @code{RESULT = IS_IOSTAT_END(I)}
6754
6755 @item @emph{Arguments}:
6756 @multitable @columnfractions .15 .70
6757 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6758 @end multitable
6759
6760 @item @emph{Return value}:
6761 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6762 @var{I} has the value which indicates an end of file condition for
6763 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6764
6765 @item @emph{Example}:
6766 @smallexample
6767 PROGRAM iostat
6768   IMPLICIT NONE
6769   INTEGER :: stat, i
6770   OPEN(88, FILE='test.dat')
6771   READ(88, *, IOSTAT=stat) i
6772   IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6773 END PROGRAM
6774 @end smallexample
6775 @end table
6776
6777
6778
6779 @node IS_IOSTAT_EOR
6780 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6781 @fnindex IS_IOSTAT_EOR
6782 @cindex @code{IOSTAT}, end of record
6783
6784 @table @asis
6785 @item @emph{Description}:
6786 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6787 status ``end of record''. The function is equivalent to comparing the
6788 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6789 @code{ISO_FORTRAN_ENV}.
6790
6791 @item @emph{Standard}:
6792 Fortran 2003 and later
6793
6794 @item @emph{Class}:
6795 Elemental function
6796
6797 @item @emph{Syntax}:
6798 @code{RESULT = IS_IOSTAT_EOR(I)}
6799
6800 @item @emph{Arguments}:
6801 @multitable @columnfractions .15 .70
6802 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6803 @end multitable
6804
6805 @item @emph{Return value}:
6806 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6807 @var{I} has the value which indicates an end of file condition for
6808 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6809
6810 @item @emph{Example}:
6811 @smallexample
6812 PROGRAM iostat
6813   IMPLICIT NONE
6814   INTEGER :: stat, i(50)
6815   OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6816   READ(88, IOSTAT=stat) i
6817   IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6818 END PROGRAM
6819 @end smallexample
6820 @end table
6821
6822
6823
6824 @node ISATTY
6825 @section @code{ISATTY} --- Whether a unit is a terminal device.
6826 @fnindex ISATTY
6827 @cindex system, terminal
6828
6829 @table @asis
6830 @item @emph{Description}:
6831 Determine whether a unit is connected to a terminal device.
6832
6833 @item @emph{Standard}:
6834 GNU extension
6835
6836 @item @emph{Class}:
6837 Function
6838
6839 @item @emph{Syntax}:
6840 @code{RESULT = ISATTY(UNIT)}
6841
6842 @item @emph{Arguments}:
6843 @multitable @columnfractions .15 .70
6844 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6845 @end multitable
6846
6847 @item @emph{Return value}:
6848 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6849 device, @code{.FALSE.} otherwise.
6850
6851 @item @emph{Example}:
6852 @smallexample
6853 PROGRAM test_isatty
6854   INTEGER(kind=1) :: unit
6855   DO unit = 1, 10
6856     write(*,*) isatty(unit=unit)
6857   END DO
6858 END PROGRAM
6859 @end smallexample
6860 @item @emph{See also}:
6861 @ref{TTYNAM}
6862 @end table
6863
6864
6865
6866 @node ISHFT
6867 @section @code{ISHFT} --- Shift bits
6868 @fnindex ISHFT
6869 @cindex bits, shift
6870
6871 @table @asis
6872 @item @emph{Description}:
6873 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6874 bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
6875 zero corresponds to a left shift, a value of zero corresponds to no
6876 shift, and a value less than zero corresponds to a right shift.  If the
6877 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6878 value is undefined.  Bits shifted out from the left end or right end are
6879 lost; zeros are shifted in from the opposite end.
6880
6881 @item @emph{Standard}:
6882 Fortran 95 and later
6883
6884 @item @emph{Class}:
6885 Elemental function
6886
6887 @item @emph{Syntax}:
6888 @code{RESULT = ISHFT(I, SHIFT)}
6889
6890 @item @emph{Arguments}:
6891 @multitable @columnfractions .15 .70
6892 @item @var{I} @tab The type shall be @code{INTEGER}.
6893 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6894 @end multitable
6895
6896 @item @emph{Return value}:
6897 The return value is of type @code{INTEGER} and of the same kind as
6898 @var{I}.
6899
6900 @item @emph{See also}:
6901 @ref{ISHFTC}
6902 @end table
6903
6904
6905
6906 @node ISHFTC
6907 @section @code{ISHFTC} --- Shift bits circularly
6908 @fnindex ISHFTC
6909 @cindex bits, shift circular
6910
6911 @table @asis
6912 @item @emph{Description}:
6913 @code{ISHFTC} returns a value corresponding to @var{I} with the
6914 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6915 is, bits shifted out one end are shifted into the opposite end.  A value
6916 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6917 zero corresponds to no shift, and a value less than zero corresponds to
6918 a right shift.  The absolute value of @var{SHIFT} must be less than
6919 @var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
6920 equivalent to @code{BIT_SIZE(I)}.
6921
6922 @item @emph{Standard}:
6923 Fortran 95 and later
6924
6925 @item @emph{Class}:
6926 Elemental function
6927
6928 @item @emph{Syntax}:
6929 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6930
6931 @item @emph{Arguments}:
6932 @multitable @columnfractions .15 .70
6933 @item @var{I} @tab The type shall be @code{INTEGER}.
6934 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6935 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6936 the value must be greater than zero and less than or equal to
6937 @code{BIT_SIZE(I)}.
6938 @end multitable
6939
6940 @item @emph{Return value}:
6941 The return value is of type @code{INTEGER} and of the same kind as
6942 @var{I}.
6943
6944 @item @emph{See also}:
6945 @ref{ISHFT}
6946 @end table
6947
6948
6949
6950 @node ISNAN
6951 @section @code{ISNAN} --- Test for a NaN
6952 @fnindex ISNAN
6953 @cindex IEEE, ISNAN
6954
6955 @table @asis
6956 @item @emph{Description}:
6957 @code{ISNAN} tests whether a floating-point value is an IEEE
6958 Not-a-Number (NaN).
6959 @item @emph{Standard}:
6960 GNU extension
6961
6962 @item @emph{Class}:
6963 Elemental function
6964
6965 @item @emph{Syntax}:
6966 @code{ISNAN(X)}
6967
6968 @item @emph{Arguments}:
6969 @multitable @columnfractions .15 .70
6970 @item @var{X} @tab Variable of the type @code{REAL}.
6971
6972 @end multitable
6973
6974 @item @emph{Return value}:
6975 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6976 if @var{X} is a NaN and @code{FALSE} otherwise.
6977
6978 @item @emph{Example}:
6979 @smallexample
6980 program test_nan
6981   implicit none
6982   real :: x
6983   x = -1.0
6984   x = sqrt(x)
6985   if (isnan(x)) stop '"x" is a NaN'
6986 end program test_nan
6987 @end smallexample
6988 @end table
6989
6990
6991
6992 @node ITIME
6993 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6994 @fnindex ITIME
6995 @cindex time, current
6996 @cindex current time
6997
6998 @table @asis
6999 @item @emph{Description}:
7000 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7001 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7002 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7003 respectively.
7004
7005 @item @emph{Standard}:
7006 GNU extension
7007
7008 @item @emph{Class}:
7009 Subroutine
7010
7011 @item @emph{Syntax}:
7012 @code{CALL ITIME(VALUES)}
7013
7014 @item @emph{Arguments}:
7015 @multitable @columnfractions .15 .70
7016 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7017 and the kind shall be the default integer kind.
7018 @end multitable
7019
7020 @item @emph{Return value}:
7021 Does not return anything.
7022
7023
7024 @item @emph{Example}:
7025 @smallexample
7026 program test_itime
7027   integer, dimension(3) :: tarray
7028   call itime(tarray)
7029   print *, tarray(1)
7030   print *, tarray(2)
7031   print *, tarray(3)
7032 end program test_itime
7033 @end smallexample
7034 @end table
7035
7036
7037
7038 @node KILL
7039 @section @code{KILL} --- Send a signal to a process
7040 @fnindex KILL
7041
7042 @table @asis
7043 @item @emph{Description}:
7044 @item @emph{Standard}:
7045 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7046 See @code{kill(2)}.
7047
7048 This intrinsic is provided in both subroutine and function forms; however,
7049 only one form can be used in any given program unit.
7050
7051 @item @emph{Class}:
7052 Subroutine, function
7053
7054 @item @emph{Syntax}:
7055 @multitable @columnfractions .80
7056 @item @code{CALL KILL(C, VALUE [, STATUS])}
7057 @item @code{STATUS = KILL(C, VALUE)}
7058 @end multitable
7059
7060 @item @emph{Arguments}:
7061 @multitable @columnfractions .15 .70
7062 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7063 @code{INTENT(IN)}
7064 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7065 @code{INTENT(IN)}
7066 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7067 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7068 otherwise.
7069 @end multitable
7070
7071 @item @emph{See also}:
7072 @ref{ABORT}, @ref{EXIT}
7073 @end table
7074
7075
7076
7077 @node KIND
7078 @section @code{KIND} --- Kind of an entity
7079 @fnindex KIND
7080 @cindex kind
7081
7082 @table @asis
7083 @item @emph{Description}:
7084 @code{KIND(X)} returns the kind value of the entity @var{X}.
7085
7086 @item @emph{Standard}:
7087 Fortran 95 and later
7088
7089 @item @emph{Class}:
7090 Inquiry function
7091
7092 @item @emph{Syntax}:
7093 @code{K = KIND(X)}
7094
7095 @item @emph{Arguments}:
7096 @multitable @columnfractions .15 .70
7097 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7098 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7099 @end multitable
7100
7101 @item @emph{Return value}:
7102 The return value is a scalar of type @code{INTEGER} and of the default
7103 integer kind.
7104
7105 @item @emph{Example}:
7106 @smallexample
7107 program test_kind
7108   integer,parameter :: kc = kind(' ')
7109   integer,parameter :: kl = kind(.true.)
7110
7111   print *, "The default character kind is ", kc
7112   print *, "The default logical kind is ", kl
7113 end program test_kind
7114 @end smallexample
7115
7116 @end table
7117
7118
7119
7120 @node LBOUND
7121 @section @code{LBOUND} --- Lower dimension bounds of an array
7122 @fnindex LBOUND
7123 @cindex array, lower bound
7124
7125 @table @asis
7126 @item @emph{Description}:
7127 Returns the lower bounds of an array, or a single lower bound
7128 along the @var{DIM} dimension.
7129 @item @emph{Standard}:
7130 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7131
7132 @item @emph{Class}:
7133 Inquiry function
7134
7135 @item @emph{Syntax}:
7136 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7137
7138 @item @emph{Arguments}:
7139 @multitable @columnfractions .15 .70
7140 @item @var{ARRAY} @tab Shall be an array, of any type.
7141 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7142 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7143 expression indicating the kind parameter of the result.
7144 @end multitable
7145
7146 @item @emph{Return value}:
7147 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7148 @var{KIND} is absent, the return value is of default integer kind.
7149 If @var{DIM} is absent, the result is an array of the lower bounds of
7150 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
7151 corresponding to the lower bound of the array along that dimension.  If
7152 @var{ARRAY} is an expression rather than a whole array or array
7153 structure component, or if it has a zero extent along the relevant
7154 dimension, the lower bound is taken to be 1.
7155
7156 @item @emph{See also}:
7157 @ref{UBOUND}, @ref{LCOBOUND}
7158 @end table
7159
7160
7161
7162 @node LCOBOUND
7163 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7164 @fnindex LCOBOUND
7165 @cindex coarray, lower bound
7166
7167 @table @asis
7168 @item @emph{Description}:
7169 Returns the lower bounds of a coarray, or a single lower cobound
7170 along the @var{DIM} codimension.
7171 @item @emph{Standard}:
7172 Fortran 2008 and later
7173
7174 @item @emph{Class}:
7175 Inquiry function
7176
7177 @item @emph{Syntax}:
7178 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7179
7180 @item @emph{Arguments}:
7181 @multitable @columnfractions .15 .70
7182 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7183 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7184 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7185 expression indicating the kind parameter of the result.
7186 @end multitable
7187
7188 @item @emph{Return value}:
7189 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7190 @var{KIND} is absent, the return value is of default integer kind.
7191 If @var{DIM} is absent, the result is an array of the lower cobounds of
7192 @var{COARRAY}.  If @var{DIM} is present, the result is a scalar
7193 corresponding to the lower cobound of the array along that codimension.
7194
7195 @item @emph{See also}:
7196 @ref{UCOBOUND}, @ref{LBOUND}
7197 @end table
7198
7199
7200
7201 @node LEADZ
7202 @section @code{LEADZ} --- Number of leading zero bits of an integer
7203 @fnindex LEADZ
7204 @cindex zero bits
7205
7206 @table @asis
7207 @item @emph{Description}:
7208 @code{LEADZ} returns the number of leading zero bits of an integer.
7209
7210 @item @emph{Standard}:
7211 Fortran 2008 and later
7212
7213 @item @emph{Class}:
7214 Elemental function
7215
7216 @item @emph{Syntax}:
7217 @code{RESULT = LEADZ(I)}
7218
7219 @item @emph{Arguments}:
7220 @multitable @columnfractions .15 .70
7221 @item @var{I} @tab Shall be of type @code{INTEGER}.
7222 @end multitable
7223
7224 @item @emph{Return value}:
7225 The type of the return value is the default @code{INTEGER}.
7226 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7227
7228 @item @emph{Example}:
7229 @smallexample
7230 PROGRAM test_leadz
7231   WRITE (*,*) LEADZ(1)  ! prints 8 if BITSIZE(I) has the value 32
7232 END PROGRAM
7233 @end smallexample
7234
7235 @item @emph{See also}:
7236 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7237 @end table
7238
7239
7240
7241 @node LEN
7242 @section @code{LEN} --- Length of a character entity
7243 @fnindex LEN
7244 @cindex string, length
7245
7246 @table @asis
7247 @item @emph{Description}:
7248 Returns the length of a character string.  If @var{STRING} is an array,
7249 the length of an element of @var{STRING} is returned.  Note that
7250 @var{STRING} need not be defined when this intrinsic is invoked, since
7251 only the length, not the content, of @var{STRING} is needed.
7252
7253 @item @emph{Standard}:
7254 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7255
7256 @item @emph{Class}:
7257 Inquiry function
7258
7259 @item @emph{Syntax}:
7260 @code{L = LEN(STRING [, KIND])}
7261
7262 @item @emph{Arguments}:
7263 @multitable @columnfractions .15 .70
7264 @item @var{STRING} @tab Shall be a scalar or array of type
7265 @code{CHARACTER}, with @code{INTENT(IN)}
7266 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7267 expression indicating the kind parameter of the result.
7268 @end multitable
7269
7270 @item @emph{Return value}:
7271 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7272 @var{KIND} is absent, the return value is of default integer kind.
7273
7274
7275 @item @emph{Specific names}:
7276 @multitable @columnfractions .20 .20 .20 .25
7277 @item Name               @tab Argument          @tab Return type       @tab Standard
7278 @item @code{LEN(STRING)} @tab @code{CHARACTER}  @tab @code{INTEGER}    @tab Fortran 77 and later
7279 @end multitable
7280
7281
7282 @item @emph{See also}:
7283 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7284 @end table
7285
7286
7287
7288 @node LEN_TRIM
7289 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7290 @fnindex LEN_TRIM
7291 @cindex string, length, without trailing whitespace
7292
7293 @table @asis
7294 @item @emph{Description}:
7295 Returns the length of a character string, ignoring any trailing blanks.
7296
7297 @item @emph{Standard}:
7298 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7299
7300 @item @emph{Class}:
7301 Elemental function
7302
7303 @item @emph{Syntax}:
7304 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7305
7306 @item @emph{Arguments}:
7307 @multitable @columnfractions .15 .70
7308 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7309 with @code{INTENT(IN)}
7310 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7311 expression indicating the kind parameter of the result.
7312 @end multitable
7313
7314 @item @emph{Return value}:
7315 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7316 @var{KIND} is absent, the return value is of default integer kind.
7317
7318 @item @emph{See also}:
7319 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7320 @end table
7321
7322
7323
7324 @node LGE
7325 @section @code{LGE} --- Lexical greater than or equal
7326 @fnindex LGE
7327 @cindex lexical comparison of strings
7328 @cindex string, comparison
7329
7330 @table @asis
7331 @item @emph{Description}:
7332 Determines whether one string is lexically greater than or equal to
7333 another string, where the two strings are interpreted as containing
7334 ASCII character codes.  If the String A and String B are not the same
7335 length, the shorter is compared as if spaces were appended to it to form
7336 a value that has the same length as the longer.
7337
7338 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7339 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7340 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7341 that the latter use the processor's character ordering (which is not
7342 ASCII on some targets), whereas the former always use the ASCII
7343 ordering.
7344
7345 @item @emph{Standard}:
7346 Fortran 77 and later
7347
7348 @item @emph{Class}:
7349 Elemental function
7350
7351 @item @emph{Syntax}:
7352 @code{RESULT = LGE(STRING_A, STRING_B)}
7353
7354 @item @emph{Arguments}:
7355 @multitable @columnfractions .15 .70
7356 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7357 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7358 @end multitable
7359
7360 @item @emph{Return value}:
7361 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7362 otherwise, based on the ASCII ordering.
7363
7364 @item @emph{Specific names}:
7365 @multitable @columnfractions .20 .20 .20 .25
7366 @item Name                           @tab Argument          @tab Return type       @tab Standard
7367 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7368 @end multitable
7369
7370 @item @emph{See also}:
7371 @ref{LGT}, @ref{LLE}, @ref{LLT}
7372 @end table
7373
7374
7375
7376 @node LGT
7377 @section @code{LGT} --- Lexical greater than
7378 @fnindex LGT
7379 @cindex lexical comparison of strings
7380 @cindex string, comparison
7381
7382 @table @asis
7383 @item @emph{Description}:
7384 Determines whether one string is lexically greater than another string,
7385 where the two strings are interpreted as containing ASCII character
7386 codes.  If the String A and String B are not the same length, the
7387 shorter is compared as if spaces were appended to it to form a value
7388 that has the same length as the longer.
7389
7390 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7391 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7392 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7393 that the latter use the processor's character ordering (which is not
7394 ASCII on some targets), whereas the former always use the ASCII
7395 ordering.
7396
7397 @item @emph{Standard}:
7398 Fortran 77 and later
7399
7400 @item @emph{Class}:
7401 Elemental function
7402
7403 @item @emph{Syntax}:
7404 @code{RESULT = LGT(STRING_A, STRING_B)}
7405
7406 @item @emph{Arguments}:
7407 @multitable @columnfractions .15 .70
7408 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7409 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7410 @end multitable
7411
7412 @item @emph{Return value}:
7413 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7414 otherwise, based on the ASCII ordering.
7415
7416 @item @emph{Specific names}:
7417 @multitable @columnfractions .20 .20 .20 .25
7418 @item Name                           @tab Argument          @tab Return type       @tab Standard
7419 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7420 @end multitable
7421
7422 @item @emph{See also}:
7423 @ref{LGE}, @ref{LLE}, @ref{LLT}
7424 @end table
7425
7426
7427
7428 @node LINK
7429 @section @code{LINK} --- Create a hard link
7430 @fnindex LINK
7431 @cindex file system, create link
7432 @cindex file system, hard link
7433
7434 @table @asis
7435 @item @emph{Description}:
7436 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7437 character (@code{CHAR(0)}) can be used to mark the end of the names in
7438 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7439 names are ignored.  If the @var{STATUS} argument is supplied, it
7440 contains 0 on success or a nonzero error code upon return; see
7441 @code{link(2)}.
7442
7443 This intrinsic is provided in both subroutine and function forms;
7444 however, only one form can be used in any given program unit.
7445
7446 @item @emph{Standard}:
7447 GNU extension
7448
7449 @item @emph{Class}:
7450 Subroutine, function
7451
7452 @item @emph{Syntax}:
7453 @multitable @columnfractions .80
7454 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7455 @item @code{STATUS = LINK(PATH1, PATH2)}
7456 @end multitable
7457
7458 @item @emph{Arguments}:
7459 @multitable @columnfractions .15 .70
7460 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7461 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7462 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7463 @end multitable
7464
7465 @item @emph{See also}:
7466 @ref{SYMLNK}, @ref{UNLINK}
7467 @end table
7468
7469
7470
7471 @node LLE
7472 @section @code{LLE} --- Lexical less than or equal
7473 @fnindex LLE
7474 @cindex lexical comparison of strings
7475 @cindex string, comparison
7476
7477 @table @asis
7478 @item @emph{Description}:
7479 Determines whether one string is lexically less than or equal to another
7480 string, where the two strings are interpreted as containing ASCII
7481 character codes.  If the String A and String B are not the same length,
7482 the shorter is compared as if spaces were appended to it to form a value
7483 that has the same length as the longer.
7484
7485 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7486 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7487 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7488 that the latter use the processor's character ordering (which is not
7489 ASCII on some targets), whereas the former always use the ASCII
7490 ordering.
7491
7492 @item @emph{Standard}:
7493 Fortran 77 and later
7494
7495 @item @emph{Class}:
7496 Elemental function
7497
7498 @item @emph{Syntax}:
7499 @code{RESULT = LLE(STRING_A, STRING_B)}
7500
7501 @item @emph{Arguments}:
7502 @multitable @columnfractions .15 .70
7503 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7504 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7505 @end multitable
7506
7507 @item @emph{Return value}:
7508 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7509 otherwise, based on the ASCII ordering.
7510
7511 @item @emph{Specific names}:
7512 @multitable @columnfractions .20 .20 .20 .25
7513 @item Name                           @tab Argument          @tab Return type       @tab Standard
7514 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7515 @end multitable
7516
7517 @item @emph{See also}:
7518 @ref{LGE}, @ref{LGT}, @ref{LLT}
7519 @end table
7520
7521
7522
7523 @node LLT
7524 @section @code{LLT} --- Lexical less than
7525 @fnindex LLT
7526 @cindex lexical comparison of strings
7527 @cindex string, comparison
7528
7529 @table @asis
7530 @item @emph{Description}:
7531 Determines whether one string is lexically less than another string,
7532 where the two strings are interpreted as containing ASCII character
7533 codes.  If the String A and String B are not the same length, the
7534 shorter is compared as if spaces were appended to it to form a value
7535 that has the same length as the longer.
7536
7537 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7538 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7539 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7540 that the latter use the processor's character ordering (which is not
7541 ASCII on some targets), whereas the former always use the ASCII
7542 ordering.
7543
7544 @item @emph{Standard}:
7545 Fortran 77 and later
7546
7547 @item @emph{Class}:
7548 Elemental function
7549
7550 @item @emph{Syntax}:
7551 @code{RESULT = LLT(STRING_A, STRING_B)}
7552
7553 @item @emph{Arguments}:
7554 @multitable @columnfractions .15 .70
7555 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7556 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7557 @end multitable
7558
7559 @item @emph{Return value}:
7560 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7561 otherwise, based on the ASCII ordering.
7562
7563 @item @emph{Specific names}:
7564 @multitable @columnfractions .20 .20 .20 .25
7565 @item Name                           @tab Argument          @tab Return type       @tab Standard
7566 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7567 @end multitable
7568
7569 @item @emph{See also}:
7570 @ref{LGE}, @ref{LGT}, @ref{LLE}
7571 @end table
7572
7573
7574
7575 @node LNBLNK
7576 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7577 @fnindex LNBLNK
7578 @cindex string, find non-blank character
7579
7580 @table @asis
7581 @item @emph{Description}:
7582 Returns the length of a character string, ignoring any trailing blanks.
7583 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7584 included for backwards compatibility.
7585
7586 @item @emph{Standard}:
7587 GNU extension
7588
7589 @item @emph{Class}:
7590 Elemental function
7591
7592 @item @emph{Syntax}:
7593 @code{RESULT = LNBLNK(STRING)}
7594
7595 @item @emph{Arguments}:
7596 @multitable @columnfractions .15 .70
7597 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7598 with @code{INTENT(IN)}
7599 @end multitable
7600
7601 @item @emph{Return value}:
7602 The return value is of @code{INTEGER(kind=4)} type.
7603
7604 @item @emph{See also}:
7605 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7606 @end table
7607
7608
7609
7610 @node LOC
7611 @section @code{LOC} --- Returns the address of a variable
7612 @fnindex LOC
7613 @cindex location of a variable in memory
7614
7615 @table @asis
7616 @item @emph{Description}:
7617 @code{LOC(X)} returns the address of @var{X} as an integer.
7618
7619 @item @emph{Standard}:
7620 GNU extension
7621
7622 @item @emph{Class}:
7623 Inquiry function
7624
7625 @item @emph{Syntax}:
7626 @code{RESULT = LOC(X)}
7627
7628 @item @emph{Arguments}:
7629 @multitable @columnfractions .15 .70
7630 @item @var{X} @tab Variable of any type.
7631 @end multitable
7632
7633 @item @emph{Return value}:
7634 The return value is of type @code{INTEGER}, with a @code{KIND}
7635 corresponding to the size (in bytes) of a memory address on the target
7636 machine.
7637
7638 @item @emph{Example}:
7639 @smallexample
7640 program test_loc
7641   integer :: i
7642   real :: r
7643   i = loc(r)
7644   print *, i
7645 end program test_loc
7646 @end smallexample
7647 @end table
7648
7649
7650
7651 @node LOG
7652 @section @code{LOG} --- Logarithm function
7653 @fnindex LOG
7654 @fnindex ALOG
7655 @fnindex DLOG
7656 @fnindex CLOG
7657 @fnindex ZLOG
7658 @fnindex CDLOG
7659 @cindex exponential function, inverse
7660 @cindex logarithmic function
7661
7662 @table @asis
7663 @item @emph{Description}:
7664 @code{LOG(X)} computes the logarithm of @var{X}.
7665
7666 @item @emph{Standard}:
7667 Fortran 77 and later
7668
7669 @item @emph{Class}:
7670 Elemental function
7671
7672 @item @emph{Syntax}:
7673 @code{RESULT = LOG(X)}
7674
7675 @item @emph{Arguments}:
7676 @multitable @columnfractions .15 .70
7677 @item @var{X} @tab The type shall be @code{REAL} or
7678 @code{COMPLEX}.
7679 @end multitable
7680
7681 @item @emph{Return value}:
7682 The return value is of type @code{REAL} or @code{COMPLEX}.
7683 The kind type parameter is the same as @var{X}.
7684 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7685 @math{-\pi \leq \omega \leq \pi}.
7686
7687 @item @emph{Example}:
7688 @smallexample
7689 program test_log
7690   real(8) :: x = 1.0_8
7691   complex :: z = (1.0, 2.0)
7692   x = log(x)
7693   z = log(z)
7694 end program test_log
7695 @end smallexample
7696
7697 @item @emph{Specific names}:
7698 @multitable @columnfractions .20 .20 .20 .25
7699 @item Name            @tab Argument          @tab Return type       @tab Standard
7700 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
7701 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
7702 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
7703 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7704 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7705 @end multitable
7706 @end table
7707
7708
7709
7710 @node LOG10
7711 @section @code{LOG10} --- Base 10 logarithm function
7712 @fnindex LOG10
7713 @fnindex ALOG10
7714 @fnindex DLOG10
7715 @cindex exponential function, inverse
7716 @cindex logarithmic function
7717
7718 @table @asis
7719 @item @emph{Description}:
7720 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7721
7722 @item @emph{Standard}:
7723 Fortran 77 and later
7724
7725 @item @emph{Class}:
7726 Elemental function
7727
7728 @item @emph{Syntax}:
7729 @code{RESULT = LOG10(X)}
7730
7731 @item @emph{Arguments}:
7732 @multitable @columnfractions .15 .70
7733 @item @var{X} @tab The type shall be @code{REAL}.
7734 @end multitable
7735
7736 @item @emph{Return value}:
7737 The return value is of type @code{REAL} or @code{COMPLEX}.
7738 The kind type parameter is the same as @var{X}.
7739
7740 @item @emph{Example}:
7741 @smallexample
7742 program test_log10
7743   real(8) :: x = 10.0_8
7744   x = log10(x)
7745 end program test_log10
7746 @end smallexample
7747
7748 @item @emph{Specific names}:
7749 @multitable @columnfractions .20 .20 .20 .25
7750 @item Name            @tab Argument          @tab Return type       @tab Standard
7751 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
7752 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
7753 @end multitable
7754 @end table
7755
7756
7757
7758 @node LOG_GAMMA
7759 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7760 @fnindex LOG_GAMMA
7761 @fnindex LGAMMA
7762 @fnindex ALGAMA
7763 @fnindex DLGAMA
7764 @cindex Gamma function, logarithm of
7765
7766 @table @asis
7767 @item @emph{Description}:
7768 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7769 of the Gamma (@math{\Gamma}) function.
7770
7771 @item @emph{Standard}:
7772 Fortran 2008 and later
7773
7774 @item @emph{Class}:
7775 Elemental function
7776
7777 @item @emph{Syntax}:
7778 @code{X = LOG_GAMMA(X)}
7779
7780 @item @emph{Arguments}:
7781 @multitable @columnfractions .15 .70
7782 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7783 nor a negative integer.
7784 @end multitable
7785
7786 @item @emph{Return value}:
7787 The return value is of type @code{REAL} of the same kind as @var{X}.
7788
7789 @item @emph{Example}:
7790 @smallexample
7791 program test_log_gamma
7792   real :: x = 1.0
7793   x = lgamma(x) ! returns 0.0
7794 end program test_log_gamma
7795 @end smallexample
7796
7797 @item @emph{Specific names}:
7798 @multitable @columnfractions .20 .20 .20 .25
7799 @item Name             @tab Argument         @tab Return type       @tab Standard
7800 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
7801 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
7802 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
7803 @end multitable
7804
7805 @item @emph{See also}:
7806 Gamma function: @ref{GAMMA}
7807
7808 @end table
7809
7810
7811
7812 @node LOGICAL
7813 @section @code{LOGICAL} --- Convert to logical type
7814 @fnindex LOGICAL
7815 @cindex conversion, to logical
7816
7817 @table @asis
7818 @item @emph{Description}:
7819 Converts one kind of @code{LOGICAL} variable to another.
7820
7821 @item @emph{Standard}:
7822 Fortran 95 and later
7823
7824 @item @emph{Class}:
7825 Elemental function
7826
7827 @item @emph{Syntax}:
7828 @code{RESULT = LOGICAL(L [, KIND])}
7829
7830 @item @emph{Arguments}:
7831 @multitable @columnfractions .15 .70
7832 @item @var{L}    @tab The type shall be @code{LOGICAL}.
7833 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7834 expression indicating the kind parameter of the result.
7835 @end multitable
7836
7837 @item @emph{Return value}:
7838 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7839 kind corresponding to @var{KIND}, or of the default logical kind if
7840 @var{KIND} is not given.
7841
7842 @item @emph{See also}:
7843 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7844 @end table
7845
7846
7847
7848 @node LONG
7849 @section @code{LONG} --- Convert to integer type
7850 @fnindex LONG
7851 @cindex conversion, to integer
7852
7853 @table @asis
7854 @item @emph{Description}:
7855 Convert to a @code{KIND=4} integer type, which is the same size as a C
7856 @code{long} integer.  This is equivalent to the standard @code{INT}
7857 intrinsic with an optional argument of @code{KIND=4}, and is only
7858 included for backwards compatibility.
7859
7860 @item @emph{Standard}:
7861 GNU extension
7862
7863 @item @emph{Class}:
7864 Elemental function
7865
7866 @item @emph{Syntax}:
7867 @code{RESULT = LONG(A)}
7868
7869 @item @emph{Arguments}:
7870 @multitable @columnfractions .15 .70
7871 @item @var{A}    @tab Shall be of type @code{INTEGER},
7872 @code{REAL}, or @code{COMPLEX}.
7873 @end multitable
7874
7875 @item @emph{Return value}:
7876 The return value is a @code{INTEGER(4)} variable.
7877
7878 @item @emph{See also}:
7879 @ref{INT}, @ref{INT2}, @ref{INT8}
7880 @end table
7881
7882
7883
7884 @node LSHIFT
7885 @section @code{LSHIFT} --- Left shift bits
7886 @fnindex LSHIFT
7887 @cindex bits, shift left
7888
7889 @table @asis
7890 @item @emph{Description}:
7891 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7892 bits shifted left by @var{SHIFT} places.  If the absolute value of
7893 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7894 Bits shifted out from the left end are lost; zeros are shifted in from
7895 the opposite end.
7896
7897 This function has been superseded by the @code{ISHFT} intrinsic, which
7898 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
7899 which is standard in Fortran 2008 and later.
7900
7901 @item @emph{Standard}:
7902 GNU extension
7903
7904 @item @emph{Class}:
7905 Elemental function
7906
7907 @item @emph{Syntax}:
7908 @code{RESULT = LSHIFT(I, SHIFT)}
7909
7910 @item @emph{Arguments}:
7911 @multitable @columnfractions .15 .70
7912 @item @var{I} @tab The type shall be @code{INTEGER}.
7913 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7914 @end multitable
7915
7916 @item @emph{Return value}:
7917 The return value is of type @code{INTEGER} and of the same kind as
7918 @var{I}.
7919
7920 @item @emph{See also}:
7921 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
7922 @ref{SHIFTR}
7923
7924 @end table
7925
7926
7927
7928 @node LSTAT
7929 @section @code{LSTAT} --- Get file status
7930 @fnindex LSTAT
7931 @cindex file system, file status
7932
7933 @table @asis
7934 @item @emph{Description}:
7935 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7936 symbolic link, then the link itself is statted, not the file that it
7937 refers to.
7938
7939 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7940
7941 This intrinsic is provided in both subroutine and function forms;
7942 however, only one form can be used in any given program unit.
7943
7944 @item @emph{Standard}:
7945 GNU extension
7946
7947 @item @emph{Class}:
7948 Subroutine, function
7949
7950 @item @emph{Syntax}:
7951 @multitable @columnfractions .80
7952 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7953 @item @code{STATUS = LSTAT(NAME, VALUES)}
7954 @end multitable
7955
7956 @item @emph{Arguments}:
7957 @multitable @columnfractions .15 .70
7958 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of the default
7959 kind, a valid path within the file system.
7960 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7961 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7962 Returns 0 on success and a system specific error code otherwise.
7963 @end multitable
7964
7965 @item @emph{Example}:
7966 See @ref{STAT} for an example.
7967
7968 @item @emph{See also}:
7969 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7970 @end table
7971
7972
7973
7974 @node LTIME
7975 @section @code{LTIME} --- Convert time to local time info
7976 @fnindex LTIME
7977 @cindex time, conversion to local time info
7978
7979 @table @asis
7980 @item @emph{Description}:
7981 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7982 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7983 to the local time zone using @code{localtime(3)}.
7984
7985 @item @emph{Standard}:
7986 GNU extension
7987
7988 @item @emph{Class}:
7989 Subroutine
7990
7991 @item @emph{Syntax}:
7992 @code{CALL LTIME(TIME, VALUES)}
7993
7994 @item @emph{Arguments}:
7995 @multitable @columnfractions .15 .70
7996 @item @var{TIME}  @tab An @code{INTEGER} scalar expression
7997 corresponding to a system time, with @code{INTENT(IN)}.
7998 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7999 with @code{INTENT(OUT)}.
8000 @end multitable
8001
8002 @item @emph{Return value}:
8003 The elements of @var{VALUES} are assigned as follows:
8004 @enumerate
8005 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8006 seconds
8007 @item Minutes after the hour, range 0--59
8008 @item Hours past midnight, range 0--23
8009 @item Day of month, range 0--31
8010 @item Number of months since January, range 0--12
8011 @item Years since 1900
8012 @item Number of days since Sunday, range 0--6
8013 @item Days since January 1
8014 @item Daylight savings indicator: positive if daylight savings is in
8015 effect, zero if not, and negative if the information is not available.
8016 @end enumerate
8017
8018 @item @emph{See also}:
8019 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8020
8021 @end table
8022
8023
8024
8025 @node MALLOC
8026 @section @code{MALLOC} --- Allocate dynamic memory
8027 @fnindex MALLOC
8028 @cindex pointer, cray
8029
8030 @table @asis
8031 @item @emph{Description}:
8032 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8033 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8034 is an extension intended to be used with Cray pointers, and is provided
8035 in GNU Fortran to allow the user to compile legacy code. For new code
8036 using Fortran 95 pointers, the memory allocation intrinsic is
8037 @code{ALLOCATE}.
8038
8039 @item @emph{Standard}:
8040 GNU extension
8041
8042 @item @emph{Class}:
8043 Function
8044
8045 @item @emph{Syntax}:
8046 @code{PTR = MALLOC(SIZE)}
8047
8048 @item @emph{Arguments}:
8049 @multitable @columnfractions .15 .70
8050 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8051 @end multitable
8052
8053 @item @emph{Return value}:
8054 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8055 variables of type @code{INTEGER(K)} have the same size as
8056 C pointers (@code{sizeof(void *)}).
8057
8058 @item @emph{Example}:
8059 The following example demonstrates the use of @code{MALLOC} and
8060 @code{FREE} with Cray pointers.
8061
8062 @smallexample
8063 program test_malloc
8064   implicit none
8065   integer i
8066   real*8 x(*), z
8067   pointer(ptr_x,x)
8068
8069   ptr_x = malloc(20*8)
8070   do i = 1, 20
8071     x(i) = sqrt(1.0d0 / i)
8072   end do
8073   z = 0
8074   do i = 1, 20
8075     z = z + x(i)
8076     print *, z
8077   end do
8078   call free(ptr_x)
8079 end program test_malloc
8080 @end smallexample
8081
8082 @item @emph{See also}:
8083 @ref{FREE}
8084 @end table
8085
8086
8087
8088 @node MASKL
8089 @section @code{MASKL} --- Left justified mask
8090 @fnindex MASKL
8091 @cindex mask, left justified
8092
8093 @table @asis
8094 @item @emph{Description}:
8095 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8096 remaining bits set to 0.
8097
8098 @item @emph{Standard}:
8099 Fortran 2008 and later
8100
8101 @item @emph{Class}:
8102 Elemental function
8103
8104 @item @emph{Syntax}:
8105 @code{RESULT = MASKL(I[, KIND])}
8106
8107 @item @emph{Arguments}:
8108 @multitable @columnfractions .15 .70
8109 @item @var{I} @tab Shall be of type @code{INTEGER}.
8110 @item @var{KIND} @tab Shall be a scalar constant expression of type
8111 @code{INTEGER}.
8112 @end multitable
8113
8114 @item @emph{Return value}:
8115 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8116 specifies the kind value of the return type; otherwise, it is of the
8117 default integer kind.
8118
8119 @item @emph{See also}:
8120 @ref{MASKR}
8121 @end table
8122
8123
8124
8125 @node MASKR
8126 @section @code{MASKR} --- Right justified mask
8127 @fnindex MASKR
8128 @cindex mask, right justified
8129
8130 @table @asis
8131 @item @emph{Description}:
8132 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8133 remaining bits set to 0.
8134
8135 @item @emph{Standard}:
8136 Fortran 2008 and later
8137
8138 @item @emph{Class}:
8139 Elemental function
8140
8141 @item @emph{Syntax}:
8142 @code{RESULT = MASKR(I[, KIND])}
8143
8144 @item @emph{Arguments}:
8145 @multitable @columnfractions .15 .70
8146 @item @var{I} @tab Shall be of type @code{INTEGER}.
8147 @item @var{KIND} @tab Shall be a scalar constant expression of type
8148 @code{INTEGER}.
8149 @end multitable
8150
8151 @item @emph{Return value}:
8152 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8153 specifies the kind value of the return type; otherwise, it is of the
8154 default integer kind.
8155
8156 @item @emph{See also}:
8157 @ref{MASKL}
8158 @end table
8159
8160
8161
8162 @node MATMUL
8163 @section @code{MATMUL} --- matrix multiplication
8164 @fnindex MATMUL
8165 @cindex matrix multiplication
8166 @cindex product, matrix
8167
8168 @table @asis
8169 @item @emph{Description}:
8170 Performs a matrix multiplication on numeric or logical arguments.
8171
8172 @item @emph{Standard}:
8173 Fortran 95 and later
8174
8175 @item @emph{Class}:
8176 Transformational function
8177
8178 @item @emph{Syntax}:
8179 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8180
8181 @item @emph{Arguments}:
8182 @multitable @columnfractions .15 .70
8183 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8184 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8185 one or two.
8186 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8187 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8188 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8189 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8190 equal to the last (or only) dimension of @var{MATRIX_A}.
8191 @end multitable
8192
8193 @item @emph{Return value}:
8194 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
8195 kind of the result follow the usual type and kind promotion rules, as
8196 for the @code{*} or @code{.AND.} operators.
8197
8198 @item @emph{See also}:
8199 @end table
8200
8201
8202
8203 @node MAX
8204 @section @code{MAX} --- Maximum value of an argument list
8205 @fnindex MAX
8206 @fnindex MAX0
8207 @fnindex AMAX0
8208 @fnindex MAX1
8209 @fnindex AMAX1
8210 @fnindex DMAX1
8211 @cindex maximum value
8212
8213 @table @asis
8214 @item @emph{Description}:
8215 Returns the argument with the largest (most positive) value.
8216
8217 @item @emph{Standard}:
8218 Fortran 77 and later
8219
8220 @item @emph{Class}:
8221 Elemental function
8222
8223 @item @emph{Syntax}:
8224 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8225
8226 @item @emph{Arguments}:
8227 @multitable @columnfractions .15 .70
8228 @item @var{A1}          @tab The type shall be @code{INTEGER} or
8229 @code{REAL}.
8230 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8231 as @var{A1}.  (As a GNU extension, arguments of different kinds are
8232 permitted.)
8233 @end multitable
8234
8235 @item @emph{Return value}:
8236 The return value corresponds to the maximum value among the arguments,
8237 and has the same type and kind as the first argument.
8238
8239 @item @emph{Specific names}:
8240 @multitable @columnfractions .20 .20 .20 .25
8241 @item Name             @tab Argument             @tab Return type         @tab Standard
8242 @item @code{MAX0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
8243 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8244 @item @code{MAX1(A1)}  @tab @code{REAL A1}       @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
8245 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1}    @tab @code{REAL(4)}      @tab Fortran 77 and later
8246 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1}    @tab @code{REAL(8)}      @tab Fortran 77 and later
8247 @end multitable
8248
8249 @item @emph{See also}:
8250 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8251
8252 @end table
8253
8254
8255
8256 @node MAXEXPONENT
8257 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8258 @fnindex MAXEXPONENT
8259 @cindex model representation, maximum exponent
8260
8261 @table @asis
8262 @item @emph{Description}:
8263 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8264 type of @code{X}.
8265
8266 @item @emph{Standard}:
8267 Fortran 95 and later
8268
8269 @item @emph{Class}:
8270 Inquiry function
8271
8272 @item @emph{Syntax}:
8273 @code{RESULT = MAXEXPONENT(X)}
8274
8275 @item @emph{Arguments}:
8276 @multitable @columnfractions .15 .70
8277 @item @var{X} @tab Shall be of type @code{REAL}.
8278 @end multitable
8279
8280 @item @emph{Return value}:
8281 The return value is of type @code{INTEGER} and of the default integer
8282 kind.
8283
8284 @item @emph{Example}:
8285 @smallexample
8286 program exponents
8287   real(kind=4) :: x
8288   real(kind=8) :: y
8289
8290   print *, minexponent(x), maxexponent(x)
8291   print *, minexponent(y), maxexponent(y)
8292 end program exponents
8293 @end smallexample
8294 @end table
8295
8296
8297
8298 @node MAXLOC
8299 @section @code{MAXLOC} --- Location of the maximum value within an array
8300 @fnindex MAXLOC
8301 @cindex array, location of maximum element
8302
8303 @table @asis
8304 @item @emph{Description}:
8305 Determines the location of the element in the array with the maximum
8306 value, or, if the @var{DIM} argument is supplied, determines the
8307 locations of the maximum element along each row of the array in the
8308 @var{DIM} direction.  If @var{MASK} is present, only the elements for
8309 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8310 element in the array has the maximum value, the location returned is
8311 that of the first such element in array element order.  If the array has
8312 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8313 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8314 and all of the elements of @var{MASK} along a given row are zero, the
8315 result value for that row is zero.
8316
8317 @item @emph{Standard}:
8318 Fortran 95 and later
8319
8320 @item @emph{Class}:
8321 Transformational function
8322
8323 @item @emph{Syntax}:
8324 @multitable @columnfractions .80
8325 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8326 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8327 @end multitable
8328
8329 @item @emph{Arguments}:
8330 @multitable @columnfractions .15 .70
8331 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8332 @code{REAL}.
8333 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8334 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8335 inclusive.  It may not be an optional dummy argument.
8336 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8337 and conformable with @var{ARRAY}.
8338 @end multitable
8339
8340 @item @emph{Return value}:
8341 If @var{DIM} is absent, the result is a rank-one array with a length
8342 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8343 is an array with a rank one less than the rank of @var{ARRAY}, and a
8344 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8345 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8346 of one, the result is a scalar.  In all cases, the result is of default
8347 @code{INTEGER} type.
8348
8349 @item @emph{See also}:
8350 @ref{MAX}, @ref{MAXVAL}
8351
8352 @end table
8353
8354
8355
8356 @node MAXVAL
8357 @section @code{MAXVAL} --- Maximum value of an array
8358 @fnindex MAXVAL
8359 @cindex array, maximum value
8360 @cindex maximum value
8361
8362 @table @asis
8363 @item @emph{Description}:
8364 Determines the maximum value of the elements in an array value, or, if
8365 the @var{DIM} argument is supplied, determines the maximum value along
8366 each row of the array in the @var{DIM} direction.  If @var{MASK} is
8367 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8368 considered.  If the array has zero size, or all of the elements of
8369 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8370 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8371 type.
8372
8373 @item @emph{Standard}:
8374 Fortran 95 and later
8375
8376 @item @emph{Class}:
8377 Transformational function
8378
8379 @item @emph{Syntax}:
8380 @multitable @columnfractions .80
8381 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8382 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8383 @end multitable
8384
8385 @item @emph{Arguments}:
8386 @multitable @columnfractions .15 .70
8387 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8388 @code{REAL}.
8389 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8390 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8391 inclusive.  It may not be an optional dummy argument.
8392 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8393 and conformable with @var{ARRAY}.
8394 @end multitable
8395
8396 @item @emph{Return value}:
8397 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8398 is a scalar.  If @var{DIM} is present, the result is an array with a
8399 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8400 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8401 cases, the result is of the same type and kind as @var{ARRAY}.
8402
8403 @item @emph{See also}:
8404 @ref{MAX}, @ref{MAXLOC}
8405 @end table
8406
8407
8408
8409 @node MCLOCK
8410 @section @code{MCLOCK} --- Time function
8411 @fnindex MCLOCK
8412 @cindex time, clock ticks
8413 @cindex clock ticks
8414
8415 @table @asis
8416 @item @emph{Description}:
8417 Returns the number of clock ticks since the start of the process, based
8418 on the UNIX function @code{clock(3)}.
8419
8420 This intrinsic is not fully portable, such as to systems with 32-bit
8421 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8422 the values returned by this intrinsic might be, or become, negative, or
8423 numerically less than previous values, during a single run of the
8424 compiled program.
8425
8426 @item @emph{Standard}:
8427 GNU extension
8428
8429 @item @emph{Class}:
8430 Function
8431
8432 @item @emph{Syntax}:
8433 @code{RESULT = MCLOCK()}
8434
8435 @item @emph{Return value}:
8436 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8437 number of clock ticks since the start of the process, or @code{-1} if
8438 the system does not support @code{clock(3)}.
8439
8440 @item @emph{See also}:
8441 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8442
8443 @end table
8444
8445
8446
8447 @node MCLOCK8
8448 @section @code{MCLOCK8} --- Time function (64-bit)
8449 @fnindex MCLOCK8
8450 @cindex time, clock ticks
8451 @cindex clock ticks
8452
8453 @table @asis
8454 @item @emph{Description}:
8455 Returns the number of clock ticks since the start of the process, based
8456 on the UNIX function @code{clock(3)}.
8457
8458 @emph{Warning:} this intrinsic does not increase the range of the timing
8459 values over that returned by @code{clock(3)}. On a system with a 32-bit
8460 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
8461 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8462 overflows of the 32-bit value can still occur. Therefore, the values
8463 returned by this intrinsic might be or become negative or numerically
8464 less than previous values during a single run of the compiled program.
8465
8466 @item @emph{Standard}:
8467 GNU extension
8468
8469 @item @emph{Class}:
8470 Function
8471
8472 @item @emph{Syntax}:
8473 @code{RESULT = MCLOCK8()}
8474
8475 @item @emph{Return value}:
8476 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8477 number of clock ticks since the start of the process, or @code{-1} if
8478 the system does not support @code{clock(3)}.
8479
8480 @item @emph{See also}:
8481 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8482
8483 @end table
8484
8485
8486
8487 @node MERGE
8488 @section @code{MERGE} --- Merge variables
8489 @fnindex MERGE
8490 @cindex array, merge arrays
8491 @cindex array, combine arrays
8492
8493 @table @asis
8494 @item @emph{Description}:
8495 Select values from two arrays according to a logical mask.  The result
8496 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8497 @var{FSOURCE} if it is @code{.FALSE.}.
8498
8499 @item @emph{Standard}:
8500 Fortran 95 and later
8501
8502 @item @emph{Class}:
8503 Elemental function
8504
8505 @item @emph{Syntax}:
8506 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8507
8508 @item @emph{Arguments}:
8509 @multitable @columnfractions .15 .70
8510 @item @var{TSOURCE} @tab May be of any type.
8511 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8512 as @var{TSOURCE}.
8513 @item @var{MASK}    @tab Shall be of type @code{LOGICAL}.
8514 @end multitable
8515
8516 @item @emph{Return value}:
8517 The result is of the same type and type parameters as @var{TSOURCE}.
8518
8519 @end table
8520
8521
8522
8523 @node MERGE_BITS
8524 @section @code{MERGE_BITS} --- Merge of bits under mask
8525 @fnindex MERGE_BITS
8526 @cindex bits, merge
8527
8528 @table @asis
8529 @item @emph{Description}:
8530 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8531 as determined by the mask.  The i-th bit of the result is equal to the
8532 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8533 the i-th bit of @var{J} otherwise.
8534
8535 @item @emph{Standard}:
8536 Fortran 2008 and later
8537
8538 @item @emph{Class}:
8539 Elemental function
8540
8541 @item @emph{Syntax}:
8542 @code{RESULT = MERGE_BITS(I, J, MASK)}
8543
8544 @item @emph{Arguments}:
8545 @multitable @columnfractions .15 .70
8546 @item @var{I}    @tab Shall be of type @code{INTEGER}.
8547 @item @var{J}    @tab Shall be of type @code{INTEGER} and of the same
8548 kind as @var{I}.
8549 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8550 kind as @var{I}.
8551 @end multitable
8552
8553 @item @emph{Return value}:
8554 The result is of the same type and kind as @var{I}.
8555
8556 @end table
8557
8558
8559
8560 @node MIN
8561 @section @code{MIN} --- Minimum value of an argument list
8562 @fnindex MIN
8563 @fnindex MIN0
8564 @fnindex AMIN0
8565 @fnindex MIN1
8566 @fnindex AMIN1
8567 @fnindex DMIN1
8568 @cindex minimum value
8569
8570 @table @asis
8571 @item @emph{Description}:
8572 Returns the argument with the smallest (most negative) value.
8573
8574 @item @emph{Standard}:
8575 Fortran 77 and later
8576
8577 @item @emph{Class}:
8578 Elemental function
8579
8580 @item @emph{Syntax}:
8581 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8582
8583 @item @emph{Arguments}:
8584 @multitable @columnfractions .15 .70
8585 @item @var{A1}          @tab The type shall be @code{INTEGER} or
8586 @code{REAL}.
8587 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8588 as @var{A1}.  (As a GNU extension, arguments of different kinds are
8589 permitted.)
8590 @end multitable
8591
8592 @item @emph{Return value}:
8593 The return value corresponds to the maximum value among the arguments,
8594 and has the same type and kind as the first argument.
8595
8596 @item @emph{Specific names}:
8597 @multitable @columnfractions .20 .20 .20 .25
8598 @item Name              @tab Argument             @tab Return type        @tab Standard
8599 @item @code{MIN0(A1)}   @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8600 @item @code{AMIN0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{REAL(4)}     @tab Fortran 77 and later
8601 @item @code{MIN1(A1)}   @tab @code{REAL A1}       @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8602 @item @code{AMIN1(A1)}  @tab @code{REAL(4) A1}    @tab @code{REAL(4)}     @tab Fortran 77 and later
8603 @item @code{DMIN1(A1)}  @tab @code{REAL(8) A1}    @tab @code{REAL(8)}     @tab Fortran 77 and later
8604 @end multitable
8605
8606 @item @emph{See also}:
8607 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8608 @end table
8609
8610
8611
8612 @node MINEXPONENT
8613 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8614 @fnindex MINEXPONENT
8615 @cindex model representation, minimum exponent
8616
8617 @table @asis
8618 @item @emph{Description}:
8619 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8620 type of @code{X}.
8621
8622 @item @emph{Standard}:
8623 Fortran 95 and later
8624
8625 @item @emph{Class}:
8626 Inquiry function
8627
8628 @item @emph{Syntax}:
8629 @code{RESULT = MINEXPONENT(X)}
8630
8631 @item @emph{Arguments}:
8632 @multitable @columnfractions .15 .70
8633 @item @var{X} @tab Shall be of type @code{REAL}.
8634 @end multitable
8635
8636 @item @emph{Return value}:
8637 The return value is of type @code{INTEGER} and of the default integer
8638 kind.
8639
8640 @item @emph{Example}:
8641 See @code{MAXEXPONENT} for an example.
8642 @end table
8643
8644
8645
8646 @node MINLOC
8647 @section @code{MINLOC} --- Location of the minimum value within an array
8648 @fnindex MINLOC
8649 @cindex array, location of minimum element
8650
8651 @table @asis
8652 @item @emph{Description}:
8653 Determines the location of the element in the array with the minimum
8654 value, or, if the @var{DIM} argument is supplied, determines the
8655 locations of the minimum element along each row of the array in the
8656 @var{DIM} direction.  If @var{MASK} is present, only the elements for
8657 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8658 element in the array has the minimum value, the location returned is
8659 that of the first such element in array element order.  If the array has
8660 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8661 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8662 and all of the elements of @var{MASK} along a given row are zero, the
8663 result value for that row is zero.
8664
8665 @item @emph{Standard}:
8666 Fortran 95 and later
8667
8668 @item @emph{Class}:
8669 Transformational function
8670
8671 @item @emph{Syntax}:
8672 @multitable @columnfractions .80
8673 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8674 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8675 @end multitable
8676
8677 @item @emph{Arguments}:
8678 @multitable @columnfractions .15 .70
8679 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8680 @code{REAL}.
8681 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8682 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8683 inclusive.  It may not be an optional dummy argument.
8684 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8685 and conformable with @var{ARRAY}.
8686 @end multitable
8687
8688 @item @emph{Return value}:
8689 If @var{DIM} is absent, the result is a rank-one array with a length
8690 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8691 is an array with a rank one less than the rank of @var{ARRAY}, and a
8692 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8693 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8694 of one, the result is a scalar.  In all cases, the result is of default
8695 @code{INTEGER} type.
8696
8697 @item @emph{See also}:
8698 @ref{MIN}, @ref{MINVAL}
8699
8700 @end table
8701
8702
8703
8704 @node MINVAL
8705 @section @code{MINVAL} --- Minimum value of an array
8706 @fnindex MINVAL
8707 @cindex array, minimum value
8708 @cindex minimum value
8709
8710 @table @asis
8711 @item @emph{Description}:
8712 Determines the minimum value of the elements in an array value, or, if
8713 the @var{DIM} argument is supplied, determines the minimum value along
8714 each row of the array in the @var{DIM} direction.  If @var{MASK} is
8715 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8716 considered.  If the array has zero size, or all of the elements of
8717 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8718 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8719 @var{ARRAY} is of character type.
8720
8721 @item @emph{Standard}:
8722 Fortran 95 and later
8723
8724 @item @emph{Class}:
8725 Transformational function
8726
8727 @item @emph{Syntax}:
8728 @multitable @columnfractions .80
8729 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8730 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8731 @end multitable
8732
8733 @item @emph{Arguments}:
8734 @multitable @columnfractions .15 .70
8735 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8736 @code{REAL}.
8737 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8738 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8739 inclusive.  It may not be an optional dummy argument.
8740 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8741 and conformable with @var{ARRAY}.
8742 @end multitable
8743
8744 @item @emph{Return value}:
8745 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8746 is a scalar.  If @var{DIM} is present, the result is an array with a
8747 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8748 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8749 cases, the result is of the same type and kind as @var{ARRAY}.
8750
8751 @item @emph{See also}:
8752 @ref{MIN}, @ref{MINLOC}
8753
8754 @end table
8755
8756
8757
8758 @node MOD
8759 @section @code{MOD} --- Remainder function
8760 @fnindex MOD
8761 @fnindex AMOD
8762 @fnindex DMOD
8763 @cindex remainder
8764 @cindex division, remainder
8765
8766 @table @asis
8767 @item @emph{Description}:
8768 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8769 calculated as @code{A - (INT(A/P) * P)}.
8770
8771 @item @emph{Standard}:
8772 Fortran 77 and later
8773
8774 @item @emph{Class}:
8775 Elemental function
8776
8777 @item @emph{Syntax}:
8778 @code{RESULT = MOD(A, P)}
8779
8780 @item @emph{Arguments}:
8781 @multitable @columnfractions .15 .70
8782 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8783 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8784 equal to zero
8785 @end multitable
8786
8787 @item @emph{Return value}:
8788 The kind of the return value is the result of cross-promoting
8789 the kinds of the arguments.
8790
8791 @item @emph{Example}:
8792 @smallexample
8793 program test_mod
8794   print *, mod(17,3)
8795   print *, mod(17.5,5.5)
8796   print *, mod(17.5d0,5.5)
8797   print *, mod(17.5,5.5d0)
8798
8799   print *, mod(-17,3)
8800   print *, mod(-17.5,5.5)
8801   print *, mod(-17.5d0,5.5)
8802   print *, mod(-17.5,5.5d0)
8803
8804   print *, mod(17,-3)
8805   print *, mod(17.5,-5.5)
8806   print *, mod(17.5d0,-5.5)
8807   print *, mod(17.5,-5.5d0)
8808 end program test_mod
8809 @end smallexample
8810
8811 @item @emph{Specific names}:
8812 @multitable @columnfractions .20 .20 .20 .25
8813 @item Name             @tab Arguments          @tab Return type    @tab Standard
8814 @item @code{MOD(A,P)}  @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8815 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8816 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8817 @end multitable
8818 @end table
8819
8820
8821
8822 @node MODULO
8823 @section @code{MODULO} --- Modulo function
8824 @fnindex MODULO
8825 @cindex modulo
8826 @cindex division, modulo
8827
8828 @table @asis
8829 @item @emph{Description}:
8830 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8831
8832 @item @emph{Standard}:
8833 Fortran 95 and later
8834
8835 @item @emph{Class}:
8836 Elemental function
8837
8838 @item @emph{Syntax}:
8839 @code{RESULT = MODULO(A, P)}
8840
8841 @item @emph{Arguments}:
8842 @multitable @columnfractions .15 .70
8843 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8844 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8845 @end multitable
8846
8847 @item @emph{Return value}:
8848 The type and kind of the result are those of the arguments.
8849 @table @asis
8850 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8851 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8852 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8853 (exclusive).
8854 @item If @var{A} and @var{P} are of type @code{REAL}:
8855 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8856 @end table
8857 In all cases, if @var{P} is zero the result is processor-dependent.
8858
8859 @item @emph{Example}:
8860 @smallexample
8861 program test_modulo
8862   print *, modulo(17,3)
8863   print *, modulo(17.5,5.5)
8864
8865   print *, modulo(-17,3)
8866   print *, modulo(-17.5,5.5)
8867
8868   print *, modulo(17,-3)
8869   print *, modulo(17.5,-5.5)
8870 end program
8871 @end smallexample
8872
8873 @end table
8874
8875
8876
8877 @node MOVE_ALLOC
8878 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8879 @fnindex MOVE_ALLOC
8880 @cindex moving allocation
8881 @cindex allocation, moving
8882
8883 @table @asis
8884 @item @emph{Description}:
8885 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8886 @var{TO}.  @var{FROM} will become deallocated in the process.
8887
8888 @item @emph{Standard}:
8889 Fortran 2003 and later
8890
8891 @item @emph{Class}:
8892 Subroutine
8893
8894 @item @emph{Syntax}:
8895 @code{CALL MOVE_ALLOC(FROM, TO)}
8896
8897 @item @emph{Arguments}:
8898 @multitable @columnfractions .15 .70
8899 @item @var{FROM}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8900 of any type and kind.
8901 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8902 of the same type, kind and rank as @var{FROM}.
8903 @end multitable
8904
8905 @item @emph{Return value}:
8906 None
8907
8908 @item @emph{Example}:
8909 @smallexample
8910 program test_move_alloc
8911     integer, allocatable :: a(:), b(:)
8912
8913     allocate(a(3))
8914     a = [ 1, 2, 3 ]
8915     call move_alloc(a, b)
8916     print *, allocated(a), allocated(b)
8917     print *, b
8918 end program test_move_alloc
8919 @end smallexample
8920 @end table
8921
8922
8923
8924 @node MVBITS
8925 @section @code{MVBITS} --- Move bits from one integer to another
8926 @fnindex MVBITS
8927 @cindex bits, move
8928
8929 @table @asis
8930 @item @emph{Description}:
8931 Moves @var{LEN} bits from positions @var{FROMPOS} through
8932 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8933 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8934 affected by the movement of bits is unchanged. The values of
8935 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8936 @code{BIT_SIZE(FROM)}.
8937
8938 @item @emph{Standard}:
8939 Fortran 95 and later
8940
8941 @item @emph{Class}:
8942 Elemental subroutine
8943
8944 @item @emph{Syntax}:
8945 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8946
8947 @item @emph{Arguments}:
8948 @multitable @columnfractions .15 .70
8949 @item @var{FROM}    @tab The type shall be @code{INTEGER}.
8950 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8951 @item @var{LEN}     @tab The type shall be @code{INTEGER}.
8952 @item @var{TO}      @tab The type shall be @code{INTEGER}, of the
8953 same kind as @var{FROM}.
8954 @item @var{TOPOS}   @tab The type shall be @code{INTEGER}.
8955 @end multitable
8956
8957 @item @emph{See also}:
8958 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8959 @end table
8960
8961
8962
8963 @node NEAREST
8964 @section @code{NEAREST} --- Nearest representable number
8965 @fnindex NEAREST
8966 @cindex real number, nearest different
8967 @cindex floating point, nearest different
8968
8969 @table @asis
8970 @item @emph{Description}:
8971 @code{NEAREST(X, S)} returns the processor-representable number nearest
8972 to @code{X} in the direction indicated by the sign of @code{S}.
8973
8974 @item @emph{Standard}:
8975 Fortran 95 and later
8976
8977 @item @emph{Class}:
8978 Elemental function
8979
8980 @item @emph{Syntax}:
8981 @code{RESULT = NEAREST(X, S)}
8982
8983 @item @emph{Arguments}:
8984 @multitable @columnfractions .15 .70
8985 @item @var{X} @tab Shall be of type @code{REAL}.
8986 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8987 not equal to zero.
8988 @end multitable
8989
8990 @item @emph{Return value}:
8991 The return value is of the same type as @code{X}. If @code{S} is
8992 positive, @code{NEAREST} returns the processor-representable number
8993 greater than @code{X} and nearest to it. If @code{S} is negative,
8994 @code{NEAREST} returns the processor-representable number smaller than
8995 @code{X} and nearest to it.
8996
8997 @item @emph{Example}:
8998 @smallexample
8999 program test_nearest
9000   real :: x, y
9001   x = nearest(42.0, 1.0)
9002   y = nearest(42.0, -1.0)
9003   write (*,"(3(G20.15))") x, y, x - y
9004 end program test_nearest
9005 @end smallexample
9006 @end table
9007
9008
9009
9010 @node NEW_LINE
9011 @section @code{NEW_LINE} --- New line character
9012 @fnindex NEW_LINE
9013 @cindex newline
9014 @cindex output, newline
9015
9016 @table @asis
9017 @item @emph{Description}:
9018 @code{NEW_LINE(C)} returns the new-line character.
9019
9020 @item @emph{Standard}:
9021 Fortran 2003 and later
9022
9023 @item @emph{Class}:
9024 Inquiry function
9025
9026 @item @emph{Syntax}:
9027 @code{RESULT = NEW_LINE(C)}
9028
9029 @item @emph{Arguments}:
9030 @multitable @columnfractions .15 .70
9031 @item @var{C}    @tab The argument shall be a scalar or array of the
9032 type @code{CHARACTER}.
9033 @end multitable
9034
9035 @item @emph{Return value}:
9036 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9037 the same kind as parameter @var{C}.
9038
9039 @item @emph{Example}:
9040 @smallexample
9041 program newline
9042   implicit none
9043   write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9044 end program newline
9045 @end smallexample
9046 @end table
9047
9048
9049
9050 @node NINT
9051 @section @code{NINT} --- Nearest whole number
9052 @fnindex NINT
9053 @fnindex IDNINT
9054 @cindex rounding, nearest whole number
9055
9056 @table @asis
9057 @item @emph{Description}:
9058 @code{NINT(A)} rounds its argument to the nearest whole number.
9059
9060 @item @emph{Standard}:
9061 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9062
9063 @item @emph{Class}:
9064 Elemental function
9065
9066 @item @emph{Syntax}:
9067 @code{RESULT = NINT(A [, KIND])}
9068
9069 @item @emph{Arguments}:
9070 @multitable @columnfractions .15 .70
9071 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
9072 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9073 expression indicating the kind parameter of the result.
9074 @end multitable
9075
9076 @item @emph{Return value}:
9077 Returns @var{A} with the fractional portion of its magnitude eliminated by
9078 rounding to the nearest whole number and with its sign preserved,
9079 converted to an @code{INTEGER} of the default kind.
9080
9081 @item @emph{Example}:
9082 @smallexample
9083 program test_nint
9084   real(4) x4
9085   real(8) x8
9086   x4 = 1.234E0_4
9087   x8 = 4.321_8
9088   print *, nint(x4), idnint(x8)
9089 end program test_nint
9090 @end smallexample
9091
9092 @item @emph{Specific names}:
9093 @multitable @columnfractions .20 .20 .20 .25
9094 @item Name             @tab Argument           @tab Return Type     @tab Standard
9095 @item @code{NINT(A)}   @tab @code{REAL(4) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9096 @item @code{IDNINT(A)} @tab @code{REAL(8) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9097 @end multitable
9098
9099 @item @emph{See also}:
9100 @ref{CEILING}, @ref{FLOOR}
9101
9102 @end table
9103
9104
9105
9106 @node NORM2
9107 @section @code{NORM2} --- Euclidean vector norms
9108 @fnindex NORM2
9109 @cindex Euclidean vector norm
9110 @cindex L2 vector norm
9111 @cindex norm, Euclidean
9112
9113 @table @asis
9114 @item @emph{Description}:
9115 Calculates the Euclidean vector norm (@math{L_2} norm) of
9116 of @var{ARRAY} along dimension @var{DIM}.
9117
9118 @item @emph{Standard}:
9119 Fortran 2008 and later
9120
9121 @item @emph{Class}:
9122 Transformational function
9123
9124 @item @emph{Syntax}:
9125 @multitable @columnfractions .80
9126 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9127 @end multitable
9128
9129 @item @emph{Arguments}:
9130 @multitable @columnfractions .15 .70
9131 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9132 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9133 @code{INTEGER} with a value in the range from 1 to n, where n
9134 equals the rank of @var{ARRAY}.
9135 @end multitable
9136
9137 @item @emph{Return value}:
9138 The result is of the same type as @var{ARRAY}.
9139
9140 If @var{DIM} is absent, a scalar with the square root of the sum of all
9141 elements in @var{ARRAY} squared  is returned. Otherwise, an array of
9142 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9143 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9144 is returned.
9145
9146 @item @emph{Example}:
9147 @smallexample
9148 PROGRAM test_sum
9149   REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9150   print *, NORM2(x)  ! = sqrt(55.) ~ 7.416
9151 END PROGRAM
9152 @end smallexample
9153 @end table
9154
9155
9156
9157 @node NOT
9158 @section @code{NOT} --- Logical negation
9159 @fnindex NOT
9160 @cindex bits, negate
9161 @cindex bitwise logical not
9162 @cindex logical not, bitwise
9163
9164 @table @asis
9165 @item @emph{Description}:
9166 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9167
9168 @item @emph{Standard}:
9169 Fortran 95 and later
9170
9171 @item @emph{Class}:
9172 Elemental function
9173
9174 @item @emph{Syntax}:
9175 @code{RESULT = NOT(I)}
9176
9177 @item @emph{Arguments}:
9178 @multitable @columnfractions .15 .70
9179 @item @var{I} @tab The type shall be @code{INTEGER}.
9180 @end multitable
9181
9182 @item @emph{Return value}:
9183 The return type is @code{INTEGER}, of the same kind as the
9184 argument.
9185
9186 @item @emph{See also}:
9187 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9188
9189 @end table
9190
9191
9192
9193 @node NULL
9194 @section @code{NULL} --- Function that returns an disassociated pointer
9195 @fnindex NULL
9196 @cindex pointer, status
9197 @cindex pointer, disassociated
9198
9199 @table @asis
9200 @item @emph{Description}:
9201 Returns a disassociated pointer.
9202
9203 If @var{MOLD} is present, a disassociated pointer of the same type is
9204 returned, otherwise the type is determined by context.
9205
9206 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9207 includes cases where it is required.
9208
9209 @item @emph{Standard}:
9210 Fortran 95 and later
9211
9212 @item @emph{Class}:
9213 Transformational function
9214
9215 @item @emph{Syntax}:
9216 @code{PTR => NULL([MOLD])}
9217
9218 @item @emph{Arguments}:
9219 @multitable @columnfractions .15 .70
9220 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9221 status and of any type.
9222 @end multitable
9223
9224 @item @emph{Return value}:
9225 A disassociated pointer.
9226
9227 @item @emph{Example}:
9228 @smallexample
9229 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9230 @end smallexample
9231
9232 @item @emph{See also}:
9233 @ref{ASSOCIATED}
9234 @end table
9235
9236
9237
9238 @node NUM_IMAGES
9239 @section @code{NUM_IMAGES} --- Function that returns the number of images
9240 @fnindex NUM_IMAGES
9241 @cindex coarray, @code{NUM_IMAGES}
9242 @cindex images, number of
9243
9244 @table @asis
9245 @item @emph{Description}:
9246 Returns the number of images.
9247
9248 @item @emph{Standard}:
9249 Fortran 2008 and later
9250
9251 @item @emph{Class}:
9252 Transformational function
9253
9254 @item @emph{Syntax}:
9255 @code{RESULT = NUM_IMAGES()}
9256
9257 @item @emph{Arguments}: None.
9258
9259 @item @emph{Return value}:
9260 Scalar default-kind integer.
9261
9262 @item @emph{Example}:
9263 @smallexample
9264 INTEGER :: value[*]
9265 INTEGER :: i
9266 value = THIS_IMAGE()
9267 SYNC ALL
9268 IF (THIS_IMAGE() == 1) THEN
9269   DO i = 1, NUM_IMAGES()
9270     WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9271   END DO
9272 END IF
9273 @end smallexample
9274
9275 @item @emph{See also}:
9276 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9277 @end table
9278
9279
9280
9281 @node OR
9282 @section @code{OR} --- Bitwise logical OR
9283 @fnindex OR
9284 @cindex bitwise logical or
9285 @cindex logical or, bitwise
9286
9287 @table @asis
9288 @item @emph{Description}:
9289 Bitwise logical @code{OR}.
9290
9291 This intrinsic routine is provided for backwards compatibility with
9292 GNU Fortran 77.  For integer arguments, programmers should consider
9293 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9294
9295 @item @emph{Standard}:
9296 GNU extension
9297
9298 @item @emph{Class}:
9299 Function
9300
9301 @item @emph{Syntax}:
9302 @code{RESULT = OR(I, J)}
9303
9304 @item @emph{Arguments}:
9305 @multitable @columnfractions .15 .70
9306 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9307 type or a scalar @code{LOGICAL} type.
9308 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9309 @end multitable
9310
9311 @item @emph{Return value}:
9312 The return type is either a scalar @code{INTEGER} or a scalar
9313 @code{LOGICAL}.  If the kind type parameters differ, then the
9314 smaller kind type is implicitly converted to larger kind, and the
9315 return has the larger kind.
9316
9317 @item @emph{Example}:
9318 @smallexample
9319 PROGRAM test_or
9320   LOGICAL :: T = .TRUE., F = .FALSE.
9321   INTEGER :: a, b
9322   DATA a / Z'F' /, b / Z'3' /
9323
9324   WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9325   WRITE (*,*) OR(a, b)
9326 END PROGRAM
9327 @end smallexample
9328
9329 @item @emph{See also}:
9330 Fortran 95 elemental function: @ref{IOR}
9331 @end table
9332
9333
9334
9335 @node PACK
9336 @section @code{PACK} --- Pack an array into an array of rank one
9337 @fnindex PACK
9338 @cindex array, packing
9339 @cindex array, reduce dimension
9340 @cindex array, gather elements
9341
9342 @table @asis
9343 @item @emph{Description}:
9344 Stores the elements of @var{ARRAY} in an array of rank one.
9345
9346 The beginning of the resulting array is made up of elements whose @var{MASK}
9347 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9348 @var{VECTOR}.
9349
9350 @item @emph{Standard}:
9351 Fortran 95 and later
9352
9353 @item @emph{Class}:
9354 Transformational function
9355
9356 @item @emph{Syntax}:
9357 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9358
9359 @item @emph{Arguments}:
9360 @multitable @columnfractions .15 .70
9361 @item @var{ARRAY}  @tab Shall be an array of any type.
9362 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
9363 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9364 scalar.
9365 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9366 as @var{ARRAY} and of rank one. If present, the number of elements in
9367 @var{VECTOR} shall be equal to or greater than the number of true elements
9368 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9369 @var{VECTOR} shall be equal to or greater than the number of elements in
9370 @var{ARRAY}.
9371 @end multitable
9372
9373 @item @emph{Return value}:
9374 The result is an array of rank one and the same type as that of @var{ARRAY}.
9375 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9376 number of @code{TRUE} values in @var{MASK} otherwise.
9377
9378 @item @emph{Example}:
9379 Gathering nonzero elements from an array:
9380 @smallexample
9381 PROGRAM test_pack_1
9382   INTEGER :: m(6)
9383   m = (/ 1, 0, 0, 0, 5, 0 /)
9384   WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
9385 END PROGRAM
9386 @end smallexample
9387
9388 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9389 @smallexample
9390 PROGRAM test_pack_2
9391   INTEGER :: m(4)
9392   m = (/ 1, 0, 0, 2 /)
9393   WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
9394 END PROGRAM
9395 @end smallexample
9396
9397 @item @emph{See also}:
9398 @ref{UNPACK}
9399 @end table
9400
9401
9402
9403 @node PARITY
9404 @section @code{PARITY} --- Reduction with exclusive OR
9405 @fnindex PARITY
9406 @cindex Parity
9407 @cindex Reduction, XOR
9408 @cindex XOR reduction
9409
9410 @table @asis
9411 @item @emph{Description}:
9412 Calculates the parity, i.e. the reduction using @code{.XOR.},
9413 of @var{MASK} along dimension @var{DIM}.
9414
9415 @item @emph{Standard}:
9416 Fortran 2008 and later
9417
9418 @item @emph{Class}:
9419 Transformational function
9420
9421 @item @emph{Syntax}:
9422 @multitable @columnfractions .80
9423 @item @code{RESULT = PARITY(MASK[, DIM])}
9424 @end multitable
9425
9426 @item @emph{Arguments}:
9427 @multitable @columnfractions .15 .70
9428 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9429 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9430 @code{INTEGER} with a value in the range from 1 to n, where n
9431 equals the rank of @var{MASK}.
9432 @end multitable
9433
9434 @item @emph{Return value}:
9435 The result is of the same type as @var{MASK}.
9436
9437 If @var{DIM} is absent, a scalar with the parity of all elements in
9438 @var{MASK} is returned, i.e. true if an odd number of elements is
9439 @code{.true.} and false otherwise.  If @var{DIM} is present, an array
9440 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9441 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9442 dropped is returned.
9443
9444 @item @emph{Example}:
9445 @smallexample
9446 PROGRAM test_sum
9447   LOGICAL :: x(2) = [ .true., .false. ]
9448   print *, PARITY(x) ! prints "T" (true).
9449 END PROGRAM
9450 @end smallexample
9451 @end table
9452
9453
9454
9455 @node PERROR
9456 @section @code{PERROR} --- Print system error message
9457 @fnindex PERROR
9458 @cindex system, error handling
9459
9460 @table @asis
9461 @item @emph{Description}:
9462 Prints (on the C @code{stderr} stream) a newline-terminated error
9463 message corresponding to the last system error. This is prefixed by
9464 @var{STRING}, a colon and a space. See @code{perror(3)}.
9465
9466 @item @emph{Standard}:
9467 GNU extension
9468
9469 @item @emph{Class}:
9470 Subroutine
9471
9472 @item @emph{Syntax}:
9473 @code{CALL PERROR(STRING)}
9474
9475 @item @emph{Arguments}:
9476 @multitable @columnfractions .15 .70
9477 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9478 default kind.
9479 @end multitable
9480
9481 @item @emph{See also}:
9482 @ref{IERRNO}
9483 @end table
9484
9485
9486
9487 @node PRECISION
9488 @section @code{PRECISION} --- Decimal precision of a real kind
9489 @fnindex PRECISION
9490 @cindex model representation, precision
9491
9492 @table @asis
9493 @item @emph{Description}:
9494 @code{PRECISION(X)} returns the decimal precision in the model of the
9495 type of @code{X}.
9496
9497 @item @emph{Standard}:
9498 Fortran 95 and later
9499
9500 @item @emph{Class}:
9501 Inquiry function
9502
9503 @item @emph{Syntax}:
9504 @code{RESULT = PRECISION(X)}
9505
9506 @item @emph{Arguments}:
9507 @multitable @columnfractions .15 .70
9508 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9509 @end multitable
9510
9511 @item @emph{Return value}:
9512 The return value is of type @code{INTEGER} and of the default integer
9513 kind.
9514
9515 @item @emph{See also}:
9516 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9517
9518 @item @emph{Example}:
9519 @smallexample
9520 program prec_and_range
9521   real(kind=4) :: x(2)
9522   complex(kind=8) :: y
9523
9524   print *, precision(x), range(x)
9525   print *, precision(y), range(y)
9526 end program prec_and_range
9527 @end smallexample
9528 @end table
9529
9530
9531
9532 @node POPCNT
9533 @section @code{POPCNT} --- Number of bits set
9534 @fnindex POPCNT
9535 @cindex binary representation
9536 @cindex bits set
9537
9538 @table @asis
9539 @item @emph{Description}:
9540 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9541 representation of @code{I}.
9542
9543 @item @emph{Standard}:
9544 Fortran 2008 and later
9545
9546 @item @emph{Class}:
9547 Elemental function
9548
9549 @item @emph{Syntax}:
9550 @code{RESULT = POPCNT(I)}
9551
9552 @item @emph{Arguments}:
9553 @multitable @columnfractions .15 .70
9554 @item @var{I} @tab Shall be of type @code{INTEGER}.
9555 @end multitable
9556
9557 @item @emph{Return value}:
9558 The return value is of type @code{INTEGER} and of the default integer
9559 kind.
9560
9561 @item @emph{See also}:
9562 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9563
9564 @item @emph{Example}:
9565 @smallexample
9566 program test_population
9567   print *, popcnt(127),       poppar(127)
9568   print *, popcnt(huge(0_4)), poppar(huge(0_4))
9569   print *, popcnt(huge(0_8)), poppar(huge(0_8))
9570 end program test_population
9571 @end smallexample
9572 @end table
9573
9574
9575 @node POPPAR
9576 @section @code{POPPAR} --- Parity of the number of bits set
9577 @fnindex POPPAR
9578 @cindex binary representation
9579 @cindex parity
9580
9581 @table @asis
9582 @item @emph{Description}:
9583 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9584 of the number of bits set ('1' bits) in the binary representation of
9585 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9586 and 1 for an odd number of '1' bits.
9587
9588 @item @emph{Standard}:
9589 Fortran 2008 and later
9590
9591 @item @emph{Class}:
9592 Elemental function
9593
9594 @item @emph{Syntax}:
9595 @code{RESULT = POPPAR(I)}
9596
9597 @item @emph{Arguments}:
9598 @multitable @columnfractions .15 .70
9599 @item @var{I} @tab Shall be of type @code{INTEGER}.
9600 @end multitable
9601
9602 @item @emph{Return value}:
9603 The return value is of type @code{INTEGER} and of the default integer
9604 kind.
9605
9606 @item @emph{See also}:
9607 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9608
9609 @item @emph{Example}:
9610 @smallexample
9611 program test_population
9612   print *, popcnt(127),       poppar(127)
9613   print *, popcnt(huge(0_4)), poppar(huge(0_4))
9614   print *, popcnt(huge(0_8)), poppar(huge(0_8))
9615 end program test_population
9616 @end smallexample
9617 @end table
9618
9619
9620
9621 @node PRESENT
9622 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9623 @fnindex PRESENT
9624
9625 @table @asis
9626 @item @emph{Description}:
9627 Determines whether an optional dummy argument is present.
9628
9629 @item @emph{Standard}:
9630 Fortran 95 and later
9631
9632 @item @emph{Class}:
9633 Inquiry function
9634
9635 @item @emph{Syntax}:
9636 @code{RESULT = PRESENT(A)}
9637
9638 @item @emph{Arguments}:
9639 @multitable @columnfractions .15 .70
9640 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9641 value, or a dummy procedure. It shall be the name of an optional dummy argument
9642 accessible within the current subroutine or function.
9643 @end multitable
9644
9645 @item @emph{Return value}:
9646 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9647 @code{FALSE} otherwise.
9648
9649 @item @emph{Example}:
9650 @smallexample
9651 PROGRAM test_present
9652   WRITE(*,*) f(), f(42)      ! "F T"
9653 CONTAINS
9654   LOGICAL FUNCTION f(x)
9655     INTEGER, INTENT(IN), OPTIONAL :: x
9656     f = PRESENT(x)
9657   END FUNCTION
9658 END PROGRAM
9659 @end smallexample
9660 @end table
9661
9662
9663
9664 @node PRODUCT
9665 @section @code{PRODUCT} --- Product of array elements
9666 @fnindex PRODUCT
9667 @cindex array, product
9668 @cindex array, multiply elements
9669 @cindex array, conditionally multiply elements
9670 @cindex multiply array elements
9671
9672 @table @asis
9673 @item @emph{Description}:
9674 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9675 the corresponding element in @var{MASK} is @code{TRUE}.
9676
9677 @item @emph{Standard}:
9678 Fortran 95 and later
9679
9680 @item @emph{Class}:
9681 Transformational function
9682
9683 @item @emph{Syntax}:
9684 @multitable @columnfractions .80
9685 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9686 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9687 @end multitable
9688
9689 @item @emph{Arguments}:
9690 @multitable @columnfractions .15 .70
9691 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9692 @code{REAL} or @code{COMPLEX}.
9693 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9694 @code{INTEGER} with a value in the range from 1 to n, where n
9695 equals the rank of @var{ARRAY}.
9696 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
9697 and either be a scalar or an array of the same shape as @var{ARRAY}.
9698 @end multitable
9699
9700 @item @emph{Return value}:
9701 The result is of the same type as @var{ARRAY}.
9702
9703 If @var{DIM} is absent, a scalar with the product of all elements in
9704 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9705 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9706 dimension @var{DIM} dropped is returned.
9707
9708
9709 @item @emph{Example}:
9710 @smallexample
9711 PROGRAM test_product
9712   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9713   print *, PRODUCT(x)                    ! all elements, product = 120
9714   print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9715 END PROGRAM
9716 @end smallexample
9717
9718 @item @emph{See also}:
9719 @ref{SUM}
9720 @end table
9721
9722
9723
9724 @node RADIX
9725 @section @code{RADIX} --- Base of a model number
9726 @fnindex RADIX
9727 @cindex model representation, base
9728 @cindex model representation, radix
9729
9730 @table @asis
9731 @item @emph{Description}:
9732 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9733
9734 @item @emph{Standard}:
9735 Fortran 95 and later
9736
9737 @item @emph{Class}:
9738 Inquiry function
9739
9740 @item @emph{Syntax}:
9741 @code{RESULT = RADIX(X)}
9742
9743 @item @emph{Arguments}:
9744 @multitable @columnfractions .15 .70
9745 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9746 @end multitable
9747
9748 @item @emph{Return value}:
9749 The return value is a scalar of type @code{INTEGER} and of the default
9750 integer kind.
9751
9752 @item @emph{See also}:
9753 @ref{SELECTED_REAL_KIND}
9754
9755 @item @emph{Example}:
9756 @smallexample
9757 program test_radix
9758   print *, "The radix for the default integer kind is", radix(0)
9759   print *, "The radix for the default real kind is", radix(0.0)
9760 end program test_radix
9761 @end smallexample
9762
9763 @end table
9764
9765
9766
9767 @node RAN
9768 @section @code{RAN} --- Real pseudo-random number
9769 @fnindex RAN
9770 @cindex random number generation
9771
9772 @table @asis
9773 @item @emph{Description}:
9774 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9775 provided as an alias for @code{RAND}.  See @ref{RAND} for complete
9776 documentation.
9777
9778 @item @emph{Standard}:
9779 GNU extension
9780
9781 @item @emph{Class}:
9782 Function
9783
9784 @item @emph{See also}:
9785 @ref{RAND}, @ref{RANDOM_NUMBER}
9786 @end table
9787
9788
9789
9790 @node RAND
9791 @section @code{RAND} --- Real pseudo-random number
9792 @fnindex RAND
9793 @cindex random number generation
9794
9795 @table @asis
9796 @item @emph{Description}:
9797 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
9798 distribution between 0 and 1. If @var{FLAG} is 0, the next number
9799 in the current sequence is returned; if @var{FLAG} is 1, the generator
9800 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
9801 it is used as a new seed with @code{SRAND}.
9802
9803 This intrinsic routine is provided for backwards compatibility with
9804 GNU Fortran 77. It implements a simple modulo generator as provided
9805 by @command{g77}. For new code, one should consider the use of
9806 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
9807
9808 @item @emph{Standard}:
9809 GNU extension
9810
9811 @item @emph{Class}:
9812 Function
9813
9814 @item @emph{Syntax}:
9815 @code{RESULT = RAND(I)}
9816
9817 @item @emph{Arguments}:
9818 @multitable @columnfractions .15 .70
9819 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
9820 @end multitable
9821
9822 @item @emph{Return value}:
9823 The return value is of @code{REAL} type and the default kind.
9824
9825 @item @emph{Example}:
9826 @smallexample
9827 program test_rand
9828   integer,parameter :: seed = 86456
9829
9830   call srand(seed)
9831   print *, rand(), rand(), rand(), rand()
9832   print *, rand(seed), rand(), rand(), rand()
9833 end program test_rand
9834 @end smallexample
9835
9836 @item @emph{See also}:
9837 @ref{SRAND}, @ref{RANDOM_NUMBER}
9838
9839 @end table
9840
9841
9842
9843 @node RANDOM_NUMBER
9844 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9845 @fnindex RANDOM_NUMBER
9846 @cindex random number generation
9847
9848 @table @asis
9849 @item @emph{Description}:
9850 Returns a single pseudorandom number or an array of pseudorandom numbers
9851 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9852
9853 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9854 Stupid) random number generator (RNG). This RNG combines:
9855 @enumerate
9856 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9857 with a period of @math{2^{32}},
9858 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9859 @item  Two 16-bit multiply-with-carry generators with a period of
9860 @math{597273182964842497 > 2^{59}}.
9861 @end enumerate
9862 The overall period exceeds @math{2^{123}}.
9863
9864 Please note, this RNG is thread safe if used within OpenMP directives,
9865 i.e., its state will be consistent while called from multiple threads.
9866 However, the KISS generator does not create random numbers in parallel
9867 from multiple sources, but in sequence from a single source. If an
9868 OpenMP-enabled application heavily relies on random numbers, one should
9869 consider employing a dedicated parallel random number generator instead.
9870
9871 @item @emph{Standard}:
9872 Fortran 95 and later
9873
9874 @item @emph{Class}:
9875 Subroutine
9876
9877 @item @emph{Syntax}:
9878 @code{RANDOM_NUMBER(HARVEST)}
9879
9880 @item @emph{Arguments}:
9881 @multitable @columnfractions .15 .70
9882 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9883 @end multitable
9884
9885 @item @emph{Example}:
9886 @smallexample
9887 program test_random_number
9888   REAL :: r(5,5)
9889   CALL init_random_seed()         ! see example of RANDOM_SEED
9890   CALL RANDOM_NUMBER(r)
9891 end program
9892 @end smallexample
9893
9894 @item @emph{See also}:
9895 @ref{RANDOM_SEED}
9896 @end table
9897
9898
9899
9900 @node RANDOM_SEED
9901 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
9902 @fnindex RANDOM_SEED
9903 @cindex random number generation, seeding
9904 @cindex seeding a random number generator
9905
9906 @table @asis
9907 @item @emph{Description}:
9908 Restarts or queries the state of the pseudorandom number generator used by
9909 @code{RANDOM_NUMBER}.
9910
9911 If @code{RANDOM_SEED} is called without arguments, it is initialized to
9912 a default state. The example below shows how to initialize the random
9913 seed based on the system's time.
9914
9915 @item @emph{Standard}:
9916 Fortran 95 and later
9917
9918 @item @emph{Class}:
9919 Subroutine
9920
9921 @item @emph{Syntax}:
9922 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
9923
9924 @item @emph{Arguments}:
9925 @multitable @columnfractions .15 .70
9926 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
9927 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
9928 of the arrays used with the @var{PUT} and @var{GET} arguments.
9929 @item @var{PUT}  @tab (Optional) Shall be an array of type default
9930 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
9931 the array must be larger than or equal to the number returned by the
9932 @var{SIZE} argument.
9933 @item @var{GET}  @tab (Optional) Shall be an array of type default
9934 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
9935 of the array must be larger than or equal to the number returned by
9936 the @var{SIZE} argument.
9937 @end multitable
9938
9939 @item @emph{Example}:
9940 @smallexample
9941 SUBROUTINE init_random_seed()
9942   INTEGER :: i, n, clock
9943   INTEGER, DIMENSION(:), ALLOCATABLE :: seed
9944
9945   CALL RANDOM_SEED(size = n)
9946   ALLOCATE(seed(n))
9947
9948   CALL SYSTEM_CLOCK(COUNT=clock)
9949
9950   seed = clock + 37 * (/ (i - 1, i = 1, n) /)
9951   CALL RANDOM_SEED(PUT = seed)
9952
9953   DEALLOCATE(seed)
9954 END SUBROUTINE
9955 @end smallexample
9956
9957 @item @emph{See also}:
9958 @ref{RANDOM_NUMBER}
9959 @end table
9960
9961
9962
9963 @node RANGE
9964 @section @code{RANGE} --- Decimal exponent range
9965 @fnindex RANGE
9966 @cindex model representation, range
9967
9968 @table @asis
9969 @item @emph{Description}:
9970 @code{RANGE(X)} returns the decimal exponent range in the model of the
9971 type of @code{X}.
9972
9973 @item @emph{Standard}:
9974 Fortran 95 and later
9975
9976 @item @emph{Class}:
9977 Inquiry function
9978
9979 @item @emph{Syntax}:
9980 @code{RESULT = RANGE(X)}
9981
9982 @item @emph{Arguments}:
9983 @multitable @columnfractions .15 .70
9984 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
9985 or @code{COMPLEX}.
9986 @end multitable
9987
9988 @item @emph{Return value}:
9989 The return value is of type @code{INTEGER} and of the default integer
9990 kind.
9991
9992 @item @emph{See also}:
9993 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
9994
9995 @item @emph{Example}:
9996 See @code{PRECISION} for an example.
9997 @end table
9998
9999
10000
10001 @node REAL
10002 @section @code{REAL} --- Convert to real type
10003 @fnindex REAL
10004 @fnindex REALPART
10005 @fnindex FLOAT
10006 @fnindex DFLOAT
10007 @fnindex SNGL
10008 @cindex conversion, to real
10009 @cindex complex numbers, real part
10010
10011 @table @asis
10012 @item @emph{Description}:
10013 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type.  The
10014 @code{REALPART} function is provided for compatibility with @command{g77},
10015 and its use is strongly discouraged.
10016
10017 @item @emph{Standard}:
10018 Fortran 77 and later
10019
10020 @item @emph{Class}:
10021 Elemental function
10022
10023 @item @emph{Syntax}:
10024 @multitable @columnfractions .80
10025 @item @code{RESULT = REAL(A [, KIND])}
10026 @item @code{RESULT = REALPART(Z)}
10027 @end multitable
10028
10029 @item @emph{Arguments}:
10030 @multitable @columnfractions .15 .70
10031 @item @var{A}    @tab Shall be @code{INTEGER}, @code{REAL}, or
10032 @code{COMPLEX}.
10033 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10034 expression indicating the kind parameter of the result.
10035 @end multitable
10036
10037 @item @emph{Return value}:
10038 These functions return a @code{REAL} variable or array under
10039 the following rules:
10040
10041 @table @asis
10042 @item (A)
10043 @code{REAL(A)} is converted to a default real type if @var{A} is an
10044 integer or real variable.
10045 @item (B)
10046 @code{REAL(A)} is converted to a real type with the kind type parameter
10047 of @var{A} if @var{A} is a complex variable.
10048 @item (C)
10049 @code{REAL(A, KIND)} is converted to a real type with kind type
10050 parameter @var{KIND} if @var{A} is a complex, integer, or real
10051 variable.
10052 @end table
10053
10054 @item @emph{Example}:
10055 @smallexample
10056 program test_real
10057   complex :: x = (1.0, 2.0)
10058   print *, real(x), real(x,8), realpart(x)
10059 end program test_real
10060 @end smallexample
10061
10062 @item @emph{Specific names}:
10063 @multitable @columnfractions .20 .20 .20 .25
10064 @item Name             @tab Argument           @tab Return type     @tab Standard
10065 @item @code{FLOAT(A)}  @tab @code{INTEGER(4)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10066 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)}  @tab @code{REAL(8)}  @tab GNU extension
10067 @item @code{SNGL(A)}   @tab @code{INTEGER(8)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10068 @end multitable
10069
10070
10071 @item @emph{See also}:
10072 @ref{DBLE}
10073
10074 @end table
10075
10076
10077
10078 @node RENAME
10079 @section @code{RENAME} --- Rename a file
10080 @fnindex RENAME
10081 @cindex file system, rename file
10082
10083 @table @asis
10084 @item @emph{Description}:
10085 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10086 character (@code{CHAR(0)}) can be used to mark the end of the names in
10087 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10088 names are ignored.  If the @var{STATUS} argument is supplied, it
10089 contains 0 on success or a nonzero error code upon return; see
10090 @code{rename(2)}.
10091
10092 This intrinsic is provided in both subroutine and function forms;
10093 however, only one form can be used in any given program unit.
10094
10095 @item @emph{Standard}:
10096 GNU extension
10097
10098 @item @emph{Class}:
10099 Subroutine, function
10100
10101 @item @emph{Syntax}:
10102 @multitable @columnfractions .80
10103 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10104 @item @code{STATUS = RENAME(PATH1, PATH2)}
10105 @end multitable
10106
10107 @item @emph{Arguments}:
10108 @multitable @columnfractions .15 .70
10109 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10110 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10111 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10112 @end multitable
10113
10114 @item @emph{See also}:
10115 @ref{LINK}
10116
10117 @end table
10118
10119
10120
10121 @node REPEAT
10122 @section @code{REPEAT} --- Repeated string concatenation
10123 @fnindex REPEAT
10124 @cindex string, repeat
10125 @cindex string, concatenate
10126
10127 @table @asis
10128 @item @emph{Description}:
10129 Concatenates @var{NCOPIES} copies of a string.
10130
10131 @item @emph{Standard}:
10132 Fortran 95 and later
10133
10134 @item @emph{Class}:
10135 Transformational function
10136
10137 @item @emph{Syntax}:
10138 @code{RESULT = REPEAT(STRING, NCOPIES)}
10139
10140 @item @emph{Arguments}:
10141 @multitable @columnfractions .15 .70
10142 @item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER}.
10143 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10144 @end multitable
10145
10146 @item @emph{Return value}:
10147 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10148 of @var{STRING}.
10149
10150 @item @emph{Example}:
10151 @smallexample
10152 program test_repeat
10153   write(*,*) repeat("x", 5)   ! "xxxxx"
10154 end program
10155 @end smallexample
10156 @end table
10157
10158
10159
10160 @node RESHAPE
10161 @section @code{RESHAPE} --- Function to reshape an array
10162 @fnindex RESHAPE
10163 @cindex array, change dimensions
10164 @cindex array, transmogrify
10165
10166 @table @asis
10167 @item @emph{Description}:
10168 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10169 the new array may be padded with elements from @var{PAD} or permuted
10170 as defined by @var{ORDER}.
10171
10172 @item @emph{Standard}:
10173 Fortran 95 and later
10174
10175 @item @emph{Class}:
10176 Transformational function
10177
10178 @item @emph{Syntax}:
10179 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10180
10181 @item @emph{Arguments}:
10182 @multitable @columnfractions .15 .70
10183 @item @var{SOURCE} @tab Shall be an array of any type.
10184 @item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
10185 array of rank one. Its values must be positive or zero.
10186 @item @var{PAD}    @tab (Optional) shall be an array of the same
10187 type as @var{SOURCE}.
10188 @item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
10189 and an array of the same shape as @var{SHAPE}. Its values shall
10190 be a permutation of the numbers from 1 to n, where n is the size of
10191 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10192 be assumed.
10193 @end multitable
10194
10195 @item @emph{Return value}:
10196 The result is an array of shape @var{SHAPE} with the same type as
10197 @var{SOURCE}.
10198
10199 @item @emph{Example}:
10200 @smallexample
10201 PROGRAM test_reshape
10202   INTEGER, DIMENSION(4) :: x
10203   WRITE(*,*) SHAPE(x)                       ! prints "4"
10204   WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
10205 END PROGRAM
10206 @end smallexample
10207
10208 @item @emph{See also}:
10209 @ref{SHAPE}
10210 @end table
10211
10212
10213
10214 @node RRSPACING
10215 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10216 @fnindex RRSPACING
10217 @cindex real number, relative spacing
10218 @cindex floating point, relative spacing
10219
10220
10221 @table @asis
10222 @item @emph{Description}:
10223 @code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
10224 model numbers near @var{X}.
10225
10226 @item @emph{Standard}:
10227 Fortran 95 and later
10228
10229 @item @emph{Class}:
10230 Elemental function
10231
10232 @item @emph{Syntax}:
10233 @code{RESULT = RRSPACING(X)}
10234
10235 @item @emph{Arguments}:
10236 @multitable @columnfractions .15 .70
10237 @item @var{X} @tab Shall be of type @code{REAL}.
10238 @end multitable
10239
10240 @item @emph{Return value}:
10241 The return value is of the same type and kind as @var{X}.
10242 The value returned is equal to
10243 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10244
10245 @item @emph{See also}:
10246 @ref{SPACING}
10247 @end table
10248
10249
10250
10251 @node RSHIFT
10252 @section @code{RSHIFT} --- Right shift bits
10253 @fnindex RSHIFT
10254 @cindex bits, shift right
10255
10256 @table @asis
10257 @item @emph{Description}:
10258 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10259 bits shifted right by @var{SHIFT} places.  If the absolute value of
10260 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10261 Bits shifted out from the right end are lost. The fill is arithmetic: the
10262 bits shifted in from the left end are equal to the leftmost bit, which in
10263 two's complement representation is the sign bit.
10264
10265 This function has been superseded by the @code{SHIFTA} intrinsic, which
10266 is standard in Fortran 2008 and later.
10267
10268 @item @emph{Standard}:
10269 GNU extension
10270
10271 @item @emph{Class}:
10272 Elemental function
10273
10274 @item @emph{Syntax}:
10275 @code{RESULT = RSHIFT(I, SHIFT)}
10276
10277 @item @emph{Arguments}:
10278 @multitable @columnfractions .15 .70
10279 @item @var{I} @tab The type shall be @code{INTEGER}.
10280 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10281 @end multitable
10282
10283 @item @emph{Return value}:
10284 The return value is of type @code{INTEGER} and of the same kind as
10285 @var{I}.
10286
10287 @item @emph{See also}:
10288 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10289 @ref{SHIFTL}
10290
10291 @end table
10292
10293
10294
10295 @node SAME_TYPE_AS
10296 @section @code{SAME_TYPE_AS} ---  Query dynamic types for equality
10297 @fnindex SAME_TYPE_AS
10298
10299 @table @asis
10300 @item @emph{Description}:
10301 Query dynamic types for equality.
10302
10303 @item @emph{Standard}:
10304 Fortran 2003 and later
10305
10306 @item @emph{Class}:
10307 Inquiry function
10308
10309 @item @emph{Syntax}:
10310 @code{RESULT = SAME_TYPE_AS(A, B)}
10311
10312 @item @emph{Arguments}:
10313 @multitable @columnfractions .15 .70
10314 @item @var{A} @tab Shall be an object of extensible declared type or
10315 unlimited polymorphic.
10316 @item @var{B} @tab Shall be an object of extensible declared type or
10317 unlimited polymorphic.
10318 @end multitable
10319
10320 @item @emph{Return value}:
10321 The return value is a scalar of type default logical. It is true if and
10322 only if the dynamic type of A is the same as the dynamic type of B.
10323
10324 @item @emph{See also}:
10325 @ref{EXTENDS_TYPE_OF}
10326
10327 @end table
10328
10329
10330
10331 @node SCALE
10332 @section @code{SCALE} --- Scale a real value
10333 @fnindex SCALE
10334 @cindex real number, scale
10335 @cindex floating point, scale
10336
10337 @table @asis
10338 @item @emph{Description}:
10339 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10340
10341 @item @emph{Standard}:
10342 Fortran 95 and later
10343
10344 @item @emph{Class}:
10345 Elemental function
10346
10347 @item @emph{Syntax}:
10348 @code{RESULT = SCALE(X, I)}
10349
10350 @item @emph{Arguments}:
10351 @multitable @columnfractions .15 .70
10352 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10353 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10354 @end multitable
10355
10356 @item @emph{Return value}:
10357 The return value is of the same type and kind as @var{X}.
10358 Its value is @code{X * RADIX(X)**I}.
10359
10360 @item @emph{Example}:
10361 @smallexample
10362 program test_scale
10363   real :: x = 178.1387e-4
10364   integer :: i = 5
10365   print *, scale(x,i), x*radix(x)**i
10366 end program test_scale
10367 @end smallexample
10368
10369 @end table
10370
10371
10372
10373 @node SCAN
10374 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10375 @fnindex SCAN
10376 @cindex string, find subset
10377
10378 @table @asis
10379 @item @emph{Description}:
10380 Scans a @var{STRING} for any of the characters in a @var{SET}
10381 of characters.
10382
10383 If @var{BACK} is either absent or equals @code{FALSE}, this function
10384 returns the position of the leftmost character of @var{STRING} that is
10385 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10386 is returned. If no character of @var{SET} is found in @var{STRING}, the
10387 result is zero.
10388
10389 @item @emph{Standard}:
10390 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10391
10392 @item @emph{Class}:
10393 Elemental function
10394
10395 @item @emph{Syntax}:
10396 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10397
10398 @item @emph{Arguments}:
10399 @multitable @columnfractions .15 .70
10400 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10401 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
10402 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
10403 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
10404 expression indicating the kind parameter of the result.
10405 @end multitable
10406
10407 @item @emph{Return value}:
10408 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10409 @var{KIND} is absent, the return value is of default integer kind.
10410
10411 @item @emph{Example}:
10412 @smallexample
10413 PROGRAM test_scan
10414   WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
10415   WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
10416   WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
10417 END PROGRAM
10418 @end smallexample
10419
10420 @item @emph{See also}:
10421 @ref{INDEX intrinsic}, @ref{VERIFY}
10422 @end table
10423
10424
10425
10426 @node SECNDS
10427 @section @code{SECNDS} --- Time function
10428 @fnindex SECNDS
10429 @cindex time, elapsed
10430 @cindex elapsed time
10431
10432 @table @asis
10433 @item @emph{Description}:
10434 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10435 @var{X} is a reference time, also in seconds. If this is zero, the time in
10436 seconds from midnight is returned. This function is non-standard and its
10437 use is discouraged.
10438
10439 @item @emph{Standard}:
10440 GNU extension
10441
10442 @item @emph{Class}:
10443 Function
10444
10445 @item @emph{Syntax}:
10446 @code{RESULT = SECNDS (X)}
10447
10448 @item @emph{Arguments}:
10449 @multitable @columnfractions .15 .70
10450 @item @var{T}     @tab Shall be of type @code{REAL(4)}.
10451 @item @var{X}     @tab Shall be of type @code{REAL(4)}.
10452 @end multitable
10453
10454 @item @emph{Return value}:
10455 None
10456
10457 @item @emph{Example}:
10458 @smallexample
10459 program test_secnds
10460     integer :: i
10461     real(4) :: t1, t2
10462     print *, secnds (0.0)   ! seconds since midnight
10463     t1 = secnds (0.0)       ! reference time
10464     do i = 1, 10000000      ! do something
10465     end do
10466     t2 = secnds (t1)        ! elapsed time
10467     print *, "Something took ", t2, " seconds."
10468 end program test_secnds
10469 @end smallexample
10470 @end table
10471
10472
10473
10474 @node SECOND
10475 @section @code{SECOND} --- CPU time function
10476 @fnindex SECOND
10477 @cindex time, elapsed
10478 @cindex elapsed time
10479
10480 @table @asis
10481 @item @emph{Description}:
10482 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10483 seconds.  This provides the same functionality as the standard
10484 @code{CPU_TIME} intrinsic, and is only included for backwards
10485 compatibility.
10486
10487 This intrinsic is provided in both subroutine and function forms;
10488 however, only one form can be used in any given program unit.
10489
10490 @item @emph{Standard}:
10491 GNU extension
10492
10493 @item @emph{Class}:
10494 Subroutine, function
10495
10496 @item @emph{Syntax}:
10497 @multitable @columnfractions .80
10498 @item @code{CALL SECOND(TIME)}
10499 @item @code{TIME = SECOND()}
10500 @end multitable
10501
10502 @item @emph{Arguments}:
10503 @multitable @columnfractions .15 .70
10504 @item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
10505 @end multitable
10506
10507 @item @emph{Return value}:
10508 In either syntax, @var{TIME} is set to the process's current runtime in
10509 seconds.
10510
10511 @item @emph{See also}:
10512 @ref{CPU_TIME}
10513
10514 @end table
10515
10516
10517
10518 @node SELECTED_CHAR_KIND
10519 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10520 @fnindex SELECTED_CHAR_KIND
10521 @cindex character kind
10522 @cindex kind, character
10523
10524 @table @asis
10525 @item @emph{Description}:
10526
10527 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10528 set named @var{NAME}, if a character set with such a name is supported,
10529 or @math{-1} otherwise. Currently, supported character sets include
10530 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10531 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10532
10533 @item @emph{Standard}:
10534 Fortran 2003 and later
10535
10536 @item @emph{Class}:
10537 Transformational function
10538
10539 @item @emph{Syntax}:
10540 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10541
10542 @item @emph{Arguments}:
10543 @multitable @columnfractions .15 .70
10544 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10545 @end multitable
10546
10547 @item @emph{Example}:
10548 @smallexample
10549 program character_kind
10550   use iso_fortran_env
10551   implicit none
10552   integer, parameter :: ascii = selected_char_kind ("ascii")
10553   integer, parameter :: ucs4  = selected_char_kind ('ISO_10646')
10554
10555   character(kind=ascii, len=26) :: alphabet
10556   character(kind=ucs4,  len=30) :: hello_world
10557
10558   alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10559   hello_world = ucs4_'Hello World and Ni Hao -- ' &
10560                 // char (int (z'4F60'), ucs4)     &
10561                 // char (int (z'597D'), ucs4)
10562
10563   write (*,*) alphabet
10564
10565   open (output_unit, encoding='UTF-8')
10566   write (*,*) trim (hello_world)
10567 end program character_kind
10568 @end smallexample
10569 @end table
10570
10571
10572
10573 @node SELECTED_INT_KIND
10574 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10575 @fnindex SELECTED_INT_KIND
10576 @cindex integer kind
10577 @cindex kind, integer
10578
10579 @table @asis
10580 @item @emph{Description}:
10581 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10582 type that can represent all values ranging from @math{-10^R} (exclusive)
10583 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10584 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10585
10586 @item @emph{Standard}:
10587 Fortran 95 and later
10588
10589 @item @emph{Class}:
10590 Transformational function
10591
10592 @item @emph{Syntax}:
10593 @code{RESULT = SELECTED_INT_KIND(R)}
10594
10595 @item @emph{Arguments}:
10596 @multitable @columnfractions .15 .70
10597 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10598 @end multitable
10599
10600 @item @emph{Example}:
10601 @smallexample
10602 program large_integers
10603   integer,parameter :: k5 = selected_int_kind(5)
10604   integer,parameter :: k15 = selected_int_kind(15)
10605   integer(kind=k5) :: i5
10606   integer(kind=k15) :: i15
10607
10608   print *, huge(i5), huge(i15)
10609
10610   ! The following inequalities are always true
10611   print *, huge(i5) >= 10_k5**5-1
10612   print *, huge(i15) >= 10_k15**15-1
10613 end program large_integers
10614 @end smallexample
10615 @end table
10616
10617
10618
10619 @node SELECTED_REAL_KIND
10620 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10621 @fnindex SELECTED_REAL_KIND
10622 @cindex real kind
10623 @cindex kind, real
10624 @cindex radix, real
10625
10626 @table @asis
10627 @item @emph{Description}:
10628 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10629 with decimal precision of at least @code{P} digits, exponent range of
10630 at least @code{R}, and with a radix of @code{RADIX}.
10631
10632 @item @emph{Standard}:
10633 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10634
10635 @item @emph{Class}:
10636 Transformational function
10637
10638 @item @emph{Syntax}:
10639 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10640
10641 @item @emph{Arguments}:
10642 @multitable @columnfractions .15 .70
10643 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10644 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10645 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10646 @end multitable
10647 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10648 be present; since Fortran 2008, they are assumed to be zero if absent.
10649
10650 @item @emph{Return value}:
10651
10652 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10653 a real data type with decimal precision of at least @code{P} digits, a
10654 decimal exponent range of at least @code{R}, and with the requested
10655 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10656 any radix can be returned. If more than one real data type meet the
10657 criteria, the kind of the data type with the smallest decimal precision
10658 is returned. If no real data type matches the criteria, the result is
10659 @table @asis
10660 @item -1 if the processor does not support a real data type with a
10661 precision greater than or equal to @code{P}, but the @code{R} and
10662 @code{RADIX} requirements can be fulfilled
10663 @item -2 if the processor does not support a real type with an exponent
10664 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10665 are fulfillable
10666 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10667 are fulfillable
10668 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10669 are fulfillable
10670 @item -5 if there is no real type with the given @code{RADIX}
10671 @end table
10672
10673 @item @emph{See also}:
10674 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10675
10676 @item @emph{Example}:
10677 @smallexample
10678 program real_kinds
10679   integer,parameter :: p6 = selected_real_kind(6)
10680   integer,parameter :: p10r100 = selected_real_kind(10,100)
10681   integer,parameter :: r400 = selected_real_kind(r=400)
10682   real(kind=p6) :: x
10683   real(kind=p10r100) :: y
10684   real(kind=r400) :: z
10685
10686   print *, precision(x), range(x)
10687   print *, precision(y), range(y)
10688   print *, precision(z), range(z)
10689 end program real_kinds
10690 @end smallexample
10691 @end table
10692
10693
10694
10695 @node SET_EXPONENT
10696 @section @code{SET_EXPONENT} --- Set the exponent of the model
10697 @fnindex SET_EXPONENT
10698 @cindex real number, set exponent
10699 @cindex floating point, set exponent
10700
10701 @table @asis
10702 @item @emph{Description}:
10703 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10704 is that that of @var{X} and whose exponent part is @var{I}.
10705
10706 @item @emph{Standard}:
10707 Fortran 95 and later
10708
10709 @item @emph{Class}:
10710 Elemental function
10711
10712 @item @emph{Syntax}:
10713 @code{RESULT = SET_EXPONENT(X, I)}
10714
10715 @item @emph{Arguments}:
10716 @multitable @columnfractions .15 .70
10717 @item @var{X} @tab Shall be of type @code{REAL}.
10718 @item @var{I} @tab Shall be of type @code{INTEGER}.
10719 @end multitable
10720
10721 @item @emph{Return value}:
10722 The return value is of the same type and kind as @var{X}.
10723 The real number whose fractional part
10724 is that that of @var{X} and whose exponent part if @var{I} is returned;
10725 it is @code{FRACTION(X) * RADIX(X)**I}.
10726
10727 @item @emph{Example}:
10728 @smallexample
10729 PROGRAM test_setexp
10730   REAL :: x = 178.1387e-4
10731   INTEGER :: i = 17
10732   PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10733 END PROGRAM
10734 @end smallexample
10735
10736 @end table
10737
10738
10739
10740 @node SHAPE
10741 @section @code{SHAPE} --- Determine the shape of an array
10742 @fnindex SHAPE
10743 @cindex array, shape
10744
10745 @table @asis
10746 @item @emph{Description}:
10747 Determines the shape of an array.
10748
10749 @item @emph{Standard}:
10750 Fortran 95 and later
10751
10752 @item @emph{Class}:
10753 Inquiry function
10754
10755 @item @emph{Syntax}:
10756 @code{RESULT = SHAPE(SOURCE)}
10757
10758 @item @emph{Arguments}:
10759 @multitable @columnfractions .15 .70
10760 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
10761 If @var{SOURCE} is a pointer it must be associated and allocatable
10762 arrays must be allocated.
10763 @end multitable
10764
10765 @item @emph{Return value}:
10766 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
10767 has dimensions. The elements of the resulting array correspond to the extend
10768 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
10769 the result is the rank one array of size zero.
10770
10771 @item @emph{Example}:
10772 @smallexample
10773 PROGRAM test_shape
10774   INTEGER, DIMENSION(-1:1, -1:2) :: A
10775   WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
10776   WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
10777 END PROGRAM
10778 @end smallexample
10779
10780 @item @emph{See also}:
10781 @ref{RESHAPE}, @ref{SIZE}
10782 @end table
10783
10784
10785
10786 @node SHIFTA
10787 @section @code{SHIFTA} --- Right shift with fill
10788 @fnindex SHIFTA
10789 @cindex bits, shift right
10790 @cindex shift, right with fill
10791
10792 @table @asis
10793 @item @emph{Description}:
10794 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
10795 bits shifted right by @var{SHIFT} places.  If the absolute value of
10796 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10797 Bits shifted out from the right end are lost. The fill is arithmetic: the
10798 bits shifted in from the left end are equal to the leftmost bit, which in
10799 two's complement representation is the sign bit.
10800
10801 @item @emph{Standard}:
10802 Fortran 2008 and later
10803
10804 @item @emph{Class}:
10805 Elemental function
10806
10807 @item @emph{Syntax}:
10808 @code{RESULT = SHIFTA(I, SHIFT)}
10809
10810 @item @emph{Arguments}:
10811 @multitable @columnfractions .15 .70
10812 @item @var{I} @tab The type shall be @code{INTEGER}.
10813 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10814 @end multitable
10815
10816 @item @emph{Return value}:
10817 The return value is of type @code{INTEGER} and of the same kind as
10818 @var{I}.
10819
10820 @item @emph{See also}:
10821 @ref{SHIFTL}, @ref{SHIFTR}
10822 @end table
10823
10824
10825
10826 @node SHIFTL
10827 @section @code{SHIFTL} --- Left shift
10828 @fnindex SHIFTL
10829 @cindex bits, shift left
10830 @cindex shift, left
10831
10832 @table @asis
10833 @item @emph{Description}:
10834 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
10835 bits shifted left by @var{SHIFT} places.  If the absolute value of
10836 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10837 Bits shifted out from the left end are lost, and bits shifted in from
10838 the right end are set to 0.
10839
10840 @item @emph{Standard}:
10841 Fortran 2008 and later
10842
10843 @item @emph{Class}:
10844 Elemental function
10845
10846 @item @emph{Syntax}:
10847 @code{RESULT = SHIFTL(I, SHIFT)}
10848
10849 @item @emph{Arguments}:
10850 @multitable @columnfractions .15 .70
10851 @item @var{I} @tab The type shall be @code{INTEGER}.
10852 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10853 @end multitable
10854
10855 @item @emph{Return value}:
10856 The return value is of type @code{INTEGER} and of the same kind as
10857 @var{I}.
10858
10859 @item @emph{See also}:
10860 @ref{SHIFTA}, @ref{SHIFTR}
10861 @end table
10862
10863
10864
10865 @node SHIFTR
10866 @section @code{SHIFTR} --- Right shift
10867 @fnindex SHIFTR
10868 @cindex bits, shift right
10869 @cindex shift, right
10870
10871 @table @asis
10872 @item @emph{Description}:
10873 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
10874 bits shifted right by @var{SHIFT} places.  If the absolute value of
10875 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10876 Bits shifted out from the right end are lost, and bits shifted in from
10877 the left end are set to 0.
10878
10879 @item @emph{Standard}:
10880 Fortran 2008 and later
10881
10882 @item @emph{Class}:
10883 Elemental function
10884
10885 @item @emph{Syntax}:
10886 @code{RESULT = SHIFTR(I, SHIFT)}
10887
10888 @item @emph{Arguments}:
10889 @multitable @columnfractions .15 .70
10890 @item @var{I} @tab The type shall be @code{INTEGER}.
10891 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10892 @end multitable
10893
10894 @item @emph{Return value}:
10895 The return value is of type @code{INTEGER} and of the same kind as
10896 @var{I}.
10897
10898 @item @emph{See also}:
10899 @ref{SHIFTA}, @ref{SHIFTL}
10900 @end table
10901
10902
10903
10904 @node SIGN
10905 @section @code{SIGN} --- Sign copying function
10906 @fnindex SIGN
10907 @fnindex ISIGN
10908 @fnindex DSIGN
10909 @cindex sign copying
10910
10911 @table @asis
10912 @item @emph{Description}:
10913 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
10914
10915 @item @emph{Standard}:
10916 Fortran 77 and later
10917
10918 @item @emph{Class}:
10919 Elemental function
10920
10921 @item @emph{Syntax}:
10922 @code{RESULT = SIGN(A, B)}
10923
10924 @item @emph{Arguments}:
10925 @multitable @columnfractions .15 .70
10926 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
10927 @item @var{B} @tab Shall be of the same type and kind as @var{A}
10928 @end multitable
10929
10930 @item @emph{Return value}:
10931 The kind of the return value is that of @var{A} and @var{B}.
10932 If @math{B\ge 0} then the result is @code{ABS(A)}, else
10933 it is @code{-ABS(A)}.
10934
10935 @item @emph{Example}:
10936 @smallexample
10937 program test_sign
10938   print *, sign(-12,1)
10939   print *, sign(-12,0)
10940   print *, sign(-12,-1)
10941
10942   print *, sign(-12.,1.)
10943   print *, sign(-12.,0.)
10944   print *, sign(-12.,-1.)
10945 end program test_sign
10946 @end smallexample
10947
10948 @item @emph{Specific names}:
10949 @multitable @columnfractions .20 .20 .20 .25
10950 @item Name              @tab Arguments              @tab Return type       @tab Standard
10951 @item @code{SIGN(A,B)}  @tab @code{REAL(4) A, B}    @tab @code{REAL(4)}    @tab f77, gnu
10952 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
10953 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B}    @tab @code{REAL(8)}    @tab f77, gnu
10954 @end multitable
10955 @end table
10956
10957
10958
10959 @node SIGNAL
10960 @section @code{SIGNAL} --- Signal handling subroutine (or function)
10961 @fnindex SIGNAL
10962 @cindex system, signal handling
10963
10964 @table @asis
10965 @item @emph{Description}:
10966 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
10967 @var{HANDLER} to be executed with a single integer argument when signal
10968 @var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
10969 turn off handling of signal @var{NUMBER} or revert to its default
10970 action.  See @code{signal(2)}.
10971
10972 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
10973 is supplied, it is set to the value returned by @code{signal(2)}.
10974
10975 @item @emph{Standard}:
10976 GNU extension
10977
10978 @item @emph{Class}:
10979 Subroutine, function
10980
10981 @item @emph{Syntax}:
10982 @multitable @columnfractions .80
10983 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
10984 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
10985 @end multitable
10986
10987 @item @emph{Arguments}:
10988 @multitable @columnfractions .15 .70
10989 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
10990 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
10991 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
10992 @code{INTEGER}. It is @code{INTENT(IN)}.
10993 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
10994 integer. It has @code{INTENT(OUT)}.
10995 @end multitable
10996 @c TODO: What should the interface of the handler be?  Does it take arguments?
10997
10998 @item @emph{Return value}:
10999 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11000
11001 @item @emph{Example}:
11002 @smallexample
11003 program test_signal
11004   intrinsic signal
11005   external handler_print
11006
11007   call signal (12, handler_print)
11008   call signal (10, 1)
11009
11010   call sleep (30)
11011 end program test_signal
11012 @end smallexample
11013 @end table
11014
11015
11016
11017 @node SIN
11018 @section @code{SIN} --- Sine function
11019 @fnindex SIN
11020 @fnindex DSIN
11021 @fnindex CSIN
11022 @fnindex ZSIN
11023 @fnindex CDSIN
11024 @cindex trigonometric function, sine
11025 @cindex sine
11026
11027 @table @asis
11028 @item @emph{Description}:
11029 @code{SIN(X)} computes the sine of @var{X}.
11030
11031 @item @emph{Standard}:
11032 Fortran 77 and later
11033
11034 @item @emph{Class}:
11035 Elemental function
11036
11037 @item @emph{Syntax}:
11038 @code{RESULT = SIN(X)}
11039
11040 @item @emph{Arguments}:
11041 @multitable @columnfractions .15 .70
11042 @item @var{X} @tab The type shall be @code{REAL} or
11043 @code{COMPLEX}.
11044 @end multitable
11045
11046 @item @emph{Return value}:
11047 The return value has same type and kind as @var{X}.
11048
11049 @item @emph{Example}:
11050 @smallexample
11051 program test_sin
11052   real :: x = 0.0
11053   x = sin(x)
11054 end program test_sin
11055 @end smallexample
11056
11057 @item @emph{Specific names}:
11058 @multitable @columnfractions .20 .20 .20 .25
11059 @item Name            @tab Argument             @tab Return type       @tab Standard
11060 @item @code{SIN(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}    @tab f77, gnu
11061 @item @code{DSIN(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}    @tab f95, gnu
11062 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)} @tab f95, gnu
11063 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11064 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11065 @end multitable
11066
11067 @item @emph{See also}:
11068 @ref{ASIN}
11069 @end table
11070
11071
11072
11073 @node SINH
11074 @section @code{SINH} --- Hyperbolic sine function
11075 @fnindex SINH
11076 @fnindex DSINH
11077 @cindex hyperbolic sine
11078 @cindex hyperbolic function, sine
11079 @cindex sine, hyperbolic
11080
11081 @table @asis
11082 @item @emph{Description}:
11083 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11084
11085 @item @emph{Standard}:
11086 Fortran 95 and later, for a complex argument Fortran 2008 or later
11087
11088 @item @emph{Class}:
11089 Elemental function
11090
11091 @item @emph{Syntax}:
11092 @code{RESULT = SINH(X)}
11093
11094 @item @emph{Arguments}:
11095 @multitable @columnfractions .15 .70
11096 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11097 @end multitable
11098
11099 @item @emph{Return value}:
11100 The return value has same type and kind as @var{X}.
11101
11102 @item @emph{Example}:
11103 @smallexample
11104 program test_sinh
11105   real(8) :: x = - 1.0_8
11106   x = sinh(x)
11107 end program test_sinh
11108 @end smallexample
11109
11110 @item @emph{Specific names}:
11111 @multitable @columnfractions .20 .20 .20 .25
11112 @item Name            @tab Argument          @tab Return type       @tab Standard
11113 @item @code{SINH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
11114 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
11115 @end multitable
11116
11117 @item @emph{See also}:
11118 @ref{ASINH}
11119 @end table
11120
11121
11122
11123 @node SIZE
11124 @section @code{SIZE} --- Determine the size of an array
11125 @fnindex SIZE
11126 @cindex array, size
11127 @cindex array, number of elements
11128 @cindex array, count elements
11129
11130 @table @asis
11131 @item @emph{Description}:
11132 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11133 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11134
11135 @item @emph{Standard}:
11136 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11137
11138 @item @emph{Class}:
11139 Inquiry function
11140
11141 @item @emph{Syntax}:
11142 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11143
11144 @item @emph{Arguments}:
11145 @multitable @columnfractions .15 .70
11146 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11147 a pointer it must be associated and allocatable arrays must be allocated.
11148 @item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
11149 and its value shall be in the range from 1 to n, where n equals the rank
11150 of @var{ARRAY}.
11151 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11152 expression indicating the kind parameter of the result.
11153 @end multitable
11154
11155 @item @emph{Return value}:
11156 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11157 @var{KIND} is absent, the return value is of default integer kind.
11158
11159 @item @emph{Example}:
11160 @smallexample
11161 PROGRAM test_size
11162   WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
11163 END PROGRAM
11164 @end smallexample
11165
11166 @item @emph{See also}:
11167 @ref{SHAPE}, @ref{RESHAPE}
11168 @end table
11169
11170
11171 @node SIZEOF
11172 @section @code{SIZEOF} --- Size in bytes of an expression
11173 @fnindex SIZEOF
11174 @cindex expression size
11175 @cindex size of an expression
11176
11177 @table @asis
11178 @item @emph{Description}:
11179 @code{SIZEOF(X)} calculates the number of bytes of storage the
11180 expression @code{X} occupies.
11181
11182 @item @emph{Standard}:
11183 GNU extension
11184
11185 @item @emph{Class}:
11186 Intrinsic function
11187
11188 @item @emph{Syntax}:
11189 @code{N = SIZEOF(X)}
11190
11191 @item @emph{Arguments}:
11192 @multitable @columnfractions .15 .70
11193 @item @var{X} @tab The argument shall be of any type, rank or shape.
11194 @end multitable
11195
11196 @item @emph{Return value}:
11197 The return value is of type integer and of the system-dependent kind
11198 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11199 number of bytes occupied by the argument.  If the argument has the
11200 @code{POINTER} attribute, the number of bytes of the storage area pointed
11201 to is returned.  If the argument is of a derived type with @code{POINTER}
11202 or @code{ALLOCATABLE} components, the return value doesn't account for
11203 the sizes of the data pointed to by these components. If the argument is
11204 polymorphic, the size according to the declared type is returned.
11205
11206 @item @emph{Example}:
11207 @smallexample
11208    integer :: i
11209    real :: r, s(5)
11210    print *, (sizeof(s)/sizeof(r) == 5)
11211    end
11212 @end smallexample
11213 The example will print @code{.TRUE.} unless you are using a platform
11214 where default @code{REAL} variables are unusually padded.
11215
11216 @item @emph{See also}:
11217 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11218 @end table
11219
11220
11221 @node SLEEP
11222 @section @code{SLEEP} --- Sleep for the specified number of seconds
11223 @fnindex SLEEP
11224 @cindex delayed execution
11225
11226 @table @asis
11227 @item @emph{Description}:
11228 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11229
11230 @item @emph{Standard}:
11231 GNU extension
11232
11233 @item @emph{Class}:
11234 Subroutine
11235
11236 @item @emph{Syntax}:
11237 @code{CALL SLEEP(SECONDS)}
11238
11239 @item @emph{Arguments}:
11240 @multitable @columnfractions .15 .70
11241 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11242 @end multitable
11243
11244 @item @emph{Example}:
11245 @smallexample
11246 program test_sleep
11247   call sleep(5)
11248 end
11249 @end smallexample
11250 @end table
11251
11252
11253
11254 @node SPACING
11255 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11256 @fnindex SPACING
11257 @cindex real number, relative spacing
11258 @cindex floating point, relative spacing
11259
11260 @table @asis
11261 @item @emph{Description}:
11262 Determines the distance between the argument @var{X} and the nearest
11263 adjacent number of the same type.
11264
11265 @item @emph{Standard}:
11266 Fortran 95 and later
11267
11268 @item @emph{Class}:
11269 Elemental function
11270
11271 @item @emph{Syntax}:
11272 @code{RESULT = SPACING(X)}
11273
11274 @item @emph{Arguments}:
11275 @multitable @columnfractions .15 .70
11276 @item @var{X} @tab Shall be of type @code{REAL}.
11277 @end multitable
11278
11279 @item @emph{Return value}:
11280 The result is of the same type as the input argument @var{X}.
11281
11282 @item @emph{Example}:
11283 @smallexample
11284 PROGRAM test_spacing
11285   INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11286   INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11287
11288   WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
11289   WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
11290 END PROGRAM
11291 @end smallexample
11292
11293 @item @emph{See also}:
11294 @ref{RRSPACING}
11295 @end table
11296
11297
11298
11299 @node SPREAD
11300 @section @code{SPREAD} --- Add a dimension to an array
11301 @fnindex SPREAD
11302 @cindex array, increase dimension
11303 @cindex array, duplicate elements
11304 @cindex array, duplicate dimensions
11305
11306 @table @asis
11307 @item @emph{Description}:
11308 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11309 dimension @var{DIM}.
11310
11311 @item @emph{Standard}:
11312 Fortran 95 and later
11313
11314 @item @emph{Class}:
11315 Transformational function
11316
11317 @item @emph{Syntax}:
11318 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11319
11320 @item @emph{Arguments}:
11321 @multitable @columnfractions .15 .70
11322 @item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
11323 a rank less than seven.
11324 @item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
11325 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11326 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11327 @end multitable
11328
11329 @item @emph{Return value}:
11330 The result is an array of the same type as @var{SOURCE} and has rank n+1
11331 where n equals the rank of @var{SOURCE}.
11332
11333 @item @emph{Example}:
11334 @smallexample
11335 PROGRAM test_spread
11336   INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11337   WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
11338   WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
11339 END PROGRAM
11340 @end smallexample
11341
11342 @item @emph{See also}:
11343 @ref{UNPACK}
11344 @end table
11345
11346
11347
11348 @node SQRT
11349 @section @code{SQRT} --- Square-root function
11350 @fnindex SQRT
11351 @fnindex DSQRT
11352 @fnindex CSQRT
11353 @fnindex ZSQRT
11354 @fnindex CDSQRT
11355 @cindex root
11356 @cindex square-root
11357
11358 @table @asis
11359 @item @emph{Description}:
11360 @code{SQRT(X)} computes the square root of @var{X}.
11361
11362 @item @emph{Standard}:
11363 Fortran 77 and later
11364
11365 @item @emph{Class}:
11366 Elemental function
11367
11368 @item @emph{Syntax}:
11369 @code{RESULT = SQRT(X)}
11370
11371 @item @emph{Arguments}:
11372 @multitable @columnfractions .15 .70
11373 @item @var{X} @tab The type shall be @code{REAL} or
11374 @code{COMPLEX}.
11375 @end multitable
11376
11377 @item @emph{Return value}:
11378 The return value is of type @code{REAL} or @code{COMPLEX}.
11379 The kind type parameter is the same as @var{X}.
11380
11381 @item @emph{Example}:
11382 @smallexample
11383 program test_sqrt
11384   real(8) :: x = 2.0_8
11385   complex :: z = (1.0, 2.0)
11386   x = sqrt(x)
11387   z = sqrt(z)
11388 end program test_sqrt
11389 @end smallexample
11390
11391 @item @emph{Specific names}:
11392 @multitable @columnfractions .20 .20 .20 .25
11393 @item Name             @tab Argument             @tab Return type          @tab Standard
11394 @item @code{SQRT(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}       @tab Fortran 95 and later
11395 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 95 and later
11396 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 95 and later
11397 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11398 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11399 @end multitable
11400 @end table
11401
11402
11403
11404 @node SRAND
11405 @section @code{SRAND} --- Reinitialize the random number generator
11406 @fnindex SRAND
11407 @cindex random number generation, seeding
11408 @cindex seeding a random number generator
11409
11410 @table @asis
11411 @item @emph{Description}:
11412 @code{SRAND} reinitializes the pseudo-random number generator
11413 called by @code{RAND} and @code{IRAND}. The new seed used by the
11414 generator is specified by the required argument @var{SEED}.
11415
11416 @item @emph{Standard}:
11417 GNU extension
11418
11419 @item @emph{Class}:
11420 Subroutine
11421
11422 @item @emph{Syntax}:
11423 @code{CALL SRAND(SEED)}
11424
11425 @item @emph{Arguments}:
11426 @multitable @columnfractions .15 .70
11427 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11428 @end multitable
11429
11430 @item @emph{Return value}:
11431 Does not return anything.
11432
11433 @item @emph{Example}:
11434 See @code{RAND} and @code{IRAND} for examples.
11435
11436 @item @emph{Notes}:
11437 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11438 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11439 to generate pseudo-random numbers. Please note that in
11440 GNU Fortran, these two sets of intrinsics (@code{RAND},
11441 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11442 @code{RANDOM_SEED} on the other hand) access two independent
11443 pseudo-random number generators.
11444
11445 @item @emph{See also}:
11446 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11447
11448 @end table
11449
11450
11451
11452 @node STAT
11453 @section @code{STAT} --- Get file status
11454 @fnindex STAT
11455 @cindex file system, file status
11456
11457 @table @asis
11458 @item @emph{Description}:
11459 This function returns information about a file. No permissions are required on
11460 the file itself, but execute (search) permission is required on all of the
11461 directories in path that lead to the file.
11462
11463 The elements that are obtained and stored in the array @code{VALUES}:
11464 @multitable @columnfractions .15 .70
11465 @item @code{VALUES(1)}   @tab  Device ID
11466 @item @code{VALUES(2)}   @tab  Inode number
11467 @item @code{VALUES(3)}   @tab  File mode
11468 @item @code{VALUES(4)}   @tab  Number of links
11469 @item @code{VALUES(5)}   @tab  Owner's uid
11470 @item @code{VALUES(6)}   @tab  Owner's gid
11471 @item @code{VALUES(7)}   @tab  ID of device containing directory entry for file (0 if not available)
11472 @item @code{VALUES(8)}   @tab  File size (bytes)
11473 @item @code{VALUES(9)}   @tab  Last access time
11474 @item @code{VALUES(10)}  @tab  Last modification time
11475 @item @code{VALUES(11)}  @tab  Last file status change time
11476 @item @code{VALUES(12)}  @tab  Preferred I/O block size (-1 if not available)
11477 @item @code{VALUES(13)}  @tab  Number of blocks allocated (-1 if not available)
11478 @end multitable
11479
11480 Not all these elements are relevant on all systems.
11481 If an element is not relevant, it is returned as 0.
11482
11483 This intrinsic is provided in both subroutine and function forms; however,
11484 only one form can be used in any given program unit.
11485
11486 @item @emph{Standard}:
11487 GNU extension
11488
11489 @item @emph{Class}:
11490 Subroutine, function
11491
11492 @item @emph{Syntax}:
11493 @multitable @columnfractions .80
11494 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11495 @item @code{STATUS = STAT(NAME, VALUES)}
11496 @end multitable
11497
11498 @item @emph{Arguments}:
11499 @multitable @columnfractions .15 .70
11500 @item @var{NAME}   @tab The type shall be @code{CHARACTER}, of the
11501 default kind and a valid path within the file system.
11502 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11503 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11504 on success and a system specific error code otherwise.
11505 @end multitable
11506
11507 @item @emph{Example}:
11508 @smallexample
11509 PROGRAM test_stat
11510   INTEGER, DIMENSION(13) :: buff
11511   INTEGER :: status
11512
11513   CALL STAT("/etc/passwd", buff, status)
11514
11515   IF (status == 0) THEN
11516     WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
11517     WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
11518     WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
11519     WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
11520     WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
11521     WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
11522     WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
11523     WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
11524     WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
11525     WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
11526     WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11527     WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
11528     WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11529   END IF
11530 END PROGRAM
11531 @end smallexample
11532
11533 @item @emph{See also}:
11534 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11535 @end table
11536
11537
11538
11539 @node STORAGE_SIZE
11540 @section @code{STORAGE_SIZE} --- Storage size in bits
11541 @fnindex STORAGE_SIZE
11542 @cindex storage size
11543
11544 @table @asis
11545 @item @emph{Description}:
11546 Returns the storage size of argument @var{A} in bits.
11547 @item @emph{Standard}:
11548 Fortran 2008 and later
11549 @item @emph{Class}:
11550 Inquiry function
11551 @item @emph{Syntax}:
11552 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11553
11554 @item @emph{Arguments}:
11555 @multitable @columnfractions .15 .70
11556 @item @var{A} @tab Shall be a scalar or array of any type.
11557 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11558 @end multitable
11559
11560 @item @emph{Return Value}:
11561 The result is a scalar integer with the kind type parameter speciﬁed by KIND (or default integer type if KIND is missing). The result value is the size expressed in bits for an element of an array that
11562 has the dynamic type and type parameters of A.
11563
11564 @item @emph{See also}:
11565 @ref{C_SIZEOF}, @ref{SIZEOF}
11566 @end table
11567
11568
11569
11570 @node SUM
11571 @section @code{SUM} --- Sum of array elements
11572 @fnindex SUM
11573 @cindex array, sum
11574 @cindex array, add elements
11575 @cindex array, conditionally add elements
11576 @cindex sum array elements
11577
11578 @table @asis
11579 @item @emph{Description}:
11580 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11581 the corresponding element in @var{MASK} is @code{TRUE}.
11582
11583 @item @emph{Standard}:
11584 Fortran 95 and later
11585
11586 @item @emph{Class}:
11587 Transformational function
11588
11589 @item @emph{Syntax}:
11590 @multitable @columnfractions .80
11591 @item @code{RESULT = SUM(ARRAY[, MASK])}
11592 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11593 @end multitable
11594
11595 @item @emph{Arguments}:
11596 @multitable @columnfractions .15 .70
11597 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11598 @code{REAL} or @code{COMPLEX}.
11599 @item @var{DIM}   @tab (Optional) shall be a scalar of type
11600 @code{INTEGER} with a value in the range from 1 to n, where n
11601 equals the rank of @var{ARRAY}.
11602 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
11603 and either be a scalar or an array of the same shape as @var{ARRAY}.
11604 @end multitable
11605
11606 @item @emph{Return value}:
11607 The result is of the same type as @var{ARRAY}.
11608
11609 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11610 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11611 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11612 dropped is returned.
11613
11614 @item @emph{Example}:
11615 @smallexample
11616 PROGRAM test_sum
11617   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11618   print *, SUM(x)                        ! all elements, sum = 15
11619   print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
11620 END PROGRAM
11621 @end smallexample
11622
11623 @item @emph{See also}:
11624 @ref{PRODUCT}
11625 @end table
11626
11627
11628
11629 @node SYMLNK
11630 @section @code{SYMLNK} --- Create a symbolic link
11631 @fnindex SYMLNK
11632 @cindex file system, create link
11633 @cindex file system, soft link
11634
11635 @table @asis
11636 @item @emph{Description}:
11637 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11638 character (@code{CHAR(0)}) can be used to mark the end of the names in
11639 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11640 names are ignored.  If the @var{STATUS} argument is supplied, it
11641 contains 0 on success or a nonzero error code upon return; see
11642 @code{symlink(2)}.  If the system does not supply @code{symlink(2)},
11643 @code{ENOSYS} is returned.
11644
11645 This intrinsic is provided in both subroutine and function forms;
11646 however, only one form can be used in any given program unit.
11647
11648 @item @emph{Standard}:
11649 GNU extension
11650
11651 @item @emph{Class}:
11652 Subroutine, function
11653
11654 @item @emph{Syntax}:
11655 @multitable @columnfractions .80
11656 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11657 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11658 @end multitable
11659
11660 @item @emph{Arguments}:
11661 @multitable @columnfractions .15 .70
11662 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11663 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11664 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11665 @end multitable
11666
11667 @item @emph{See also}:
11668 @ref{LINK}, @ref{UNLINK}
11669
11670 @end table
11671
11672
11673
11674 @node SYSTEM
11675 @section @code{SYSTEM} --- Execute a shell command
11676 @fnindex SYSTEM
11677 @cindex system, system call
11678
11679 @table @asis
11680 @item @emph{Description}:
11681 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11682 argument @var{STATUS} is present, it contains the value returned by
11683 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11684 Note that which shell is used to invoke the command is system-dependent
11685 and environment-dependent.
11686
11687 This intrinsic is provided in both subroutine and function forms;
11688 however, only one form can be used in any given program unit.
11689
11690 @item @emph{Standard}:
11691 GNU extension
11692
11693 @item @emph{Class}:
11694 Subroutine, function
11695
11696 @item @emph{Syntax}:
11697 @multitable @columnfractions .80
11698 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11699 @item @code{STATUS = SYSTEM(COMMAND)}
11700 @end multitable
11701
11702 @item @emph{Arguments}:
11703 @multitable @columnfractions .15 .70
11704 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11705 @item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
11706 @end multitable
11707
11708 @item @emph{See also}:
11709 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11710 and should considered in new code for future portability.
11711 @end table
11712
11713
11714
11715 @node SYSTEM_CLOCK
11716 @section @code{SYSTEM_CLOCK} --- Time function
11717 @fnindex SYSTEM_CLOCK
11718 @cindex time, clock ticks
11719 @cindex clock ticks
11720
11721 @table @asis
11722 @item @emph{Description}:
11723 Determines the @var{COUNT} of milliseconds of wall clock time since
11724 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
11725 @var{COUNT_RATE} determines the number of clock ticks per second.
11726 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
11727 @command{gfortran}.
11728
11729 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
11730 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
11731
11732 @item @emph{Standard}:
11733 Fortran 95 and later
11734
11735 @item @emph{Class}:
11736 Subroutine
11737
11738 @item @emph{Syntax}:
11739 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
11740
11741 @item @emph{Arguments}:
11742 @multitable @columnfractions .15 .70
11743 @item @var{COUNT}      @tab (Optional) shall be a scalar of type default
11744 @code{INTEGER} with @code{INTENT(OUT)}.
11745 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
11746 @code{INTEGER} with @code{INTENT(OUT)}.
11747 @item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type default
11748 @code{INTEGER} with @code{INTENT(OUT)}.
11749 @end multitable
11750
11751 @item @emph{Example}:
11752 @smallexample
11753 PROGRAM test_system_clock
11754   INTEGER :: count, count_rate, count_max
11755   CALL SYSTEM_CLOCK(count, count_rate, count_max)
11756   WRITE(*,*) count, count_rate, count_max
11757 END PROGRAM
11758 @end smallexample
11759
11760 @item @emph{See also}:
11761 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
11762 @end table
11763
11764
11765
11766 @node TAN
11767 @section @code{TAN} --- Tangent function
11768 @fnindex TAN
11769 @fnindex DTAN
11770 @cindex trigonometric function, tangent
11771 @cindex tangent
11772
11773 @table @asis
11774 @item @emph{Description}:
11775 @code{TAN(X)} computes the tangent of @var{X}.
11776
11777 @item @emph{Standard}:
11778 Fortran 77 and later, for a complex argument Fortran 2008 or later
11779
11780 @item @emph{Class}:
11781 Elemental function
11782
11783 @item @emph{Syntax}:
11784 @code{RESULT = TAN(X)}
11785
11786 @item @emph{Arguments}:
11787 @multitable @columnfractions .15 .70
11788 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11789 @end multitable
11790
11791 @item @emph{Return value}:
11792 The return value has same type and kind as @var{X}.
11793
11794 @item @emph{Example}:
11795 @smallexample
11796 program test_tan
11797   real(8) :: x = 0.165_8
11798   x = tan(x)
11799 end program test_tan
11800 @end smallexample
11801
11802 @item @emph{Specific names}:
11803 @multitable @columnfractions .20 .20 .20 .25
11804 @item Name            @tab Argument          @tab Return type     @tab Standard
11805 @item @code{TAN(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab Fortran 95 and later
11806 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab Fortran 95 and later
11807 @end multitable
11808
11809 @item @emph{See also}:
11810 @ref{ATAN}
11811 @end table
11812
11813
11814
11815 @node TANH
11816 @section @code{TANH} --- Hyperbolic tangent function
11817 @fnindex TANH
11818 @fnindex DTANH
11819 @cindex hyperbolic tangent
11820 @cindex hyperbolic function, tangent
11821 @cindex tangent, hyperbolic
11822
11823 @table @asis
11824 @item @emph{Description}:
11825 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
11826
11827 @item @emph{Standard}:
11828 Fortran 77 and later, for a complex argument Fortran 2008 or later
11829
11830 @item @emph{Class}:
11831 Elemental function
11832
11833 @item @emph{Syntax}:
11834 @code{X = TANH(X)}
11835
11836 @item @emph{Arguments}:
11837 @multitable @columnfractions .15 .70
11838 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11839 @end multitable
11840
11841 @item @emph{Return value}:
11842 The return value has same type and kind as @var{X}. If @var{X} is
11843 complex, the imaginary part of the result is in radians. If @var{X}
11844 is @code{REAL}, the return value lies in the range
11845 @math{ - 1 \leq tanh(x) \leq 1 }.
11846
11847 @item @emph{Example}:
11848 @smallexample
11849 program test_tanh
11850   real(8) :: x = 2.1_8
11851   x = tanh(x)
11852 end program test_tanh
11853 @end smallexample
11854
11855 @item @emph{Specific names}:
11856 @multitable @columnfractions .20 .20 .20 .25
11857 @item Name            @tab Argument          @tab Return type       @tab Standard
11858 @item @code{TANH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
11859 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
11860 @end multitable
11861
11862 @item @emph{See also}:
11863 @ref{ATANH}
11864 @end table
11865
11866
11867
11868 @node THIS_IMAGE
11869 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
11870 @fnindex THIS_IMAGE
11871 @cindex coarray, @code{THIS_IMAGE}
11872 @cindex images, index of this image
11873
11874 @table @asis
11875 @item @emph{Description}:
11876 Returns the cosubscript for this image.
11877
11878 @item @emph{Standard}:
11879 Fortran 2008 and later
11880
11881 @item @emph{Class}:
11882 Transformational function
11883
11884 @item @emph{Syntax}:
11885 @multitable @columnfractions .80
11886 @item @code{RESULT = THIS_IMAGE()}
11887 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
11888 @end multitable
11889
11890 @item @emph{Arguments}:
11891 @multitable @columnfractions .15 .70
11892 @item @var{COARRAY} @tab Coarray of any type  (optional; if @var{DIM}
11893 present, required).
11894 @item @var{DIM}     @tab default integer scalar (optional). If present,
11895 @var{DIM} shall be between one and the corank of @var{COARRAY}.
11896 @end multitable
11897
11898
11899 @item @emph{Return value}:
11900 Default integer. If @var{COARRAY} is not present, it is scalar and its value
11901 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
11902 a rank-1 array with corank elements is returned, containing the cosubscripts
11903 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
11904 a scalar is returned, with the value of the @var{DIM} element of
11905 @code{THIS_IMAGE(COARRAY)}.
11906
11907 @item @emph{Example}:
11908 @smallexample
11909 INTEGER :: value[*]
11910 INTEGER :: i
11911 value = THIS_IMAGE()
11912 SYNC ALL
11913 IF (THIS_IMAGE() == 1) THEN
11914   DO i = 1, NUM_IMAGES()
11915     WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11916   END DO
11917 END IF
11918 @end smallexample
11919
11920 @item @emph{See also}:
11921 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
11922 @end table
11923
11924
11925
11926 @node TIME
11927 @section @code{TIME} --- Time function
11928 @fnindex TIME
11929 @cindex time, current
11930 @cindex current time
11931
11932 @table @asis
11933 @item @emph{Description}:
11934 Returns the current time encoded as an integer (in the manner of the
11935 UNIX function @code{time(3)}). This value is suitable for passing to
11936 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
11937
11938 This intrinsic is not fully portable, such as to systems with 32-bit
11939 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
11940 the values returned by this intrinsic might be, or become, negative, or
11941 numerically less than previous values, during a single run of the
11942 compiled program.
11943
11944 See @ref{TIME8}, for information on a similar intrinsic that might be
11945 portable to more GNU Fortran implementations, though to fewer Fortran
11946 compilers.
11947
11948 @item @emph{Standard}:
11949 GNU extension
11950
11951 @item @emph{Class}:
11952 Function
11953
11954 @item @emph{Syntax}:
11955 @code{RESULT = TIME()}
11956
11957 @item @emph{Return value}:
11958 The return value is a scalar of type @code{INTEGER(4)}.
11959
11960 @item @emph{See also}:
11961 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
11962
11963 @end table
11964
11965
11966
11967 @node TIME8
11968 @section @code{TIME8} --- Time function (64-bit)
11969 @fnindex TIME8
11970 @cindex time, current
11971 @cindex current time
11972
11973 @table @asis
11974 @item @emph{Description}:
11975 Returns the current time encoded as an integer (in the manner of the
11976 UNIX function @code{time(3)}). This value is suitable for passing to
11977 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
11978
11979 @emph{Warning:} this intrinsic does not increase the range of the timing
11980 values over that returned by @code{time(3)}. On a system with a 32-bit
11981 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
11982 it is converted to a 64-bit @code{INTEGER(8)} value. That means
11983 overflows of the 32-bit value can still occur. Therefore, the values
11984 returned by this intrinsic might be or become negative or numerically
11985 less than previous values during a single run of the compiled program.
11986
11987 @item @emph{Standard}:
11988 GNU extension
11989
11990 @item @emph{Class}:
11991 Function
11992
11993 @item @emph{Syntax}:
11994 @code{RESULT = TIME8()}
11995
11996 @item @emph{Return value}:
11997 The return value is a scalar of type @code{INTEGER(8)}.
11998
11999 @item @emph{See also}:
12000 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12001
12002 @end table
12003
12004
12005
12006 @node TINY
12007 @section @code{TINY} --- Smallest positive number of a real kind
12008 @fnindex TINY
12009 @cindex limits, smallest number
12010 @cindex model representation, smallest number
12011
12012 @table @asis
12013 @item @emph{Description}:
12014 @code{TINY(X)} returns the smallest positive (non zero) number
12015 in the model of the type of @code{X}.
12016
12017 @item @emph{Standard}:
12018 Fortran 95 and later
12019
12020 @item @emph{Class}:
12021 Inquiry function
12022
12023 @item @emph{Syntax}:
12024 @code{RESULT = TINY(X)}
12025
12026 @item @emph{Arguments}:
12027 @multitable @columnfractions .15 .70
12028 @item @var{X} @tab Shall be of type @code{REAL}.
12029 @end multitable
12030
12031 @item @emph{Return value}:
12032 The return value is of the same type and kind as @var{X}
12033
12034 @item @emph{Example}:
12035 See @code{HUGE} for an example.
12036 @end table
12037
12038
12039
12040 @node TRAILZ
12041 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12042 @fnindex TRAILZ
12043 @cindex zero bits
12044
12045 @table @asis
12046 @item @emph{Description}:
12047 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12048
12049 @item @emph{Standard}:
12050 Fortran 2008 and later
12051
12052 @item @emph{Class}:
12053 Elemental function
12054
12055 @item @emph{Syntax}:
12056 @code{RESULT = TRAILZ(I)}
12057
12058 @item @emph{Arguments}:
12059 @multitable @columnfractions .15 .70
12060 @item @var{I} @tab Shall be of type @code{INTEGER}.
12061 @end multitable
12062
12063 @item @emph{Return value}:
12064 The type of the return value is the default @code{INTEGER}.
12065 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12066
12067 @item @emph{Example}:
12068 @smallexample
12069 PROGRAM test_trailz
12070   WRITE (*,*) TRAILZ(8)  ! prints 3
12071 END PROGRAM
12072 @end smallexample
12073
12074 @item @emph{See also}:
12075 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12076 @end table
12077
12078
12079
12080 @node TRANSFER
12081 @section @code{TRANSFER} --- Transfer bit patterns
12082 @fnindex TRANSFER
12083 @cindex bits, move
12084 @cindex type cast
12085
12086 @table @asis
12087 @item @emph{Description}:
12088 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12089 is the representation of a variable or array of the same type and type
12090 parameters as @var{MOLD}.
12091
12092 This is approximately equivalent to the C concept of @emph{casting} one
12093 type to another.
12094
12095 @item @emph{Standard}:
12096 Fortran 95 and later
12097
12098 @item @emph{Class}:
12099 Transformational function
12100
12101 @item @emph{Syntax}:
12102 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12103
12104 @item @emph{Arguments}:
12105 @multitable @columnfractions .15 .70
12106 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12107 @item @var{MOLD}   @tab Shall be a scalar or an array of any type.
12108 @item @var{SIZE}   @tab (Optional) shall be a scalar of type
12109 @code{INTEGER}.
12110 @end multitable
12111
12112 @item @emph{Return value}:
12113 The result has the same type as @var{MOLD}, with the bit level
12114 representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
12115 a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
12116 but @var{MOLD} is an array (of any size or shape), the result is a one-
12117 dimensional array of the minimum length needed to contain the entirety
12118 of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
12119 and @var{MOLD} is a scalar, the result is a scalar.
12120
12121 If the bitwise representation of the result is longer than that of
12122 @var{SOURCE}, then the leading bits of the result correspond to those of
12123 @var{SOURCE} and any trailing bits are filled arbitrarily.
12124
12125 When the resulting bit representation does not correspond to a valid
12126 representation of a variable of the same type as @var{MOLD}, the results
12127 are undefined, and subsequent operations on the result cannot be
12128 guaranteed to produce sensible behavior.  For example, it is possible to
12129 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12130 @code{.NOT.@var{VAR}} both appear to be true.
12131
12132 @item @emph{Example}:
12133 @smallexample
12134 PROGRAM test_transfer
12135   integer :: x = 2143289344
12136   print *, transfer(x, 1.0)    ! prints "NaN" on i686
12137 END PROGRAM
12138 @end smallexample
12139 @end table
12140
12141
12142
12143 @node TRANSPOSE
12144 @section @code{TRANSPOSE} --- Transpose an array of rank two
12145 @fnindex TRANSPOSE
12146 @cindex array, transpose
12147 @cindex matrix, transpose
12148 @cindex transpose
12149
12150 @table @asis
12151 @item @emph{Description}:
12152 Transpose an array of rank two. Element (i, j) of the result has the value
12153 @code{MATRIX(j, i)}, for all i, j.
12154
12155 @item @emph{Standard}:
12156 Fortran 95 and later
12157
12158 @item @emph{Class}:
12159 Transformational function
12160
12161 @item @emph{Syntax}:
12162 @code{RESULT = TRANSPOSE(MATRIX)}
12163
12164 @item @emph{Arguments}:
12165 @multitable @columnfractions .15 .70
12166 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12167 @end multitable
12168
12169 @item @emph{Return value}:
12170 The result has the same type as @var{MATRIX}, and has shape
12171 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12172 @end table
12173
12174
12175
12176 @node TRIM
12177 @section @code{TRIM} --- Remove trailing blank characters of a string
12178 @fnindex TRIM
12179 @cindex string, remove trailing whitespace
12180
12181 @table @asis
12182 @item @emph{Description}:
12183 Removes trailing blank characters of a string.
12184
12185 @item @emph{Standard}:
12186 Fortran 95 and later
12187
12188 @item @emph{Class}:
12189 Transformational function
12190
12191 @item @emph{Syntax}:
12192 @code{RESULT = TRIM(STRING)}
12193
12194 @item @emph{Arguments}:
12195 @multitable @columnfractions .15 .70
12196 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12197 @end multitable
12198
12199 @item @emph{Return value}:
12200 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12201 less the number of trailing blanks.
12202
12203 @item @emph{Example}:
12204 @smallexample
12205 PROGRAM test_trim
12206   CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
12207   WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
12208 END PROGRAM
12209 @end smallexample
12210
12211 @item @emph{See also}:
12212 @ref{ADJUSTL}, @ref{ADJUSTR}
12213 @end table
12214
12215
12216
12217 @node TTYNAM
12218 @section @code{TTYNAM} --- Get the name of a terminal device.
12219 @fnindex TTYNAM
12220 @cindex system, terminal
12221
12222 @table @asis
12223 @item @emph{Description}:
12224 Get the name of a terminal device. For more information,
12225 see @code{ttyname(3)}.
12226
12227 This intrinsic is provided in both subroutine and function forms;
12228 however, only one form can be used in any given program unit.
12229
12230 @item @emph{Standard}:
12231 GNU extension
12232
12233 @item @emph{Class}:
12234 Subroutine, function
12235
12236 @item @emph{Syntax}:
12237 @multitable @columnfractions .80
12238 @item @code{CALL TTYNAM(UNIT, NAME)}
12239 @item @code{NAME = TTYNAM(UNIT)}
12240 @end multitable
12241
12242 @item @emph{Arguments}:
12243 @multitable @columnfractions .15 .70
12244 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12245 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12246 @end multitable
12247
12248 @item @emph{Example}:
12249 @smallexample
12250 PROGRAM test_ttynam
12251   INTEGER :: unit
12252   DO unit = 1, 10
12253     IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12254   END DO
12255 END PROGRAM
12256 @end smallexample
12257
12258 @item @emph{See also}:
12259 @ref{ISATTY}
12260 @end table
12261
12262
12263
12264 @node UBOUND
12265 @section @code{UBOUND} --- Upper dimension bounds of an array
12266 @fnindex UBOUND
12267 @cindex array, upper bound
12268
12269 @table @asis
12270 @item @emph{Description}:
12271 Returns the upper bounds of an array, or a single upper bound
12272 along the @var{DIM} dimension.
12273 @item @emph{Standard}:
12274 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12275
12276 @item @emph{Class}:
12277 Inquiry function
12278
12279 @item @emph{Syntax}:
12280 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12281
12282 @item @emph{Arguments}:
12283 @multitable @columnfractions .15 .70
12284 @item @var{ARRAY} @tab Shall be an array, of any type.
12285 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12286 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12287 expression indicating the kind parameter of the result.
12288 @end multitable
12289
12290 @item @emph{Return value}:
12291 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12292 @var{KIND} is absent, the return value is of default integer kind.
12293 If @var{DIM} is absent, the result is an array of the upper bounds of
12294 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
12295 corresponding to the upper bound of the array along that dimension.  If
12296 @var{ARRAY} is an expression rather than a whole array or array
12297 structure component, or if it has a zero extent along the relevant
12298 dimension, the upper bound is taken to be the number of elements along
12299 the relevant dimension.
12300
12301 @item @emph{See also}:
12302 @ref{LBOUND}, @ref{LCOBOUND}
12303 @end table
12304
12305
12306
12307 @node UCOBOUND
12308 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12309 @fnindex UCOBOUND
12310 @cindex coarray, upper bound
12311
12312 @table @asis
12313 @item @emph{Description}:
12314 Returns the upper cobounds of a coarray, or a single upper cobound
12315 along the @var{DIM} codimension.
12316 @item @emph{Standard}:
12317 Fortran 2008 and later
12318
12319 @item @emph{Class}:
12320 Inquiry function
12321
12322 @item @emph{Syntax}:
12323 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12324
12325 @item @emph{Arguments}:
12326 @multitable @columnfractions .15 .70
12327 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12328 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12329 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12330 expression indicating the kind parameter of the result.
12331 @end multitable
12332
12333 @item @emph{Return value}:
12334 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12335 @var{KIND} is absent, the return value is of default integer kind.
12336 If @var{DIM} is absent, the result is an array of the lower cobounds of
12337 @var{COARRAY}.  If @var{DIM} is present, the result is a scalar
12338 corresponding to the lower cobound of the array along that codimension.
12339
12340 @item @emph{See also}:
12341 @ref{LCOBOUND}, @ref{LBOUND}
12342 @end table
12343
12344
12345
12346 @node UMASK
12347 @section @code{UMASK} --- Set the file creation mask
12348 @fnindex UMASK
12349 @cindex file system, file creation mask
12350
12351 @table @asis
12352 @item @emph{Description}:
12353 Sets the file creation mask to @var{MASK}. If called as a function, it
12354 returns the old value. If called as a subroutine and argument @var{OLD}
12355 if it is supplied, it is set to the old value. See @code{umask(2)}.
12356
12357 @item @emph{Standard}:
12358 GNU extension
12359
12360 @item @emph{Class}:
12361 Subroutine, function
12362
12363 @item @emph{Syntax}:
12364 @multitable @columnfractions .80
12365 @item @code{CALL UMASK(MASK [, OLD])}
12366 @item @code{OLD = UMASK(MASK)}
12367 @end multitable
12368
12369 @item @emph{Arguments}:
12370 @multitable @columnfractions .15 .70
12371 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12372 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12373 @code{INTEGER}.
12374 @end multitable
12375
12376 @end table
12377
12378
12379
12380 @node UNLINK
12381 @section @code{UNLINK} --- Remove a file from the file system
12382 @fnindex UNLINK
12383 @cindex file system, remove file
12384
12385 @table @asis
12386 @item @emph{Description}:
12387 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12388 used to mark the end of the name in @var{PATH}; otherwise, trailing
12389 blanks in the file name are ignored.  If the @var{STATUS} argument is
12390 supplied, it contains 0 on success or a nonzero error code upon return;
12391 see @code{unlink(2)}.
12392
12393 This intrinsic is provided in both subroutine and function forms;
12394 however, only one form can be used in any given program unit.
12395
12396 @item @emph{Standard}:
12397 GNU extension
12398
12399 @item @emph{Class}:
12400 Subroutine, function
12401
12402 @item @emph{Syntax}:
12403 @multitable @columnfractions .80
12404 @item @code{CALL UNLINK(PATH [, STATUS])}
12405 @item @code{STATUS = UNLINK(PATH)}
12406 @end multitable
12407
12408 @item @emph{Arguments}:
12409 @multitable @columnfractions .15 .70
12410 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12411 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12412 @end multitable
12413
12414 @item @emph{See also}:
12415 @ref{LINK}, @ref{SYMLNK}
12416 @end table
12417
12418
12419
12420 @node UNPACK
12421 @section @code{UNPACK} --- Unpack an array of rank one into an array
12422 @fnindex UNPACK
12423 @cindex array, unpacking
12424 @cindex array, increase dimension
12425 @cindex array, scatter elements
12426
12427 @table @asis
12428 @item @emph{Description}:
12429 Store the elements of @var{VECTOR} in an array of higher rank.
12430
12431 @item @emph{Standard}:
12432 Fortran 95 and later
12433
12434 @item @emph{Class}:
12435 Transformational function
12436
12437 @item @emph{Syntax}:
12438 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12439
12440 @item @emph{Arguments}:
12441 @multitable @columnfractions .15 .70
12442 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12443 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12444 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
12445 @item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
12446 the same shape as @var{MASK}.
12447 @end multitable
12448
12449 @item @emph{Return value}:
12450 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12451 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12452
12453 @item @emph{Example}:
12454 @smallexample
12455 PROGRAM test_unpack
12456   integer :: vector(2)  = (/1,1/)
12457   logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12458   integer :: field(2,2) = 0, unity(2,2)
12459
12460   ! result: unity matrix
12461   unity = unpack(vector, reshape(mask, (/2,2/)), field)
12462 END PROGRAM
12463 @end smallexample
12464
12465 @item @emph{See also}:
12466 @ref{PACK}, @ref{SPREAD}
12467 @end table
12468
12469
12470
12471 @node VERIFY
12472 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
12473 @fnindex VERIFY
12474 @cindex string, find missing set
12475
12476 @table @asis
12477 @item @emph{Description}:
12478 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
12479
12480 If @var{BACK} is either absent or equals @code{FALSE}, this function
12481 returns the position of the leftmost character of @var{STRING} that is
12482 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12483 is returned. If all characters of @var{SET} are found in @var{STRING}, the
12484 result is zero.
12485
12486 @item @emph{Standard}:
12487 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12488
12489 @item @emph{Class}:
12490 Elemental function
12491
12492 @item @emph{Syntax}:
12493 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12494
12495 @item @emph{Arguments}:
12496 @multitable @columnfractions .15 .70
12497 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12498 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
12499 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
12500 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
12501 expression indicating the kind parameter of the result.
12502 @end multitable
12503
12504 @item @emph{Return value}:
12505 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12506 @var{KIND} is absent, the return value is of default integer kind.
12507
12508 @item @emph{Example}:
12509 @smallexample
12510 PROGRAM test_verify
12511   WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
12512   WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
12513   WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
12514   WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
12515   WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
12516 END PROGRAM
12517 @end smallexample
12518
12519 @item @emph{See also}:
12520 @ref{SCAN}, @ref{INDEX intrinsic}
12521 @end table
12522
12523
12524
12525 @node XOR
12526 @section @code{XOR} --- Bitwise logical exclusive OR
12527 @fnindex XOR
12528 @cindex bitwise logical exclusive or
12529 @cindex logical exclusive or, bitwise
12530
12531 @table @asis
12532 @item @emph{Description}:
12533 Bitwise logical exclusive or.
12534
12535 This intrinsic routine is provided for backwards compatibility with
12536 GNU Fortran 77.  For integer arguments, programmers should consider
12537 the use of the @ref{IEOR} intrinsic and for logical arguments the
12538 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12539
12540 @item @emph{Standard}:
12541 GNU extension
12542
12543 @item @emph{Class}:
12544 Function
12545
12546 @item @emph{Syntax}:
12547 @code{RESULT = XOR(I, J)}
12548
12549 @item @emph{Arguments}:
12550 @multitable @columnfractions .15 .70
12551 @item @var{I} @tab The type shall be either  a scalar @code{INTEGER}
12552 type or a scalar @code{LOGICAL} type.
12553 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12554 @end multitable
12555
12556 @item @emph{Return value}:
12557 The return type is either a scalar @code{INTEGER} or a scalar
12558 @code{LOGICAL}.  If the kind type parameters differ, then the
12559 smaller kind type is implicitly converted to larger kind, and the
12560 return has the larger kind.
12561
12562 @item @emph{Example}:
12563 @smallexample
12564 PROGRAM test_xor
12565   LOGICAL :: T = .TRUE., F = .FALSE.
12566   INTEGER :: a, b
12567   DATA a / Z'F' /, b / Z'3' /
12568
12569   WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12570   WRITE (*,*) XOR(a, b)
12571 END PROGRAM
12572 @end smallexample
12573
12574 @item @emph{See also}:
12575 Fortran 95 elemental function: @ref{IEOR}
12576 @end table
12577
12578
12579
12580 @node Intrinsic Modules
12581 @chapter Intrinsic Modules
12582 @cindex intrinsic Modules
12583
12584 @menu
12585 * ISO_FORTRAN_ENV::
12586 * ISO_C_BINDING::
12587 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12588 @end menu
12589
12590 @node ISO_FORTRAN_ENV
12591 @section @code{ISO_FORTRAN_ENV}
12592 @table @asis
12593 @item @emph{Standard}:
12594 Fortran 2003 and later, except when otherwise noted
12595 @end table
12596
12597 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12598 named constants:
12599
12600 @table @asis
12601 @item @code{ATOMIC_INT_KIND}:
12602 Default-kind integer constant to be used as kind parameter when defining
12603 integer variables used in atomic operations. (Fortran 2008 or later.)
12604
12605 @item @code{ATOMIC_LOGICAL_KIND}:
12606 Default-kind integer constant to be used as kind parameter when defining
12607 logical variables used in atomic operations. (Fortran 2008 or later.)
12608
12609 @item @code{CHARACTER_STORAGE_SIZE}:
12610 Size in bits of the character storage unit.
12611
12612 @item @code{ERROR_UNIT}:
12613 Identifies the preconnected unit used for error reporting.
12614
12615 @item @code{FILE_STORAGE_SIZE}:
12616 Size in bits of the file-storage unit.
12617
12618 @item @code{INPUT_UNIT}:
12619 Identifies the preconnected unit identified by the asterisk
12620 (@code{*}) in @code{READ} statement.
12621
12622 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12623 Kind type parameters to specify an INTEGER type with a storage
12624 size of 16, 32, and 64 bits. It is negative if a target platform
12625 does not support the particular kind. (Fortran 2008 or later.)
12626
12627 @item @code{IOSTAT_END}:
12628 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12629 an input/output statement if an end-of-file condition occurred.
12630
12631 @item @code{IOSTAT_EOR}:
12632 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12633 an input/output statement if an end-of-record condition occurred.
12634
12635 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12636 Scalar default-integer constant, used by @code{INQUIRE} for the
12637 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12638 internal unit. (Fortran 2008 or later.)
12639
12640 @item @code{NUMERIC_STORAGE_SIZE}:
12641 The size in bits of the numeric storage unit.
12642
12643 @item @code{OUTPUT_UNIT}:
12644 Identifies the preconnected unit identified by the asterisk
12645 (@code{*}) in @code{WRITE} statement.
12646
12647 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12648 Kind type parameters to specify a REAL type with a storage
12649 size of 32, 64, and 128 bits. It is negative if a target platform
12650 does not support the particular kind. (Fortran 2008 or later.)
12651
12652 @item @code{STAT_LOCKED}:
12653 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12654 denote that the lock variable is locked by the executing image. (Fortran 2008
12655 or later.)
12656
12657 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12658 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12659 denote that the lock variable is locked by another image. (Fortran 2008 or
12660 later.)
12661
12662 @item @code{STAT_STOPPED_IMAGE}:
12663 Positive, scalar default-integer constant used as STAT= return value if the
12664 argument in the statement requires synchronisation with an image, which has
12665 initiated the termination of the execution. (Fortran 2008 or later.)
12666
12667 @item @code{STAT_UNLOCKED}:
12668 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12669 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12670 @end table
12671
12672
12673
12674 @node ISO_C_BINDING
12675 @section @code{ISO_C_BINDING}
12676 @table @asis
12677 @item @emph{Standard}:
12678 Fortran 2003 and later, GNU extensions
12679 @end table
12680
12681 The following intrinsic procedures are provided by the module; their
12682 definition can be found in the section Intrinsic Procedures of this
12683 manual.
12684
12685 @table @asis
12686 @item @code{C_ASSOCIATED}
12687 @item @code{C_F_POINTER}
12688 @item @code{C_F_PROCPOINTER}
12689 @item @code{C_FUNLOC}
12690 @item @code{C_LOC}
12691 @end table
12692 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
12693 @c don't really know why.
12694
12695 The @code{ISO_C_BINDING} module provides the following named constants of
12696 type default integer, which can be used as KIND type parameters.
12697
12698 In addition to the integer named constants required by the Fortran 2003
12699 standard, GNU Fortran provides as an extension named constants for the
12700 128-bit integer types supported by the C compiler: @code{C_INT128_T,
12701 C_INT_LEAST128_T, C_INT_FAST128_T}.
12702
12703 @multitable @columnfractions .15 .35 .35 .35
12704 @item Fortran Type  @tab Named constant         @tab C type                                @tab Extension
12705 @item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
12706 @item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
12707 @item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
12708 @item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
12709 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
12710 @item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
12711 @item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
12712 @item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
12713 @item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
12714 @item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
12715 @item @code{INTEGER}@tab @code{C_INT128_T}      @tab @code{int128_t}                      @tab Ext.
12716 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
12717 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
12718 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
12719 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
12720 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t}                @tab Ext.
12721 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}   @tab @code{int_fast8_t}
12722 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}  @tab @code{int_fast16_t}
12723 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}  @tab @code{int_fast32_t}
12724 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}  @tab @code{int_fast64_t}
12725 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t}                 @tab Ext.
12726 @item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
12727 @item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
12728 @item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
12729 @item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
12730 @item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
12731 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
12732 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
12733 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
12734 @item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
12735 @item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
12736 @end multitable
12737
12738 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
12739 are defined.
12740
12741 @multitable @columnfractions .20 .45 .15
12742 @item Name                     @tab C definition    @tab Value
12743 @item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
12744 @item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
12745 @item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
12746 @item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
12747 @item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
12748 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
12749 @item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
12750 @item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
12751 @end multitable
12752
12753 Moreover, the following two named constants are defined:
12754
12755 @multitable @columnfractions .20 .80
12756 @item Name                 @tab Type
12757 @item @code{C_NULL_PTR}    @tab @code{C_PTR}
12758 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
12759 @end multitable
12760
12761 Both are equivalent to the value @code{NULL} in C.
12762
12763 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
12764 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
12765 @table @asis
12766 @item @emph{Standard}:
12767 OpenMP Application Program Interface v3.0
12768 @end table
12769
12770
12771 The OpenMP Fortran runtime library routines are provided both in
12772 a form of two Fortran 90 modules, named @code{OMP_LIB} and
12773 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
12774 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
12775 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
12776 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
12777 below.
12778
12779 For details refer to the actual
12780 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
12781 OpenMP Application Program Interface v3.0}.
12782
12783 @code{OMP_LIB_KINDS} provides the following scalar default-integer
12784 named constants:
12785
12786 @table @asis
12787 @item @code{omp_integer_kind}
12788 @item @code{omp_logical_kind}
12789 @item @code{omp_lock_kind}
12790 @item @code{omp_nest_lock_kind}
12791 @item @code{omp_sched_kind}
12792 @end table