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