gcc/fortran/intrinsic.texi

   1 @ignore
   2 Copyright (C) 2005, 2006, 2007, 2008
   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.2 or
   9 any later version published by the Free Software Foundation; with the
  10 Invariant Sections being ``GNU General Public License'' and ``Funding
  11 Free Software'', the Front-Cover texts being (a) (see below), and with
  12 the Back-Cover Texts being (b) (see below).  A copy of the license is
  13 included in the gfdl(7) man page.
  14
  15
  16 Some basic guidelines for editing this document:
  17
  18   (1) The intrinsic procedures are to be listed in alphabetical order.
  19   (2) The generic name is to be used.
  20   (3) The specific names are included in the function index and in a
  21       table at the end of the node (See ABS entry).
  22   (4) Try to maintain the same style for each entry.
  23
  24
  25 @end ignore
  26
  27 @tex
  28 \gdef\acos{\mathop{\rm acos}\nolimits}
  29 \gdef\asin{\mathop{\rm asin}\nolimits}
  30 \gdef\atan{\mathop{\rm atan}\nolimits}
  31 \gdef\acosh{\mathop{\rm acosh}\nolimits}
  32 \gdef\asinh{\mathop{\rm asinh}\nolimits}
  33 \gdef\atanh{\mathop{\rm atanh}\nolimits}
  34 @end tex
  35
  36
  37 @node Intrinsic Procedures
  38 @chapter Intrinsic Procedures
  39 @cindex intrinsic procedures
  40
  41 @menu
  42 * Introduction:         Introduction to Intrinsics
  43 * @code{ABORT}:         ABORT,     Abort the program
  44 * @code{ABS}:           ABS,       Absolute value
  45 * @code{ACCESS}:        ACCESS,    Checks file access modes
  46 * @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
  47 * @code{ACOS}:          ACOS,      Arccosine function
  48 * @code{ACOSH}:         ACOSH,     Hyperbolic arccosine function
  49 * @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
  50 * @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
  51 * @code{AIMAG}:         AIMAG,     Imaginary part of complex number
  52 * @code{AINT}:          AINT,      Truncate to a whole number
  53 * @code{ALARM}:         ALARM,     Set an alarm clock
  54 * @code{ALL}:           ALL,       Determine if all values are true
  55 * @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
  56 * @code{AND}:           AND,       Bitwise logical AND
  57 * @code{ANINT}:         ANINT,     Nearest whole number
  58 * @code{ANY}:           ANY,       Determine if any values are true
  59 * @code{ASIN}:          ASIN,      Arcsine function
  60 * @code{ASINH}:         ASINH,     Hyperbolic arcsine function
  61 * @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
  62 * @code{ATAN}:          ATAN,      Arctangent function
  63 * @code{ATAN2}:         ATAN2,     Arctangent function
  64 * @code{ATANH}:         ATANH,     Hyperbolic arctangent function
  65 * @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
  66 * @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
  67 * @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
  68 * @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
  69 * @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
  70 * @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
  71 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
  72 * @code{BTEST}:         BTEST,     Bit test function
  73 * @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
  74 * @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
  75 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
  76 * @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
  77 * @code{C_LOC}:         C_LOC,     Obtain the C address of an object
  78 * @code{C_SIZEOF}:      C_SIZEOF,  Size in bytes of an expression
  79 * @code{CEILING}:       CEILING,   Integer ceiling function
  80 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
  81 * @code{CHDIR}:         CHDIR,     Change working directory
  82 * @code{CHMOD}:         CHMOD,     Change access permissions of files
  83 * @code{CMPLX}:         CMPLX,     Complex conversion function
  84 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
  85 * @code{COMPLEX}:       COMPLEX,   Complex conversion function
  86 * @code{CONJG}:         CONJG,     Complex conjugate function
  87 * @code{COS}:           COS,       Cosine function
  88 * @code{COSH}:          COSH,      Hyperbolic cosine function
  89 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
  90 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
  91 * @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
  92 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
  93 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
  94 * @code{DBLE}:          DBLE,      Double precision conversion function
  95 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
  96 * @code{DFLOAT}:        DFLOAT,    Double precision conversion function
  97 * @code{DIGITS}:        DIGITS,    Significant digits function
  98 * @code{DIM}:           DIM,       Positive difference
  99 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
 100 * @code{DPROD}:         DPROD,     Double product function
 101 * @code{DREAL}:         DREAL,     Double real part function
 102 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
 103 * @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
 104 * @code{EPSILON}:       EPSILON,   Epsilon function
 105 * @code{ERF}:           ERF,       Error function
 106 * @code{ERFC}:          ERFC,      Complementary error function
 107 * @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
 108 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
 109 * @code{EXIT}:          EXIT,      Exit the program with status.
 110 * @code{EXP}:           EXP,       Exponential function
 111 * @code{EXPONENT}:      EXPONENT,  Exponent function
 112 * @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
 113 * @code{FGET}:          FGET,      Read a single character in stream mode from stdin
 114 * @code{FGETC}:         FGETC,     Read a single character in stream mode
 115 * @code{FLOAT}:         FLOAT,     Convert integer to default real
 116 * @code{FLOOR}:         FLOOR,     Integer floor function
 117 * @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
 118 * @code{FNUM}:          FNUM,      File number function
 119 * @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
 120 * @code{FPUTC}:         FPUTC,     Write a single character in stream mode
 121 * @code{FRACTION}:      FRACTION,  Fractional part of the model representation
 122 * @code{FREE}:          FREE,      Memory de-allocation subroutine
 123 * @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
 124 * @code{FSTAT}:         FSTAT,     Get file status
 125 * @code{FTELL}:         FTELL,     Current stream position
 126 * @code{GAMMA}:         GAMMA,     Gamma function
 127 * @code{GERROR}:        GERROR,    Get last system error message
 128 * @code{GETARG}:        GETARG,    Get command line arguments
 129 * @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
 130 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
 131 * @code{GETCWD}:        GETCWD,    Get current working directory
 132 * @code{GETENV}:        GETENV,    Get an environmental variable
 133 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
 134 * @code{GETGID}:        GETGID,    Group ID function
 135 * @code{GETLOG}:        GETLOG,    Get login name
 136 * @code{GETPID}:        GETPID,    Process ID function
 137 * @code{GETUID}:        GETUID,    User ID function
 138 * @code{GMTIME}:        GMTIME,    Convert time to GMT info
 139 * @code{HOSTNM}:        HOSTNM,    Get system host name
 140 * @code{HUGE}:          HUGE,      Largest number of a kind
 141 * @code{HYPOT}:         HYPOT,     Euclidian distance function
 142 * @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
 143 * @code{IAND}:          IAND,      Bitwise logical and
 144 * @code{IARGC}:         IARGC,     Get the number of command line arguments
 145 * @code{IBCLR}:         IBCLR,     Clear bit
 146 * @code{IBITS}:         IBITS,     Bit extraction
 147 * @code{IBSET}:         IBSET,     Set bit
 148 * @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
 149 * @code{IDATE}:         IDATE,     Current local time (day/month/year)
 150 * @code{IEOR}:          IEOR,      Bitwise logical exclusive or
 151 * @code{IERRNO}:        IERRNO,    Function to get the last system error number
 152 * @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
 153 * @code{INT}:           INT,       Convert to integer type
 154 * @code{INT2}:          INT2,      Convert to 16-bit integer type
 155 * @code{INT8}:          INT8,      Convert to 64-bit integer type
 156 * @code{IOR}:           IOR,       Bitwise logical or
 157 * @code{IRAND}:         IRAND,     Integer pseudo-random number
 158 * @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
 159 * @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
 160 * @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
 161 * @code{ISHFT}:         ISHFT,     Shift bits
 162 * @code{ISHFTC}:        ISHFTC,    Shift bits circularly
 163 * @code{ISNAN}:         ISNAN,     Tests for a NaN
 164 * @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
 165 * @code{KILL}:          KILL,      Send a signal to a process
 166 * @code{KIND}:          KIND,      Kind of an entity
 167 * @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
 168 * @code{LEN}:           LEN,       Length of a character entity
 169 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
 170 * @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
 171 * @code{LGE}:           LGE,       Lexical greater than or equal
 172 * @code{LGT}:           LGT,       Lexical greater than
 173 * @code{LINK}:          LINK,      Create a hard link
 174 * @code{LLE}:           LLE,       Lexical less than or equal
 175 * @code{LLT}:           LLT,       Lexical less than
 176 * @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
 177 * @code{LOC}:           LOC,       Returns the address of a variable
 178 * @code{LOG}:           LOG,       Logarithm function
 179 * @code{LOG10}:         LOG10,     Base 10 logarithm function
 180 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
 181 * @code{LONG}:          LONG,      Convert to integer type
 182 * @code{LSHIFT}:        LSHIFT,    Left shift bits
 183 * @code{LSTAT}:         LSTAT,     Get file status
 184 * @code{LTIME}:         LTIME,     Convert time to local time info
 185 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
 186 * @code{MATMUL}:        MATMUL,    matrix multiplication
 187 * @code{MAX}:           MAX,       Maximum value of an argument list
 188 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
 189 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
 190 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
 191 * @code{MCLOCK}:        MCLOCK,    Time function
 192 * @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
 193 * @code{MERGE}:         MERGE,     Merge arrays
 194 * @code{MIN}:           MIN,       Minimum value of an argument list
 195 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
 196 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
 197 * @code{MINVAL}:        MINVAL,    Minimum value of an array
 198 * @code{MOD}:           MOD,       Remainder function
 199 * @code{MODULO}:        MODULO,    Modulo function
 200 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
 201 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
 202 * @code{NEAREST}:       NEAREST,   Nearest representable number
 203 * @code{NEW_LINE}:      NEW_LINE,  New line character
 204 * @code{NINT}:          NINT,      Nearest whole number
 205 * @code{NOT}:           NOT,       Logical negation
 206 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
 207 * @code{OR}:            OR,        Bitwise logical OR
 208 * @code{PACK}:          PACK,      Pack an array into an array of rank one
 209 * @code{PERROR}:        PERROR,    Print system error message
 210 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
 211 * @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
 212 * @code{PRODUCT}:       PRODUCT,   Product of array elements
 213 * @code{RADIX}:         RADIX,     Base of a data model
 214 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
 215 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
 216 * @code{RAND}:          RAND,      Real pseudo-random number
 217 * @code{RANGE}:         RANGE,     Decimal exponent range of a real kind
 218 * @code{RAN}:           RAN,       Real pseudo-random number
 219 * @code{REAL}:          REAL,      Convert to real type
 220 * @code{RENAME}:        RENAME,    Rename a file
 221 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
 222 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
 223 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
 224 * @code{RSHIFT}:        RSHIFT,    Right shift bits
 225 * @code{SCALE}:         SCALE,     Scale a real value
 226 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
 227 * @code{SECNDS}:        SECNDS,    Time function
 228 * @code{SECOND}:        SECOND,    CPU time function
 229 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
 230 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
 231 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
 232 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
 233 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
 234 * @code{SIGN}:          SIGN,      Sign copying function
 235 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
 236 * @code{SIN}:           SIN,       Sine function
 237 * @code{SINH}:          SINH,      Hyperbolic sine function
 238 * @code{SIZE}:          SIZE,      Function to determine the size of an array
 239 * @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
 240 * @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
 241 * @code{SNGL}:          SNGL,      Convert double precision real to default real
 242 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
 243 * @code{SPREAD}:        SPREAD,    Add a dimension to an array
 244 * @code{SQRT}:          SQRT,      Square-root function
 245 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
 246 * @code{STAT}:          STAT,      Get file status
 247 * @code{SUM}:           SUM,       Sum of array elements
 248 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
 249 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
 250 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
 251 * @code{TAN}:           TAN,       Tangent function
 252 * @code{TANH}:          TANH,      Hyperbolic tangent function
 253 * @code{TIME}:          TIME,      Time function
 254 * @code{TIME8}:         TIME8,     Time function (64-bit)
 255 * @code{TINY}:          TINY,      Smallest positive number of a real kind
 256 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
 257 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
 258 * @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
 259 * @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
 260 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
 261 * @code{UMASK}:         UMASK,     Set the file creation mask
 262 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
 263 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
 264 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
 265 * @code{XOR}:           XOR,       Bitwise logical exclusive or
 266 @end menu
 267
 268 @node Introduction to Intrinsics
 269 @section Introduction to intrinsic procedures
 270
 271 The intrinsic procedures provided by GNU Fortran include all of the
 272 intrinsic procedures required by the Fortran 95 standard, a set of
 273 intrinsic procedures for backwards compatibility with G77, and a
 274 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
 275 standards.  Any conflict between a description here and a description in
 276 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
 277 2008 standard is unintentional, and the standard(s) should be considered
 278 authoritative.
 279
 280 The enumeration of the @code{KIND} type parameter is processor defined in
 281 the Fortran 95 standard.  GNU Fortran defines the default integer type and
 282 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 283 respectively.  The standard mandates that both data types shall have
 284 another kind, which have more precision.  On typical target architectures
 285 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 286 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 287 In the description of generic intrinsic procedures, the kind type parameter
 288 will be specified by @code{KIND=*}, and in the description of specific
 289 names for an intrinsic procedure the kind type parameter will be explicitly
 290 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
 291 brevity the optional @code{KIND=} syntax will be omitted.
 292
 293 Many of the intrinsic procedures take one or more optional arguments.
 294 This document follows the convention used in the Fortran 95 standard,
 295 and denotes such arguments by square brackets.
 296
 297 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
 298 which can be used to restrict the set of intrinsic procedures to a
 299 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
 300 option, and so all intrinsic procedures described here are accepted.  There
 301 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 302 implemented both a function and a subroutine.  Both classes
 303 have been implemented in @command{gfortran} for backwards compatibility
 304 with @command{g77}.  It is noted here that these functions and subroutines
 305 cannot be intermixed in a given subprogram.  In the descriptions that follow,
 306 the applicable standard for each intrinsic procedure is noted.
 307
 308
 309
 310 @node ABORT
 311 @section @code{ABORT} --- Abort the program
 312 @fnindex ABORT
 313 @cindex program termination, with core dump
 314 @cindex terminate program, with core dump
 315 @cindex core, dump
 316
 317 @table @asis
 318 @item @emph{Description}:
 319 @code{ABORT} causes immediate termination of the program.  On operating
 320 systems that support a core dump, @code{ABORT} will produce a core dump,
 321 which is suitable for debugging purposes.
 322
 323 @item @emph{Standard}:
 324 GNU extension
 325
 326 @item @emph{Class}:
 327 Subroutine
 328
 329 @item @emph{Syntax}:
 330 @code{CALL ABORT}
 331
 332 @item @emph{Return value}:
 333 Does not return.
 334
 335 @item @emph{Example}:
 336 @smallexample
 337 program test_abort
 338   integer :: i = 1, j = 2
 339   if (i /= j) call abort
 340 end program test_abort
 341 @end smallexample
 342
 343 @item @emph{See also}:
 344 @ref{EXIT}, @ref{KILL}
 345
 346 @end table
 347
 348
 349
 350 @node ABS
 351 @section @code{ABS} --- Absolute value
 352 @fnindex ABS
 353 @fnindex CABS
 354 @fnindex DABS
 355 @fnindex IABS
 356 @fnindex ZABS
 357 @fnindex CDABS
 358 @cindex absolute value
 359
 360 @table @asis
 361 @item @emph{Description}:
 362 @code{ABS(A)} computes the absolute value of @code{A}.
 363
 364 @item @emph{Standard}:
 365 Fortran 77 and later, has overloads that are GNU extensions
 366
 367 @item @emph{Class}:
 368 Elemental function
 369
 370 @item @emph{Syntax}:
 371 @code{RESULT = ABS(A)}
 372
 373 @item @emph{Arguments}:
 374 @multitable @columnfractions .15 .70
 375 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
 376 @code{REAL}, or @code{COMPLEX}.
 377 @end multitable
 378
 379 @item @emph{Return value}:
 380 The return value is of the same type and
 381 kind as the argument except the return value is @code{REAL} for a
 382 @code{COMPLEX} argument.
 383
 384 @item @emph{Example}:
 385 @smallexample
 386 program test_abs
 387   integer :: i = -1
 388   real :: x = -1.e0
 389   complex :: z = (-1.e0,0.e0)
 390   i = abs(i)
 391   x = abs(x)
 392   x = abs(z)
 393 end program test_abs
 394 @end smallexample
 395
 396 @item @emph{Specific names}:
 397 @multitable @columnfractions .20 .20 .20 .25
 398 @item Name            @tab Argument            @tab Return type       @tab Standard
 399 @item @code{CABS(A)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab Fortran 77 and later
 400 @item @code{DABS(A)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}    @tab Fortran 77 and later
 401 @item @code{IABS(A)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
 402 @item @code{ZABS(A)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
 403 @item @code{CDABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
 404 @end multitable
 405 @end table
 406
 407
 408
 409 @node ACCESS
 410 @section @code{ACCESS} --- Checks file access modes
 411 @fnindex ACCESS
 412 @cindex file system, access mode
 413
 414 @table @asis
 415 @item @emph{Description}:
 416 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
 417 exists, is readable, writable or executable. Except for the
 418 executable check, @code{ACCESS} can be replaced by
 419 Fortran 95's @code{INQUIRE}.
 420
 421 @item @emph{Standard}:
 422 GNU extension
 423
 424 @item @emph{Class}:
 425 Inquiry function
 426
 427 @item @emph{Syntax}:
 428 @code{RESULT = ACCESS(NAME, MODE)}
 429
 430 @item @emph{Arguments}:
 431 @multitable @columnfractions .15 .70
 432 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
 433 file name. Tailing blank are ignored unless the character @code{achar(0)}
 434 is present, then all characters up to and excluding @code{achar(0)} are
 435 used as file name.
 436 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
 437 file access mode, may be any concatenation of @code{"r"} (readable),
 438 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
 439 for existence.
 440 @end multitable
 441
 442 @item @emph{Return value}:
 443 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
 444 accessible in the given mode; otherwise or if an invalid argument
 445 has been given for @code{MODE} the value @code{1} is returned.
 446
 447 @item @emph{Example}:
 448 @smallexample
 449 program access_test
 450   implicit none
 451   character(len=*), parameter :: file  = 'test.dat'
 452   character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
 453   if(access(file,' ') == 0) print *, trim(file),' is exists'
 454   if(access(file,'r') == 0) print *, trim(file),' is readable'
 455   if(access(file,'w') == 0) print *, trim(file),' is writable'
 456   if(access(file,'x') == 0) print *, trim(file),' is executable'
 457   if(access(file2,'rwx') == 0) &
 458     print *, trim(file2),' is readable, writable and executable'
 459 end program access_test
 460 @end smallexample
 461 @item @emph{Specific names}:
 462 @item @emph{See also}:
 463
 464 @end table
 465
 466
 467
 468 @node ACHAR
 469 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
 470 @fnindex ACHAR
 471 @cindex @acronym{ASCII} collating sequence
 472 @cindex collating sequence, @acronym{ASCII}
 473
 474 @table @asis
 475 @item @emph{Description}:
 476 @code{ACHAR(I)} returns the character located at position @code{I}
 477 in the @acronym{ASCII} collating sequence.
 478
 479 @item @emph{Standard}:
 480 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
 481
 482 @item @emph{Class}:
 483 Elemental function
 484
 485 @item @emph{Syntax}:
 486 @code{RESULT = ACHAR(I [, KIND])}
 487
 488 @item @emph{Arguments}:
 489 @multitable @columnfractions .15 .70
 490 @item @var{I}    @tab The type shall be @code{INTEGER}.
 491 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 492 expression indicating the kind parameter of the result.
 493 @end multitable
 494
 495 @item @emph{Return value}:
 496 The return value is of type @code{CHARACTER} with a length of one.
 497 If the @var{KIND} argument is present, the return value is of the
 498 specified kind and of the default kind otherwise.
 499
 500 @item @emph{Example}:
 501 @smallexample
 502 program test_achar
 503   character c
 504   c = achar(32)
 505 end program test_achar
 506 @end smallexample
 507
 508 @item @emph{Note}:
 509 See @ref{ICHAR} for a discussion of converting between numerical values
 510 and formatted string representations.
 511
 512 @item @emph{See also}:
 513 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
 514
 515 @end table
 516
 517
 518
 519 @node ACOS
 520 @section @code{ACOS} --- Arccosine function
 521 @fnindex ACOS
 522 @fnindex DACOS
 523 @cindex trigonometric function, cosine, inverse
 524 @cindex cosine, inverse
 525
 526 @table @asis
 527 @item @emph{Description}:
 528 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
 529
 530 @item @emph{Standard}:
 531 Fortran 77 and later
 532
 533 @item @emph{Class}:
 534 Elemental function
 535
 536 @item @emph{Syntax}:
 537 @code{RESULT = ACOS(X)}
 538
 539 @item @emph{Arguments}:
 540 @multitable @columnfractions .15 .70
 541 @item @var{X} @tab The type shall be @code{REAL} with a magnitude that is
 542 less than one.
 543 @end multitable
 544
 545 @item @emph{Return value}:
 546 The return value is of type @code{REAL} and it lies in the
 547 range @math{ 0 \leq \acos(x) \leq \pi}. The return value if of the same
 548 kind as @var{X}.
 549
 550 @item @emph{Example}:
 551 @smallexample
 552 program test_acos
 553   real(8) :: x = 0.866_8
 554   x = acos(x)
 555 end program test_acos
 556 @end smallexample
 557
 558 @item @emph{Specific names}:
 559 @multitable @columnfractions .20 .20 .20 .25
 560 @item Name            @tab Argument          @tab Return type       @tab Standard
 561 @item @code{DACOS(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
 562 @end multitable
 563
 564 @item @emph{See also}:
 565 Inverse function: @ref{COS}
 566
 567 @end table
 568
 569
 570
 571 @node ACOSH
 572 @section @code{ACOSH} --- Hyperbolic arccosine function
 573 @fnindex ACOSH
 574 @fnindex DACOSH
 575 @cindex area hyperbolic cosine
 576 @cindex hyperbolic arccosine
 577 @cindex hyperbolic function, cosine, inverse
 578 @cindex cosine, hyperbolic, inverse
 579
 580 @table @asis
 581 @item @emph{Description}:
 582 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
 583 @code{COSH(X)}).
 584
 585 @item @emph{Standard}:
 586 Fortran 2008 and later
 587
 588 @item @emph{Class}:
 589 Elemental function
 590
 591 @item @emph{Syntax}:
 592 @code{RESULT = ACOSH(X)}
 593
 594 @item @emph{Arguments}:
 595 @multitable @columnfractions .15 .70
 596 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
 597 @end multitable
 598
 599 @item @emph{Return value}:
 600 The return value has the same type and kind as @var{X}
 601
 602 @item @emph{Example}:
 603 @smallexample
 604 PROGRAM test_acosh
 605   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
 606   WRITE (*,*) ACOSH(x)
 607 END PROGRAM
 608 @end smallexample
 609
 610 @item @emph{Specific names}:
 611 @multitable @columnfractions .20 .20 .20 .25
 612 @item Name             @tab Argument          @tab Return type       @tab Standard
 613 @item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
 614 @end multitable
 615
 616 @item @emph{See also}:
 617 Inverse function: @ref{COSH}
 618 @end table
 619
 620
 621
 622 @node ADJUSTL
 623 @section @code{ADJUSTL} --- Left adjust a string
 624 @fnindex ADJUSTL
 625 @cindex string, adjust left
 626 @cindex adjust string
 627
 628 @table @asis
 629 @item @emph{Description}:
 630 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
 631 Spaces are inserted at the end of the string as needed.
 632
 633 @item @emph{Standard}:
 634 Fortran 95 and later
 635
 636 @item @emph{Class}:
 637 Elemental function
 638
 639 @item @emph{Syntax}:
 640 @code{RESULT = ADJUSTL(STRING)}
 641
 642 @item @emph{Arguments}:
 643 @multitable @columnfractions .15 .70
 644 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
 645 @end multitable
 646
 647 @item @emph{Return value}:
 648 The return value is of type @code{CHARACTER} and of the same kind as
 649 @var{STRING} where leading spaces are removed and the same number of
 650 spaces are inserted on the end of @var{STRING}.
 651
 652 @item @emph{Example}:
 653 @smallexample
 654 program test_adjustl
 655   character(len=20) :: str = '   gfortran'
 656   str = adjustl(str)
 657   print *, str
 658 end program test_adjustl
 659 @end smallexample
 660
 661 @item @emph{See also}:
 662 @ref{ADJUSTR}, @ref{TRIM}
 663 @end table
 664
 665
 666
 667 @node ADJUSTR
 668 @section @code{ADJUSTR} --- Right adjust a string
 669 @fnindex ADJUSTR
 670 @cindex string, adjust right
 671 @cindex adjust string
 672
 673 @table @asis
 674 @item @emph{Description}:
 675 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
 676 Spaces are inserted at the start of the string as needed.
 677
 678 @item @emph{Standard}:
 679 Fortran 95 and later
 680
 681 @item @emph{Class}:
 682 Elemental function
 683
 684 @item @emph{Syntax}:
 685 @code{RESULT = ADJUSTR(STRING)}
 686
 687 @item @emph{Arguments}:
 688 @multitable @columnfractions .15 .70
 689 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 690 @end multitable
 691
 692 @item @emph{Return value}:
 693 The return value is of type @code{CHARACTER} and of the same kind as
 694 @var{STRING} where trailing spaces are removed and the same number of
 695 spaces are inserted at the start of @var{STRING}.
 696
 697 @item @emph{Example}:
 698 @smallexample
 699 program test_adjustr
 700   character(len=20) :: str = 'gfortran'
 701   str = adjustr(str)
 702   print *, str
 703 end program test_adjustr
 704 @end smallexample
 705
 706 @item @emph{See also}:
 707 @ref{ADJUSTL}, @ref{TRIM}
 708 @end table
 709
 710
 711
 712 @node AIMAG
 713 @section @code{AIMAG} --- Imaginary part of complex number
 714 @fnindex AIMAG
 715 @fnindex DIMAG
 716 @fnindex IMAG
 717 @fnindex IMAGPART
 718 @cindex complex numbers, imaginary part
 719
 720 @table @asis
 721 @item @emph{Description}:
 722 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
 723 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
 724 for compatibility with @command{g77}, and their use in new code is
 725 strongly discouraged.
 726
 727 @item @emph{Standard}:
 728 Fortran 77 and later, has overloads that are GNU extensions
 729
 730 @item @emph{Class}:
 731 Elemental function
 732
 733 @item @emph{Syntax}:
 734 @code{RESULT = AIMAG(Z)}
 735
 736 @item @emph{Arguments}:
 737 @multitable @columnfractions .15 .70
 738 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
 739 @end multitable
 740
 741 @item @emph{Return value}:
 742 The return value is of type @code{REAL} with the
 743 kind type parameter of the argument.
 744
 745 @item @emph{Example}:
 746 @smallexample
 747 program test_aimag
 748   complex(4) z4
 749   complex(8) z8
 750   z4 = cmplx(1.e0_4, 0.e0_4)
 751   z8 = cmplx(0.e0_8, 1.e0_8)
 752   print *, aimag(z4), dimag(z8)
 753 end program test_aimag
 754 @end smallexample
 755
 756 @item @emph{Specific names}:
 757 @multitable @columnfractions .20 .20 .20 .25
 758 @item Name            @tab Argument            @tab Return type       @tab Standard
 759 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}    @tab GNU extension
 760 @item @code{IMAG(Z)}  @tab @code{COMPLEX Z} @tab @code{REAL}    @tab GNU extension
 761 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
 762 @end multitable
 763 @end table
 764
 765
 766
 767 @node AINT
 768 @section @code{AINT} --- Truncate to a whole number
 769 @fnindex AINT
 770 @fnindex DINT
 771 @cindex floor
 772 @cindex rounding, floor
 773
 774 @table @asis
 775 @item @emph{Description}:
 776 @code{AINT(A [, KIND])} truncates its argument to a whole number.
 777
 778 @item @emph{Standard}:
 779 Fortran 77 and later
 780
 781 @item @emph{Class}:
 782 Elemental function
 783
 784 @item @emph{Syntax}:
 785 @code{RESULT = AINT(A [, KIND])}
 786
 787 @item @emph{Arguments}:
 788 @multitable @columnfractions .15 .70
 789 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
 790 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 791 expression indicating the kind parameter of the result.
 792 @end multitable
 793
 794 @item @emph{Return value}:
 795 The return value is of type @code{REAL} with the kind type parameter of the
 796 argument if the optional @var{KIND} is absent; otherwise, the kind
 797 type parameter will be given by @var{KIND}.  If the magnitude of
 798 @var{X} is less than one, @code{AINT(X)} returns zero.  If the
 799 magnitude is equal to or greater than one then it returns the largest
 800 whole number that does not exceed its magnitude.  The sign is the same
 801 as the sign of @var{X}.
 802
 803 @item @emph{Example}:
 804 @smallexample
 805 program test_aint
 806   real(4) x4
 807   real(8) x8
 808   x4 = 1.234E0_4
 809   x8 = 4.321_8
 810   print *, aint(x4), dint(x8)
 811   x8 = aint(x4,8)
 812 end program test_aint
 813 @end smallexample
 814
 815 @item @emph{Specific names}:
 816 @multitable @columnfractions .20 .20 .20 .25
 817 @item Name           @tab Argument         @tab Return type      @tab Standard
 818 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab Fortran 77 and later
 819 @end multitable
 820 @end table
 821
 822
 823
 824 @node ALARM
 825 @section @code{ALARM} --- Execute a routine after a given delay
 826 @fnindex ALARM
 827 @cindex delayed execution
 828
 829 @table @asis
 830 @item @emph{Description}:
 831 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
 832 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
 833 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
 834 supplied, it will be returned with the number of seconds remaining until
 835 any previously scheduled alarm was due to be delivered, or zero if there
 836 was no previously scheduled alarm.
 837
 838 @item @emph{Standard}:
 839 GNU extension
 840
 841 @item @emph{Class}:
 842 Subroutine
 843
 844 @item @emph{Syntax}:
 845 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
 846
 847 @item @emph{Arguments}:
 848 @multitable @columnfractions .15 .70
 849 @item @var{SECONDS} @tab The type of the argument shall be a scalar
 850 @code{INTEGER}. It is @code{INTENT(IN)}.
 851 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
 852 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
 853 values may be either @code{SIG_IGN=1} to ignore the alarm generated
 854 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
 855 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
 856 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
 857 @end multitable
 858
 859 @item @emph{Example}:
 860 @smallexample
 861 program test_alarm
 862   external handler_print
 863   integer i
 864   call alarm (3, handler_print, i)
 865   print *, i
 866   call sleep(10)
 867 end program test_alarm
 868 @end smallexample
 869 This will cause the external routine @var{handler_print} to be called
 870 after 3 seconds.
 871 @end table
 872
 873
 874
 875 @node ALL
 876 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
 877 @fnindex ALL
 878 @cindex array, apply condition
 879 @cindex array, condition testing
 880
 881 @table @asis
 882 @item @emph{Description}:
 883 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
 884 in the array along dimension @var{DIM}.
 885
 886 @item @emph{Standard}:
 887 Fortran 95 and later
 888
 889 @item @emph{Class}:
 890 Transformational function
 891
 892 @item @emph{Syntax}:
 893 @code{RESULT = ALL(MASK [, DIM])}
 894
 895 @item @emph{Arguments}:
 896 @multitable @columnfractions .15 .70
 897 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
 898 it shall not be scalar.
 899 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
 900 with a value that lies between one and the rank of @var{MASK}.
 901 @end multitable
 902
 903 @item @emph{Return value}:
 904 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
 905 the kind type parameter is the same as the kind type parameter of
 906 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
 907 an array with the rank of @var{MASK} minus 1.  The shape is determined from
 908 the shape of @var{MASK} where the @var{DIM} dimension is elided.
 909
 910 @table @asis
 911 @item (A)
 912 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
 913 It also is true if @var{MASK} has zero size; otherwise, it is false.
 914 @item (B)
 915 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
 916 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
 917 is determined by applying @code{ALL} to the array sections.
 918 @end table
 919
 920 @item @emph{Example}:
 921 @smallexample
 922 program test_all
 923   logical l
 924   l = all((/.true., .true., .true./))
 925   print *, l
 926   call section
 927   contains
 928     subroutine section
 929       integer a(2,3), b(2,3)
 930       a = 1
 931       b = 1
 932       b(2,2) = 2
 933       print *, all(a .eq. b, 1)
 934       print *, all(a .eq. b, 2)
 935     end subroutine section
 936 end program test_all
 937 @end smallexample
 938 @end table
 939
 940
 941
 942 @node ALLOCATED
 943 @section @code{ALLOCATED} --- Status of an allocatable entity
 944 @fnindex ALLOCATED
 945 @cindex allocation, status
 946
 947 @table @asis
 948 @item @emph{Description}:
 949 @code{ALLOCATED(ARRAY)} checks the status of whether @var{X} is allocated.
 950
 951 @item @emph{Standard}:
 952 Fortran 95 and later
 953
 954 @item @emph{Class}:
 955 Inquiry function
 956
 957 @item @emph{Syntax}:
 958 @code{RESULT = ALLOCATED(ARRAY)}
 959
 960 @item @emph{Arguments}:
 961 @multitable @columnfractions .15 .70
 962 @item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
 963 @end multitable
 964
 965 @item @emph{Return value}:
 966 The return value is a scalar @code{LOGICAL} with the default logical
 967 kind type parameter.  If @var{ARRAY} is allocated, @code{ALLOCATED(ARRAY)}
 968 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
 969
 970 @item @emph{Example}:
 971 @smallexample
 972 program test_allocated
 973   integer :: i = 4
 974   real(4), allocatable :: x(:)
 975   if (allocated(x) .eqv. .false.) allocate(x(i))
 976 end program test_allocated
 977 @end smallexample
 978 @end table
 979
 980
 981
 982 @node AND
 983 @section @code{AND} --- Bitwise logical AND
 984 @fnindex AND
 985 @cindex bitwise logical and
 986 @cindex logical and, bitwise
 987
 988 @table @asis
 989 @item @emph{Description}:
 990 Bitwise logical @code{AND}.
 991
 992 This intrinsic routine is provided for backwards compatibility with
 993 GNU Fortran 77.  For integer arguments, programmers should consider
 994 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
 995
 996 @item @emph{Standard}:
 997 GNU extension
 998
 999 @item @emph{Class}:
1000 Function
1001
1002 @item @emph{Syntax}:
1003 @code{RESULT = AND(I, J)}
1004
1005 @item @emph{Arguments}:
1006 @multitable @columnfractions .15 .70
1007 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1008 type or a scalar @code{LOGICAL} type.
1009 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1010 @end multitable
1011
1012 @item @emph{Return value}:
1013 The return type is either a scalar @code{INTEGER} or a scalar
1014 @code{LOGICAL}.  If the kind type parameters differ, then the
1015 smaller kind type is implicitly converted to larger kind, and the
1016 return has the larger kind.
1017
1018 @item @emph{Example}:
1019 @smallexample
1020 PROGRAM test_and
1021   LOGICAL :: T = .TRUE., F = .FALSE.
1022   INTEGER :: a, b
1023   DATA a / Z'F' /, b / Z'3' /
1024
1025   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1026   WRITE (*,*) AND(a, b)
1027 END PROGRAM
1028 @end smallexample
1029
1030 @item @emph{See also}:
1031 Fortran 95 elemental function: @ref{IAND}
1032 @end table
1033
1034
1035
1036 @node ANINT
1037 @section @code{ANINT} --- Nearest whole number
1038 @fnindex ANINT
1039 @fnindex DNINT
1040 @cindex ceiling
1041 @cindex rounding, ceiling
1042
1043 @table @asis
1044 @item @emph{Description}:
1045 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1046
1047 @item @emph{Standard}:
1048 Fortran 77 and later
1049
1050 @item @emph{Class}:
1051 Elemental function
1052
1053 @item @emph{Syntax}:
1054 @code{RESULT = ANINT(A [, KIND])}
1055
1056 @item @emph{Arguments}:
1057 @multitable @columnfractions .15 .70
1058 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
1059 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1060 expression indicating the kind parameter of the result.
1061 @end multitable
1062
1063 @item @emph{Return value}:
1064 The return value is of type real with the kind type parameter of the
1065 argument if the optional @var{KIND} is absent; otherwise, the kind
1066 type parameter will be given by @var{KIND}.  If @var{A} is greater than
1067 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1068 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1069
1070 @item @emph{Example}:
1071 @smallexample
1072 program test_anint
1073   real(4) x4
1074   real(8) x8
1075   x4 = 1.234E0_4
1076   x8 = 4.321_8
1077   print *, anint(x4), dnint(x8)
1078   x8 = anint(x4,8)
1079 end program test_anint
1080 @end smallexample
1081
1082 @item @emph{Specific names}:
1083 @multitable @columnfractions .20 .20 .20 .25
1084 @item Name            @tab Argument         @tab Return type      @tab Standard
1085 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1086 @end multitable
1087 @end table
1088
1089
1090
1091 @node ANY
1092 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1093 @fnindex ANY
1094 @cindex array, apply condition
1095 @cindex array, condition testing
1096
1097 @table @asis
1098 @item @emph{Description}:
1099 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1100 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1101
1102 @item @emph{Standard}:
1103 Fortran 95 and later
1104
1105 @item @emph{Class}:
1106 Transformational function
1107
1108 @item @emph{Syntax}:
1109 @code{RESULT = ANY(MASK [, DIM])}
1110
1111 @item @emph{Arguments}:
1112 @multitable @columnfractions .15 .70
1113 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1114 it shall not be scalar.
1115 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1116 with a value that lies between one and the rank of @var{MASK}.
1117 @end multitable
1118
1119 @item @emph{Return value}:
1120 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1121 the kind type parameter is the same as the kind type parameter of
1122 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1123 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1124 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1125
1126 @table @asis
1127 @item (A)
1128 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1129 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1130 @item (B)
1131 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1132 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1133 is determined by applying @code{ANY} to the array sections.
1134 @end table
1135
1136 @item @emph{Example}:
1137 @smallexample
1138 program test_any
1139   logical l
1140   l = any((/.true., .true., .true./))
1141   print *, l
1142   call section
1143   contains
1144     subroutine section
1145       integer a(2,3), b(2,3)
1146       a = 1
1147       b = 1
1148       b(2,2) = 2
1149       print *, any(a .eq. b, 1)
1150       print *, any(a .eq. b, 2)
1151     end subroutine section
1152 end program test_any
1153 @end smallexample
1154 @end table
1155
1156
1157
1158 @node ASIN
1159 @section @code{ASIN} --- Arcsine function
1160 @fnindex ASIN
1161 @fnindex DASIN
1162 @cindex trigonometric function, sine, inverse
1163 @cindex sine, inverse
1164
1165 @table @asis
1166 @item @emph{Description}:
1167 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1168
1169 @item @emph{Standard}:
1170 Fortran 77 and later
1171
1172 @item @emph{Class}:
1173 Elemental function
1174
1175 @item @emph{Syntax}:
1176 @code{RESULT = ASIN(X)}
1177
1178 @item @emph{Arguments}:
1179 @multitable @columnfractions .15 .70
1180 @item @var{X} @tab The type shall be @code{REAL}, and a magnitude that is
1181 less than one.
1182 @end multitable
1183
1184 @item @emph{Return value}:
1185 The return value is of type @code{REAL} and it lies in the
1186 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}.  The kind type
1187 parameter is the same as @var{X}.
1188
1189 @item @emph{Example}:
1190 @smallexample
1191 program test_asin
1192   real(8) :: x = 0.866_8
1193   x = asin(x)
1194 end program test_asin
1195 @end smallexample
1196
1197 @item @emph{Specific names}:
1198 @multitable @columnfractions .20 .20 .20 .25
1199 @item Name            @tab Argument          @tab Return type       @tab Standard
1200 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1201 @end multitable
1202
1203 @item @emph{See also}:
1204 Inverse function: @ref{SIN}
1205
1206 @end table
1207
1208
1209
1210 @node ASINH
1211 @section @code{ASINH} --- Hyperbolic arcsine function
1212 @fnindex ASINH
1213 @fnindex DASINH
1214 @cindex area hyperbolic sine
1215 @cindex hyperbolic arcsine
1216 @cindex hyperbolic function, sine, inverse
1217 @cindex sine, hyperbolic, inverse
1218
1219 @table @asis
1220 @item @emph{Description}:
1221 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1222
1223 @item @emph{Standard}:
1224 Fortran 2008 and later
1225
1226 @item @emph{Class}:
1227 Elemental function
1228
1229 @item @emph{Syntax}:
1230 @code{RESULT = ASINH(X)}
1231
1232 @item @emph{Arguments}:
1233 @multitable @columnfractions .15 .70
1234 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1235 @end multitable
1236
1237 @item @emph{Return value}:
1238 The return value is of the same type and kind as  @var{X}.
1239
1240 @item @emph{Example}:
1241 @smallexample
1242 PROGRAM test_asinh
1243   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1244   WRITE (*,*) ASINH(x)
1245 END PROGRAM
1246 @end smallexample
1247
1248 @item @emph{Specific names}:
1249 @multitable @columnfractions .20 .20 .20 .25
1250 @item Name             @tab Argument          @tab Return type       @tab Standard
1251 @item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1252 @end multitable
1253
1254 @item @emph{See also}:
1255 Inverse function: @ref{SINH}
1256 @end table
1257
1258
1259
1260 @node ASSOCIATED
1261 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1262 @fnindex ASSOCIATED
1263 @cindex pointer, status
1264 @cindex association status
1265
1266 @table @asis
1267 @item @emph{Description}:
1268 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1269 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1270
1271 @item @emph{Standard}:
1272 Fortran 95 and later
1273
1274 @item @emph{Class}:
1275 Inquiry function
1276
1277 @item @emph{Syntax}:
1278 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1279
1280 @item @emph{Arguments}:
1281 @multitable @columnfractions .15 .70
1282 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1283 and it can be of any type.
1284 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1285 a target.  It must have the same type, kind type parameter, and
1286 array rank as @var{POINTER}.
1287 @end multitable
1288 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1289 undefined.
1290
1291 @item @emph{Return value}:
1292 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1293 There are several cases:
1294 @table @asis
1295 @item (A) When the optional @var{TARGET} is not present then
1296 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1297 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1298 @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
1299 disassociated, the result is false.
1300 @item (C) If @var{TARGET} is present and an array target, the result is true if
1301 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1302 are arrays whose elements are not zero-sized storage sequences, and
1303 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1304 order.
1305 As in case(B), the result is false, if @var{POINTER} is disassociated.
1306 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1307 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1308 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1309 units.
1310 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1311 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1312 target associated with @var{POINTER} and the target associated with @var{TARGET}
1313 have the same shape, are not zero-sized arrays, are arrays whose elements are
1314 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1315 the same storage units in array element order.
1316 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1317 @end table
1318
1319 @item @emph{Example}:
1320 @smallexample
1321 program test_associated
1322    implicit none
1323    real, target  :: tgt(2) = (/1., 2./)
1324    real, pointer :: ptr(:)
1325    ptr => tgt
1326    if (associated(ptr)     .eqv. .false.) call abort
1327    if (associated(ptr,tgt) .eqv. .false.) call abort
1328 end program test_associated
1329 @end smallexample
1330
1331 @item @emph{See also}:
1332 @ref{NULL}
1333 @end table
1334
1335
1336
1337 @node ATAN
1338 @section @code{ATAN} --- Arctangent function
1339 @fnindex ATAN
1340 @fnindex DATAN
1341 @cindex trigonometric function, tangent, inverse
1342 @cindex tangent, inverse
1343
1344 @table @asis
1345 @item @emph{Description}:
1346 @code{ATAN(X)} computes the arctangent of @var{X}.
1347
1348 @item @emph{Standard}:
1349 Fortran 77 and later
1350
1351 @item @emph{Class}:
1352 Elemental function
1353
1354 @item @emph{Syntax}:
1355 @code{RESULT = ATAN(X)}
1356
1357 @item @emph{Arguments}:
1358 @multitable @columnfractions .15 .70
1359 @item @var{X} @tab The type shall be @code{REAL}.
1360 @end multitable
1361
1362 @item @emph{Return value}:
1363 The return value is of type @code{REAL} and it lies in the
1364 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1365
1366 @item @emph{Example}:
1367 @smallexample
1368 program test_atan
1369   real(8) :: x = 2.866_8
1370   x = atan(x)
1371 end program test_atan
1372 @end smallexample
1373
1374 @item @emph{Specific names}:
1375 @multitable @columnfractions .20 .20 .20 .25
1376 @item Name            @tab Argument          @tab Return type       @tab Standard
1377 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1378 @end multitable
1379
1380 @item @emph{See also}:
1381 Inverse function: @ref{TAN}
1382
1383 @end table
1384
1385
1386
1387 @node ATAN2
1388 @section @code{ATAN2} --- Arctangent function
1389 @fnindex ATAN2
1390 @fnindex DATAN2
1391 @cindex trigonometric function, tangent, inverse
1392 @cindex tangent, inverse
1393
1394 @table @asis
1395 @item @emph{Description}:
1396 @code{ATAN2(Y, X)} computes the arctangent of the complex number
1397 @math{X + i Y}.
1398
1399 @item @emph{Standard}:
1400 Fortran 77 and later
1401
1402 @item @emph{Class}:
1403 Elemental function
1404
1405 @item @emph{Syntax}:
1406 @code{RESULT = ATAN2(Y, X)}
1407
1408 @item @emph{Arguments}:
1409 @multitable @columnfractions .15 .70
1410 @item @var{Y} @tab The type shall be @code{REAL}.
1411 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1412 If @var{Y} is zero, then @var{X} must be nonzero.
1413 @end multitable
1414
1415 @item @emph{Return value}:
1416 The return value has the same type and kind type parameter as @var{Y}.
1417 It is the principal value of the complex number @math{X + i Y}.  If
1418 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1419 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1420 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1421 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1422 is @math{\pi/2}.
1423
1424 @item @emph{Example}:
1425 @smallexample
1426 program test_atan2
1427   real(4) :: x = 1.e0_4, y = 0.5e0_4
1428   x = atan2(y,x)
1429 end program test_atan2
1430 @end smallexample
1431
1432 @item @emph{Specific names}:
1433 @multitable @columnfractions .20 .20 .20 .25
1434 @item Name            @tab Argument          @tab Return type    @tab Standard
1435 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1436 @end multitable
1437 @end table
1438
1439
1440
1441 @node ATANH
1442 @section @code{ATANH} --- Hyperbolic arctangent function
1443 @fnindex ASINH
1444 @fnindex DASINH
1445 @cindex area hyperbolic tangent
1446 @cindex hyperbolic arctangent
1447 @cindex hyperbolic function, tangent, inverse
1448 @cindex tangent, hyperbolic, inverse
1449
1450 @table @asis
1451 @item @emph{Description}:
1452 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1453 of @code{TANH(X)}).
1454
1455 @item @emph{Standard}:
1456 Fortran 2008 and later
1457
1458 @item @emph{Class}:
1459 Elemental function
1460
1461 @item @emph{Syntax}:
1462 @code{RESULT = ATANH(X)}
1463
1464 @item @emph{Arguments}:
1465 @multitable @columnfractions .15 .70
1466 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1467 @end multitable
1468
1469 @item @emph{Return value}:
1470 The return value has same type and kind as @var{X}.
1471
1472 @item @emph{Example}:
1473 @smallexample
1474 PROGRAM test_atanh
1475   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1476   WRITE (*,*) ATANH(x)
1477 END PROGRAM
1478 @end smallexample
1479
1480 @item @emph{Specific names}:
1481 @multitable @columnfractions .20 .20 .20 .25
1482 @item Name             @tab Argument          @tab Return type       @tab Standard
1483 @item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1484 @end multitable
1485
1486 @item @emph{See also}:
1487 Inverse function: @ref{TANH}
1488 @end table
1489
1490
1491
1492 @node BESSEL_J0
1493 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1494 @fnindex BESSEL_J0
1495 @fnindex BESJ0
1496 @fnindex DBESJ0
1497 @cindex Bessel function, first kind
1498
1499 @table @asis
1500 @item @emph{Description}:
1501 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1502 order 0 of @var{X}. This function is available under the name
1503 @code{BESJ0} as a GNU extension.
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 = BESSEL_J0(X)}
1513
1514 @item @emph{Arguments}:
1515 @multitable @columnfractions .15 .70
1516 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1517 @end multitable
1518
1519 @item @emph{Return value}:
1520 The return value is of type @code{REAL} and lies in the
1521 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1522 kind as @var{X}.
1523
1524 @item @emph{Example}:
1525 @smallexample
1526 program test_besj0
1527   real(8) :: x = 0.0_8
1528   x = bessel_j0(x)
1529 end program test_besj0
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{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1536 @end multitable
1537 @end table
1538
1539
1540
1541 @node BESSEL_J1
1542 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1543 @fnindex BESSEL_J1
1544 @fnindex BESJ1
1545 @fnindex DBESJ1
1546 @cindex Bessel function, first kind
1547
1548 @table @asis
1549 @item @emph{Description}:
1550 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1551 order 1 of @var{X}. This function is available under the name
1552 @code{BESJ1} as a GNU extension.
1553
1554 @item @emph{Standard}:
1555 Fortran 2008
1556
1557 @item @emph{Class}:
1558 Elemental function
1559
1560 @item @emph{Syntax}:
1561 @code{RESULT = BESSEL_J1(X)}
1562
1563 @item @emph{Arguments}:
1564 @multitable @columnfractions .15 .70
1565 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1566 @end multitable
1567
1568 @item @emph{Return value}:
1569 The return value is of type @code{REAL} and it lies in the
1570 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1571 kind as @var{X}.
1572
1573 @item @emph{Example}:
1574 @smallexample
1575 program test_besj1
1576   real(8) :: x = 1.0_8
1577   x = bessel_j1(x)
1578 end program test_besj1
1579 @end smallexample
1580
1581 @item @emph{Specific names}:
1582 @multitable @columnfractions .20 .20 .20 .25
1583 @item Name            @tab Argument          @tab Return type       @tab Standard
1584 @item @code{DBESJ1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1585 @end multitable
1586 @end table
1587
1588
1589
1590 @node BESSEL_JN
1591 @section @code{BESSEL_JN} --- Bessel function of the first kind
1592 @fnindex BESSEL_JN
1593 @fnindex BESJN
1594 @fnindex DBESJN
1595 @cindex Bessel function, first kind
1596
1597 @table @asis
1598 @item @emph{Description}:
1599 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1600 order @var{N} of @var{X}. This function is available under the name
1601 @code{BESJN} as a GNU extension.
1602
1603 If both arguments are arrays, their ranks and shapes shall conform.
1604
1605 @item @emph{Standard}:
1606 Fortran 2008 and later
1607
1608 @item @emph{Class}:
1609 Elemental function
1610
1611 @item @emph{Syntax}:
1612 @code{RESULT = BESSEL_JN(N, X)}
1613
1614 @item @emph{Arguments}:
1615 @multitable @columnfractions .15 .70
1616 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1617 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL}.
1618 @end multitable
1619
1620 @item @emph{Return value}:
1621 The return value is a scalar of type @code{REAL}. It has the same
1622 kind as @var{X}.
1623
1624 @item @emph{Example}:
1625 @smallexample
1626 program test_besjn
1627   real(8) :: x = 1.0_8
1628   x = bessel_jn(5,x)
1629 end program test_besjn
1630 @end smallexample
1631
1632 @item @emph{Specific names}:
1633 @multitable @columnfractions .20 .20 .20 .25
1634 @item Name             @tab Argument            @tab Return type       @tab Standard
1635 @item @code{DBESJN(X)} @tab @code{INTEGER N} @tab @code{REAL(8)}    @tab GNU extension
1636 @item                  @tab @code{REAL(8) X}    @tab                   @tab
1637 @end multitable
1638 @end table
1639
1640
1641
1642 @node BESSEL_Y0
1643 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1644 @fnindex BESSEL_Y0
1645 @fnindex BESY0
1646 @fnindex DBESY0
1647 @cindex Bessel function, second kind
1648
1649 @table @asis
1650 @item @emph{Description}:
1651 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1652 order 0 of @var{X}. This function is available under the name
1653 @code{BESY0} as a GNU extension.
1654
1655 @item @emph{Standard}:
1656 Fortran 2008 and later
1657
1658 @item @emph{Class}:
1659 Elemental function
1660
1661 @item @emph{Syntax}:
1662 @code{RESULT = BESSEL_Y0(X)}
1663
1664 @item @emph{Arguments}:
1665 @multitable @columnfractions .15 .70
1666 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1667 @end multitable
1668
1669 @item @emph{Return value}:
1670 The return value is a scalar of type @code{REAL}. It has the same
1671 kind as @var{X}.
1672
1673 @item @emph{Example}:
1674 @smallexample
1675 program test_besy0
1676   real(8) :: x = 0.0_8
1677   x = bessel_y0(x)
1678 end program test_besy0
1679 @end smallexample
1680
1681 @item @emph{Specific names}:
1682 @multitable @columnfractions .20 .20 .20 .25
1683 @item Name            @tab Argument          @tab Return type       @tab Standard
1684 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1685 @end multitable
1686 @end table
1687
1688
1689
1690 @node BESSEL_Y1
1691 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1692 @fnindex BESSEL_Y1
1693 @fnindex BESY1
1694 @fnindex DBESY1
1695 @cindex Bessel function, second kind
1696
1697 @table @asis
1698 @item @emph{Description}:
1699 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1700 order 1 of @var{X}. This function is available under the name
1701 @code{BESY1} as a GNU extension.
1702
1703 @item @emph{Standard}:
1704 Fortran 2008 and later
1705
1706 @item @emph{Class}:
1707 Elemental function
1708
1709 @item @emph{Syntax}:
1710 @code{RESULT = BESSEL_Y1(X)}
1711
1712 @item @emph{Arguments}:
1713 @multitable @columnfractions .15 .70
1714 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1715 @end multitable
1716
1717 @item @emph{Return value}:
1718 The return value is a scalar of type @code{REAL}. It has the same
1719 kind as @var{X}.
1720
1721 @item @emph{Example}:
1722 @smallexample
1723 program test_besy1
1724   real(8) :: x = 1.0_8
1725   x = bessel_y1(x)
1726 end program test_besy1
1727 @end smallexample
1728
1729 @item @emph{Specific names}:
1730 @multitable @columnfractions .20 .20 .20 .25
1731 @item Name            @tab Argument          @tab Return type       @tab Standard
1732 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1733 @end multitable
1734 @end table
1735
1736
1737
1738 @node BESSEL_YN
1739 @section @code{BESSEL_YN} --- Bessel function of the second kind
1740 @fnindex BESSEL_YN
1741 @fnindex BESYN
1742 @fnindex DBESYN
1743 @cindex Bessel function, second kind
1744
1745 @table @asis
1746 @item @emph{Description}:
1747 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1748 order @var{N} of @var{X}. This function is available under the name
1749 @code{BESYN} as a GNU extension.
1750
1751 If both arguments are arrays, their ranks and shapes shall conform.
1752
1753 @item @emph{Standard}:
1754 Fortran 2008 and later
1755
1756 @item @emph{Class}:
1757 Elemental function
1758
1759 @item @emph{Syntax}:
1760 @code{RESULT = BESSEL_YN(N, X)}
1761
1762 @item @emph{Arguments}:
1763 @multitable @columnfractions .15 .70
1764 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1765 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL}.
1766 @end multitable
1767
1768 @item @emph{Return value}:
1769 The return value is a scalar of type @code{REAL}. It has the same
1770 kind as @var{X}.
1771
1772 @item @emph{Example}:
1773 @smallexample
1774 program test_besyn
1775   real(8) :: x = 1.0_8
1776   x = bessel_yn(5,x)
1777 end program test_besyn
1778 @end smallexample
1779
1780 @item @emph{Specific names}:
1781 @multitable @columnfractions .20 .20 .20 .25
1782 @item Name               @tab Argument            @tab Return type     @tab Standard
1783 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1784 @item                    @tab @code{REAL(8)    X} @tab                 @tab
1785 @end multitable
1786 @end table
1787
1788
1789
1790 @node BIT_SIZE
1791 @section @code{BIT_SIZE} --- Bit size inquiry function
1792 @fnindex BIT_SIZE
1793 @cindex bits, number of
1794 @cindex size of a variable, in bits
1795
1796 @table @asis
1797 @item @emph{Description}:
1798 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1799 represented by the type of @var{I}.
1800
1801 @item @emph{Standard}:
1802 Fortran 95 and later
1803
1804 @item @emph{Class}:
1805 Inquiry function
1806
1807 @item @emph{Syntax}:
1808 @code{RESULT = BIT_SIZE(I)}
1809
1810 @item @emph{Arguments}:
1811 @multitable @columnfractions .15 .70
1812 @item @var{I} @tab The type shall be @code{INTEGER}.
1813 @end multitable
1814
1815 @item @emph{Return value}:
1816 The return value is of type @code{INTEGER}
1817
1818 @item @emph{Example}:
1819 @smallexample
1820 program test_bit_size
1821     integer :: i = 123
1822     integer :: size
1823     size = bit_size(i)
1824     print *, size
1825 end program test_bit_size
1826 @end smallexample
1827 @end table
1828
1829
1830
1831 @node BTEST
1832 @section @code{BTEST} --- Bit test function
1833 @fnindex BTEST
1834 @cindex bits, testing
1835
1836 @table @asis
1837 @item @emph{Description}:
1838 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1839 in @var{I} is set.
1840
1841 @item @emph{Standard}:
1842 Fortran 95 and later
1843
1844 @item @emph{Class}:
1845 Elemental function
1846
1847 @item @emph{Syntax}:
1848 @code{RESULT = BTEST(I, POS)}
1849
1850 @item @emph{Arguments}:
1851 @multitable @columnfractions .15 .70
1852 @item @var{I} @tab The type shall be @code{INTEGER}.
1853 @item @var{POS} @tab The type shall be @code{INTEGER}.
1854 @end multitable
1855
1856 @item @emph{Return value}:
1857 The return value is of type @code{LOGICAL}
1858
1859 @item @emph{Example}:
1860 @smallexample
1861 program test_btest
1862     integer :: i = 32768 + 1024 + 64
1863     integer :: pos
1864     logical :: bool
1865     do pos=0,16
1866         bool = btest(i, pos)
1867         print *, pos, bool
1868     end do
1869 end program test_btest
1870 @end smallexample
1871 @end table
1872
1873
1874 @node C_ASSOCIATED
1875 @section @code{C_ASSOCIATED} --- Status of a C pointer
1876 @fnindex C_ASSOCIATED
1877 @cindex association status, C pointer
1878 @cindex pointer, C association status
1879
1880 @table @asis
1881 @item @emph{Description}:
1882 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1883 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1884
1885 @item @emph{Standard}:
1886 Fortran 2003 and later
1887
1888 @item @emph{Class}:
1889 Inquiry function
1890
1891 @item @emph{Syntax}:
1892 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1893
1894 @item @emph{Arguments}:
1895 @multitable @columnfractions .15 .70
1896 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1897 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1898 @end multitable
1899
1900 @item @emph{Return value}:
1901 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1902 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1903 point to different addresses.
1904
1905 @item @emph{Example}:
1906 @smallexample
1907 subroutine association_test(a,b)
1908   use iso_c_binding, only: c_associated, c_loc, c_ptr
1909   implicit none
1910   real, pointer :: a
1911   type(c_ptr) :: b
1912   if(c_associated(b, c_loc(a))) &
1913      stop 'b and a do not point to same target'
1914 end subroutine association_test
1915 @end smallexample
1916
1917 @item @emph{See also}:
1918 @ref{C_LOC}, @ref{C_FUNLOC}
1919 @end table
1920
1921
1922 @node C_FUNLOC
1923 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1924 @fnindex C_FUNLOC
1925 @cindex pointer, C address of procedures
1926
1927 @table @asis
1928 @item @emph{Description}:
1929 @code{C_FUNLOC(x)} determines the C address of the argument.
1930
1931 @item @emph{Standard}:
1932 Fortran 2003 and later
1933
1934 @item @emph{Class}:
1935 Inquiry function
1936
1937 @item @emph{Syntax}:
1938 @code{RESULT = C_FUNLOC(x)}
1939
1940 @item @emph{Arguments}:
1941 @multitable @columnfractions .15 .70
1942 @item @var{x} @tab Interoperable function or pointer to such function.
1943 @end multitable
1944
1945 @item @emph{Return value}:
1946 The return value is of type @code{C_FUNPTR} and contains the C address
1947 of the argument.
1948
1949 @item @emph{Example}:
1950 @smallexample
1951 module x
1952   use iso_c_binding
1953   implicit none
1954 contains
1955   subroutine sub(a) bind(c)
1956     real(c_float) :: a
1957     a = sqrt(a)+5.0
1958   end subroutine sub
1959 end module x
1960 program main
1961   use iso_c_binding
1962   use x
1963   implicit none
1964   interface
1965     subroutine my_routine(p) bind(c,name='myC_func')
1966       import :: c_funptr
1967       type(c_funptr), intent(in) :: p
1968     end subroutine
1969   end interface
1970   call my_routine(c_funloc(sub))
1971 end program main
1972 @end smallexample
1973
1974 @item @emph{See also}:
1975 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1976 @end table
1977
1978
1979 @node C_F_PROCPOINTER
1980 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1981 @fnindex C_F_PROCPOINTER
1982 @cindex pointer, C address of pointers
1983
1984 @table @asis
1985 @item @emph{Description}:
1986 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
1987 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
1988
1989 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1990 this function is not fully operable.
1991
1992 @item @emph{Standard}:
1993 Fortran 2003 and later
1994
1995 @item @emph{Class}:
1996 Subroutine
1997
1998 @item @emph{Syntax}:
1999 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2000
2001 @item @emph{Arguments}:
2002 @multitable @columnfractions .15 .70
2003 @item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2004 @code{INTENT(IN)}.
2005 @item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2006 @code{INTENT(OUT)}.
2007 @end multitable
2008
2009 @item @emph{Example}:
2010 @smallexample
2011 program main
2012   use iso_c_binding
2013   implicit none
2014   abstract interface
2015     function func(a)
2016       import :: c_float
2017       real(c_float), intent(in) :: a
2018       real(c_float) :: func
2019     end function
2020   end interface
2021   interface
2022      function getIterFunc() bind(c,name="getIterFunc")
2023        import :: c_funptr
2024        type(c_funptr) :: getIterFunc
2025      end function
2026   end interface
2027   type(c_funptr) :: cfunptr
2028   procedure(func), pointer :: myFunc
2029   cfunptr = getIterFunc()
2030   call c_f_procpointer(cfunptr, myFunc)
2031 end program main
2032 @end smallexample
2033
2034 @item @emph{See also}:
2035 @ref{C_LOC}, @ref{C_F_POINTER}
2036 @end table
2037
2038
2039 @node C_F_POINTER
2040 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2041 @fnindex C_F_POINTER
2042 @cindex pointer, convert C to Fortran
2043
2044 @table @asis
2045 @item @emph{Description}:
2046 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2047 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2048 shape.
2049
2050 @item @emph{Standard}:
2051 Fortran 2003 and later
2052
2053 @item @emph{Class}:
2054 Subroutine
2055
2056 @item @emph{Syntax}:
2057 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2058
2059 @item @emph{Arguments}:
2060 @multitable @columnfractions .15 .70
2061 @item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2062 @code{INTENT(IN)}.
2063 @item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2064 @code{INTENT(OUT)}.
2065 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2066 with @code{INTENT(IN)}. It shall be present
2067 if and only if @var{fptr} is an array. The size
2068 must be equal to the rank of @var{fptr}.
2069 @end multitable
2070
2071 @item @emph{Example}:
2072 @smallexample
2073 program main
2074   use iso_c_binding
2075   implicit none
2076   interface
2077     subroutine my_routine(p) bind(c,name='myC_func')
2078       import :: c_ptr
2079       type(c_ptr), intent(out) :: p
2080     end subroutine
2081   end interface
2082   type(c_ptr) :: cptr
2083   real,pointer :: a(:)
2084   call my_routine(cptr)
2085   call c_f_pointer(cptr, a, [12])
2086 end program main
2087 @end smallexample
2088
2089 @item @emph{See also}:
2090 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2091 @end table
2092
2093
2094 @node C_LOC
2095 @section @code{C_LOC} --- Obtain the C address of an object
2096 @fnindex C_LOC
2097 @cindex procedure pointer, convert C to Fortran
2098
2099 @table @asis
2100 @item @emph{Description}:
2101 @code{C_LOC(X)} determines the C address of the argument.
2102
2103 @item @emph{Standard}:
2104 Fortran 2003 and later
2105
2106 @item @emph{Class}:
2107 Inquiry function
2108
2109 @item @emph{Syntax}:
2110 @code{RESULT = C_LOC(X)}
2111
2112 @item @emph{Arguments}:
2113 @multitable @columnfractions .15 .70
2114 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2115 or allocated allocatable variable with @code{TARGET} attribute.
2116 @end multitable
2117
2118 @item @emph{Return value}:
2119 The return value is of type @code{C_PTR} and contains the C address
2120 of the argument.
2121
2122 @item @emph{Example}:
2123 @smallexample
2124 subroutine association_test(a,b)
2125   use iso_c_binding, only: c_associated, c_loc, c_ptr
2126   implicit none
2127   real, pointer :: a
2128   type(c_ptr) :: b
2129   if(c_associated(b, c_loc(a))) &
2130      stop 'b and a do not point to same target'
2131 end subroutine association_test
2132 @end smallexample
2133
2134 @item @emph{See also}:
2135 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2136 @end table
2137
2138
2139 @node C_SIZEOF
2140 @section @code{C_SIZEOF} --- Size in bytes of an expression
2141 @fnindex C_SIZEOF
2142 @cindex expression size
2143 @cindex size of an expression
2144
2145 @table @asis
2146 @item @emph{Description}:
2147 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2148 expression @code{X} occupies.
2149
2150 @item @emph{Standard}:
2151 Fortran 2008
2152
2153 @item @emph{Class}:
2154 Intrinsic function
2155
2156 @item @emph{Syntax}:
2157 @code{N = C_SIZEOF(X)}
2158
2159 @item @emph{Arguments}:
2160 @multitable @columnfractions .15 .70
2161 @item @var{X} @tab The argument shall be of any type, rank or shape.
2162 @end multitable
2163
2164 @item @emph{Return value}:
2165 The return value is of type integer and of the system-dependent kind
2166 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2167 number of bytes occupied by the argument.  If the argument has the
2168 @code{POINTER} attribute, the number of bytes of the storage area pointed
2169 to is returned.  If the argument is of a derived type with @code{POINTER}
2170 or @code{ALLOCATABLE} components, the return value doesn't account for
2171 the sizes of the data pointed to by these components.
2172
2173 @item @emph{Example}:
2174 @smallexample
2175    use iso_c_binding
2176    integer(c_int) :: i
2177    real(c_float) :: r, s(5)
2178    print *, (c_sizeof(s)/c_sizeof(r) == 5)
2179    end
2180 @end smallexample
2181 The example will print @code{.TRUE.} unless you are using a platform
2182 where default @code{REAL} variables are unusually padded.
2183
2184 @item @emph{See also}:
2185 @ref{SIZEOF}
2186 @end table
2187
2188
2189 @node CEILING
2190 @section @code{CEILING} --- Integer ceiling function
2191 @fnindex CEILING
2192 @cindex ceiling
2193 @cindex rounding, ceiling
2194
2195 @table @asis
2196 @item @emph{Description}:
2197 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2198
2199 @item @emph{Standard}:
2200 Fortran 95 and later
2201
2202 @item @emph{Class}:
2203 Elemental function
2204
2205 @item @emph{Syntax}:
2206 @code{RESULT = CEILING(A [, KIND])}
2207
2208 @item @emph{Arguments}:
2209 @multitable @columnfractions .15 .70
2210 @item @var{A} @tab The type shall be @code{REAL}.
2211 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2212 expression indicating the kind parameter of the result.
2213 @end multitable
2214
2215 @item @emph{Return value}:
2216 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2217 and a default-kind @code{INTEGER} otherwise.
2218
2219 @item @emph{Example}:
2220 @smallexample
2221 program test_ceiling
2222     real :: x = 63.29
2223     real :: y = -63.59
2224     print *, ceiling(x) ! returns 64
2225     print *, ceiling(y) ! returns -63
2226 end program test_ceiling
2227 @end smallexample
2228
2229 @item @emph{See also}:
2230 @ref{FLOOR}, @ref{NINT}
2231
2232 @end table
2233
2234
2235
2236 @node CHAR
2237 @section @code{CHAR} --- Character conversion function
2238 @fnindex CHAR
2239 @cindex conversion, to character
2240
2241 @table @asis
2242 @item @emph{Description}:
2243 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2244
2245 @item @emph{Standard}:
2246 Fortran 77 and later
2247
2248 @item @emph{Class}:
2249 Elemental function
2250
2251 @item @emph{Syntax}:
2252 @code{RESULT = CHAR(I [, KIND])}
2253
2254 @item @emph{Arguments}:
2255 @multitable @columnfractions .15 .70
2256 @item @var{I} @tab The type shall be @code{INTEGER}.
2257 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2258 expression indicating the kind parameter of the result.
2259 @end multitable
2260
2261 @item @emph{Return value}:
2262 The return value is of type @code{CHARACTER(1)}
2263
2264 @item @emph{Example}:
2265 @smallexample
2266 program test_char
2267     integer :: i = 74
2268     character(1) :: c
2269     c = char(i)
2270     print *, i, c ! returns 'J'
2271 end program test_char
2272 @end smallexample
2273
2274 @item @emph{Note}:
2275 See @ref{ICHAR} for a discussion of converting between numerical values
2276 and formatted string representations.
2277
2278 @item @emph{See also}:
2279 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2280
2281 @end table
2282
2283
2284
2285 @node CHDIR
2286 @section @code{CHDIR} --- Change working directory
2287 @fnindex CHDIR
2288 @cindex system, working directory
2289
2290 @table @asis
2291 @item @emph{Description}:
2292 Change current working directory to a specified path.
2293
2294 This intrinsic is provided in both subroutine and function forms; however,
2295 only one form can be used in any given program unit.
2296
2297 @item @emph{Standard}:
2298 GNU extension
2299
2300 @item @emph{Class}:
2301 Subroutine, function
2302
2303 @item @emph{Syntax}:
2304 @multitable @columnfractions .80
2305 @item @code{CALL CHDIR(NAME [, STATUS])}
2306 @item @code{STATUS = CHDIR(NAME)}
2307 @end multitable
2308
2309 @item @emph{Arguments}:
2310 @multitable @columnfractions .15 .70
2311 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2312 kind and shall specify a valid path within the file system.
2313 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2314 kind.  Returns 0 on success, and a system specific and nonzero error code
2315 otherwise.
2316 @end multitable
2317
2318 @item @emph{Example}:
2319 @smallexample
2320 PROGRAM test_chdir
2321   CHARACTER(len=255) :: path
2322   CALL getcwd(path)
2323   WRITE(*,*) TRIM(path)
2324   CALL chdir("/tmp")
2325   CALL getcwd(path)
2326   WRITE(*,*) TRIM(path)
2327 END PROGRAM
2328 @end smallexample
2329
2330 @item @emph{See also}:
2331 @ref{GETCWD}
2332 @end table
2333
2334
2335
2336 @node CHMOD
2337 @section @code{CHMOD} --- Change access permissions of files
2338 @fnindex CHMOD
2339 @cindex file system, change access mode
2340
2341 @table @asis
2342 @item @emph{Description}:
2343 @code{CHMOD} changes the permissions of a file. This function invokes
2344 @code{/bin/chmod} and might therefore not work on all platforms.
2345
2346 This intrinsic is provided in both subroutine and function forms; however,
2347 only one form can be used in any given program unit.
2348
2349 @item @emph{Standard}:
2350 GNU extension
2351
2352 @item @emph{Class}:
2353 Subroutine, function
2354
2355 @item @emph{Syntax}:
2356 @multitable @columnfractions .80
2357 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2358 @item @code{STATUS = CHMOD(NAME, MODE)}
2359 @end multitable
2360
2361 @item @emph{Arguments}:
2362 @multitable @columnfractions .15 .70
2363
2364 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2365 file name. Trailing blanks are ignored unless the character
2366 @code{achar(0)} is present, then all characters up to and excluding
2367 @code{achar(0)} are used as the file name.
2368
2369 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2370 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2371 argument of @code{/bin/chmod}.
2372
2373 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2374 @code{0} on success and nonzero otherwise.
2375 @end multitable
2376
2377 @item @emph{Return value}:
2378 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2379 otherwise.
2380
2381 @item @emph{Example}:
2382 @code{CHMOD} as subroutine
2383 @smallexample
2384 program chmod_test
2385   implicit none
2386   integer :: status
2387   call chmod('test.dat','u+x',status)
2388   print *, 'Status: ', status
2389 end program chmod_test
2390 @end smallexample
2391 @code{CHMOD} as function:
2392 @smallexample
2393 program chmod_test
2394   implicit none
2395   integer :: status
2396   status = chmod('test.dat','u+x')
2397   print *, 'Status: ', status
2398 end program chmod_test
2399 @end smallexample
2400
2401 @end table
2402
2403
2404
2405 @node CMPLX
2406 @section @code{CMPLX} --- Complex conversion function
2407 @fnindex CMPLX
2408 @cindex complex numbers, conversion to
2409 @cindex conversion, to complex
2410
2411 @table @asis
2412 @item @emph{Description}:
2413 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2414 the real component.  If @var{Y} is present it is converted to the imaginary
2415 component.  If @var{Y} is not present then the imaginary component is set to
2416 0.0.  If @var{X} is complex then @var{Y} must not be present.
2417
2418 @item @emph{Standard}:
2419 Fortran 77 and later
2420
2421 @item @emph{Class}:
2422 Elemental function
2423
2424 @item @emph{Syntax}:
2425 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2426
2427 @item @emph{Arguments}:
2428 @multitable @columnfractions .15 .70
2429 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2430 or @code{COMPLEX}.
2431 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2432 @code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
2433 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2434 expression indicating the kind parameter of the result.
2435 @end multitable
2436
2437 @item @emph{Return value}:
2438 The return value is of @code{COMPLEX} type, with a kind equal to
2439 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2440 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2441 @var{X} and @var{Y}.
2442
2443 @item @emph{Example}:
2444 @smallexample
2445 program test_cmplx
2446     integer :: i = 42
2447     real :: x = 3.14
2448     complex :: z
2449     z = cmplx(i, x)
2450     print *, z, cmplx(x)
2451 end program test_cmplx
2452 @end smallexample
2453
2454 @item @emph{See also}:
2455 @ref{COMPLEX}
2456 @end table
2457
2458
2459
2460 @node COMMAND_ARGUMENT_COUNT
2461 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2462 @fnindex COMMAND_ARGUMENT_COUNT
2463 @cindex command-line arguments
2464 @cindex command-line arguments, number of
2465 @cindex arguments, to program
2466
2467 @table @asis
2468 @item @emph{Description}:
2469 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2470 command line when the containing program was invoked.
2471
2472 @item @emph{Standard}:
2473 Fortran 2003 and later
2474
2475 @item @emph{Class}:
2476 Inquiry function
2477
2478 @item @emph{Syntax}:
2479 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2480
2481 @item @emph{Arguments}:
2482 @multitable @columnfractions .15 .70
2483 @item None
2484 @end multitable
2485
2486 @item @emph{Return value}:
2487 The return value is of type @code{INTEGER(4)}
2488
2489 @item @emph{Example}:
2490 @smallexample
2491 program test_command_argument_count
2492     integer :: count
2493     count = command_argument_count()
2494     print *, count
2495 end program test_command_argument_count
2496 @end smallexample
2497
2498 @item @emph{See also}:
2499 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2500 @end table
2501
2502
2503
2504 @node COMPLEX
2505 @section @code{COMPLEX} --- Complex conversion function
2506 @fnindex COMPLEX
2507 @cindex complex numbers, conversion to
2508 @cindex conversion, to complex
2509
2510 @table @asis
2511 @item @emph{Description}:
2512 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2513 to the real component and @var{Y} is converted to the imaginary
2514 component.
2515
2516 @item @emph{Standard}:
2517 GNU extension
2518
2519 @item @emph{Class}:
2520 Elemental function
2521
2522 @item @emph{Syntax}:
2523 @code{RESULT = COMPLEX(X, Y)}
2524
2525 @item @emph{Arguments}:
2526 @multitable @columnfractions .15 .70
2527 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2528 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2529 @end multitable
2530
2531 @item @emph{Return value}:
2532 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2533 value is of default @code{COMPLEX} type.
2534
2535 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2536 type and one is of @code{INTEGER} type, then the return value is of
2537 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2538 argument with the highest precision.
2539
2540 @item @emph{Example}:
2541 @smallexample
2542 program test_complex
2543     integer :: i = 42
2544     real :: x = 3.14
2545     print *, complex(i, x)
2546 end program test_complex
2547 @end smallexample
2548
2549 @item @emph{See also}:
2550 @ref{CMPLX}
2551 @end table
2552
2553
2554
2555 @node CONJG
2556 @section @code{CONJG} --- Complex conjugate function
2557 @fnindex CONJG
2558 @fnindex DCONJG
2559 @cindex complex conjugate
2560
2561 @table @asis
2562 @item @emph{Description}:
2563 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2564 then the result is @code{(x, -y)}
2565
2566 @item @emph{Standard}:
2567 Fortran 77 and later, has overloads that are GNU extensions
2568
2569 @item @emph{Class}:
2570 Elemental function
2571
2572 @item @emph{Syntax}:
2573 @code{Z = CONJG(Z)}
2574
2575 @item @emph{Arguments}:
2576 @multitable @columnfractions .15 .70
2577 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2578 @end multitable
2579
2580 @item @emph{Return value}:
2581 The return value is of type @code{COMPLEX}.
2582
2583 @item @emph{Example}:
2584 @smallexample
2585 program test_conjg
2586     complex :: z = (2.0, 3.0)
2587     complex(8) :: dz = (2.71_8, -3.14_8)
2588     z= conjg(z)
2589     print *, z
2590     dz = dconjg(dz)
2591     print *, dz
2592 end program test_conjg
2593 @end smallexample
2594
2595 @item @emph{Specific names}:
2596 @multitable @columnfractions .20 .20 .20 .25
2597 @item Name             @tab Argument             @tab Return type          @tab Standard
2598 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)}    @tab GNU extension
2599 @end multitable
2600 @end table
2601
2602
2603
2604 @node COS
2605 @section @code{COS} --- Cosine function
2606 @fnindex COS
2607 @fnindex DCOS
2608 @fnindex CCOS
2609 @fnindex ZCOS
2610 @fnindex CDCOS
2611 @cindex trigonometric function, cosine
2612 @cindex cosine
2613
2614 @table @asis
2615 @item @emph{Description}:
2616 @code{COS(X)} computes the cosine of @var{X}.
2617
2618 @item @emph{Standard}:
2619 Fortran 77 and later, has overloads that are GNU extensions
2620
2621 @item @emph{Class}:
2622 Elemental function
2623
2624 @item @emph{Syntax}:
2625 @code{RESULT = COS(X)}
2626
2627 @item @emph{Arguments}:
2628 @multitable @columnfractions .15 .70
2629 @item @var{X} @tab The type shall be @code{REAL} or
2630 @code{COMPLEX}.
2631 @end multitable
2632
2633 @item @emph{Return value}:
2634 The return value is of type @code{REAL} and it lies in the
2635 range @math{ -1 \leq \cos (x) \leq 1}.  The kind type
2636 parameter is the same as @var{X}.
2637
2638 @item @emph{Example}:
2639 @smallexample
2640 program test_cos
2641   real :: x = 0.0
2642   x = cos(x)
2643 end program test_cos
2644 @end smallexample
2645
2646 @item @emph{Specific names}:
2647 @multitable @columnfractions .20 .20 .20 .25
2648 @item Name            @tab Argument            @tab Return type       @tab Standard
2649 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
2650 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2651 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2652 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2653 @end multitable
2654
2655 @item @emph{See also}:
2656 Inverse function: @ref{ACOS}
2657
2658 @end table
2659
2660
2661
2662 @node COSH
2663 @section @code{COSH} --- Hyperbolic cosine function
2664 @fnindex COSH
2665 @fnindex DCOSH
2666 @cindex hyperbolic cosine
2667 @cindex hyperbolic function, cosine
2668 @cindex cosine, hyperbolic
2669
2670 @table @asis
2671 @item @emph{Description}:
2672 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2673
2674 @item @emph{Standard}:
2675 Fortran 77 and later
2676
2677 @item @emph{Class}:
2678 Elemental function
2679
2680 @item @emph{Syntax}:
2681 @code{X = COSH(X)}
2682
2683 @item @emph{Arguments}:
2684 @multitable @columnfractions .15 .70
2685 @item @var{X} @tab The type shall be @code{REAL}.
2686 @end multitable
2687
2688 @item @emph{Return value}:
2689 The return value is of type @code{REAL} and it is positive
2690 (@math{ \cosh (x) \geq 0 }. The return value is of the same
2691 kind as @var{X}.
2692
2693 @item @emph{Example}:
2694 @smallexample
2695 program test_cosh
2696   real(8) :: x = 1.0_8
2697   x = cosh(x)
2698 end program test_cosh
2699 @end smallexample
2700
2701 @item @emph{Specific names}:
2702 @multitable @columnfractions .20 .20 .20 .25
2703 @item Name            @tab Argument          @tab Return type       @tab Standard
2704 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
2705 @end multitable
2706
2707 @item @emph{See also}:
2708 Inverse function: @ref{ACOSH}
2709
2710 @end table
2711
2712
2713
2714 @node COUNT
2715 @section @code{COUNT} --- Count function
2716 @fnindex COUNT
2717 @cindex array, conditionally count elements
2718 @cindex array, element counting
2719 @cindex array, number of elements
2720
2721 @table @asis
2722 @item @emph{Description}:
2723
2724 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2725 elements of @var{MASK} along the dimension of @var{DIM}.  If @var{DIM} is
2726 omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type
2727 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2728 is the rank of @var{MASK}.
2729
2730 @item @emph{Standard}:
2731 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2732
2733 @item @emph{Class}:
2734 Transformational function
2735
2736 @item @emph{Syntax}:
2737 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2738
2739 @item @emph{Arguments}:
2740 @multitable @columnfractions .15 .70
2741 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2742 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
2743 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2744 expression indicating the kind parameter of the result.
2745 @end multitable
2746
2747 @item @emph{Return value}:
2748 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2749 @var{KIND} is absent, the return value is of default integer kind.
2750 The result has a rank equal to that of @var{MASK}.
2751
2752 @item @emph{Example}:
2753 @smallexample
2754 program test_count
2755     integer, dimension(2,3) :: a, b
2756     logical, dimension(2,3) :: mask
2757     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2758     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2759     print '(3i3)', a(1,:)
2760     print '(3i3)', a(2,:)
2761     print *
2762     print '(3i3)', b(1,:)
2763     print '(3i3)', b(2,:)
2764     print *
2765     mask = a.ne.b
2766     print '(3l3)', mask(1,:)
2767     print '(3l3)', mask(2,:)
2768     print *
2769     print '(3i3)', count(mask)
2770     print *
2771     print '(3i3)', count(mask, 1)
2772     print *
2773     print '(3i3)', count(mask, 2)
2774 end program test_count
2775 @end smallexample
2776 @end table
2777
2778
2779
2780 @node CPU_TIME
2781 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2782 @fnindex CPU_TIME
2783 @cindex time, elapsed
2784
2785 @table @asis
2786 @item @emph{Description}:
2787 Returns a @code{REAL} value representing the elapsed CPU time in
2788 seconds.  This is useful for testing segments of code to determine
2789 execution time.
2790
2791 If a time source is available, time will be reported with microsecond
2792 resolution. If no time source is available, @var{TIME} is set to
2793 @code{-1.0}.
2794
2795 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2796 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2797 value is meaningless, only differences between subsequent calls to
2798 this subroutine, as shown in the example below, should be used.
2799
2800
2801 @item @emph{Standard}:
2802 Fortran 95 and later
2803
2804 @item @emph{Class}:
2805 Subroutine
2806
2807 @item @emph{Syntax}:
2808 @code{CALL CPU_TIME(TIME)}
2809
2810 @item @emph{Arguments}:
2811 @multitable @columnfractions .15 .70
2812 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2813 @end multitable
2814
2815 @item @emph{Return value}:
2816 None
2817
2818 @item @emph{Example}:
2819 @smallexample
2820 program test_cpu_time
2821     real :: start, finish
2822     call cpu_time(start)
2823         ! put code to test here
2824     call cpu_time(finish)
2825     print '("Time = ",f6.3," seconds.")',finish-start
2826 end program test_cpu_time
2827 @end smallexample
2828
2829 @item @emph{See also}:
2830 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2831 @end table
2832
2833
2834
2835 @node CSHIFT
2836 @section @code{CSHIFT} --- Circular shift elements of an array
2837 @fnindex CSHIFT
2838 @cindex array, shift circularly
2839 @cindex array, permutation
2840 @cindex array, rotate
2841
2842 @table @asis
2843 @item @emph{Description}:
2844 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2845 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
2846 taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the
2847 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2848 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2849 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
2850 sections of @var{ARRAY} along the given dimension are shifted.  Elements
2851 shifted out one end of each rank one section are shifted back in the other end.
2852
2853 @item @emph{Standard}:
2854 Fortran 95 and later
2855
2856 @item @emph{Class}:
2857 Transformational function
2858
2859 @item @emph{Syntax}:
2860 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2861
2862 @item @emph{Arguments}:
2863 @multitable @columnfractions .15 .70
2864 @item @var{ARRAY}  @tab Shall be an array of any type.
2865 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
2866 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
2867 @end multitable
2868
2869 @item @emph{Return value}:
2870 Returns an array of same type and rank as the @var{ARRAY} argument.
2871
2872 @item @emph{Example}:
2873 @smallexample
2874 program test_cshift
2875     integer, dimension(3,3) :: a
2876     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2877     print '(3i3)', a(1,:)
2878     print '(3i3)', a(2,:)
2879     print '(3i3)', a(3,:)
2880     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2881     print *
2882     print '(3i3)', a(1,:)
2883     print '(3i3)', a(2,:)
2884     print '(3i3)', a(3,:)
2885 end program test_cshift
2886 @end smallexample
2887 @end table
2888
2889
2890
2891 @node CTIME
2892 @section @code{CTIME} --- Convert a time into a string
2893 @fnindex CTIME
2894 @cindex time, conversion to string
2895 @cindex conversion, to string
2896
2897 @table @asis
2898 @item @emph{Description}:
2899 @code{CTIME} converts a system time value, such as returned by
2900 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2901
2902 This intrinsic is provided in both subroutine and function forms; however,
2903 only one form can be used in any given program unit.
2904
2905 @item @emph{Standard}:
2906 GNU extension
2907
2908 @item @emph{Class}:
2909 Subroutine, function
2910
2911 @item @emph{Syntax}:
2912 @multitable @columnfractions .80
2913 @item @code{CALL CTIME(TIME, RESULT)}.
2914 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2915 @end multitable
2916
2917 @item @emph{Arguments}:
2918 @multitable @columnfractions .15 .70
2919 @item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
2920 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
2921 of default kind.
2922 @end multitable
2923
2924 @item @emph{Return value}:
2925 The converted date and time as a string.
2926
2927 @item @emph{Example}:
2928 @smallexample
2929 program test_ctime
2930     integer(8) :: i
2931     character(len=30) :: date
2932     i = time8()
2933
2934     ! Do something, main part of the program
2935
2936     call ctime(i,date)
2937     print *, 'Program was started on ', date
2938 end program test_ctime
2939 @end smallexample
2940
2941 @item @emph{See Also}:
2942 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2943 @end table
2944
2945
2946
2947 @node DATE_AND_TIME
2948 @section @code{DATE_AND_TIME} --- Date and time subroutine
2949 @fnindex DATE_AND_TIME
2950 @cindex date, current
2951 @cindex current date
2952 @cindex time, current
2953 @cindex current time
2954
2955 @table @asis
2956 @item @emph{Description}:
2957 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2958 time information from the real-time system clock.  @var{DATE} is
2959 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
2960 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2961 representing the difference with respect to Coordinated Universal Time (UTC).
2962 Unavailable time and date parameters return blanks.
2963
2964 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2965
2966 @multitable @columnfractions .15 .30 .40
2967 @item @tab @code{VALUE(1)}: @tab The year
2968 @item @tab @code{VALUE(2)}: @tab The month
2969 @item @tab @code{VALUE(3)}: @tab The day of the month
2970 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2971 @item @tab @code{VALUE(5)}: @tab The hour of the day
2972 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2973 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2974 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2975 @end multitable
2976
2977 @item @emph{Standard}:
2978 Fortran 95 and later
2979
2980 @item @emph{Class}:
2981 Subroutine
2982
2983 @item @emph{Syntax}:
2984 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2985
2986 @item @emph{Arguments}:
2987 @multitable @columnfractions .15 .70
2988 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
2989 or larger, and of default kind.
2990 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
2991 or larger, and of default kind.
2992 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
2993 or larger, and of default kind.
2994 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2995 @end multitable
2996
2997 @item @emph{Return value}:
2998 None
2999
3000 @item @emph{Example}:
3001 @smallexample
3002 program test_time_and_date
3003     character(8)  :: date
3004     character(10) :: time
3005     character(5)  :: zone
3006     integer,dimension(8) :: values
3007     ! using keyword arguments
3008     call date_and_time(date,time,zone,values)
3009     call date_and_time(DATE=date,ZONE=zone)
3010     call date_and_time(TIME=time)
3011     call date_and_time(VALUES=values)
3012     print '(a,2x,a,2x,a)', date, time, zone
3013     print '(8i5))', values
3014 end program test_time_and_date
3015 @end smallexample
3016
3017 @item @emph{See also}:
3018 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3019 @end table
3020
3021
3022
3023 @node DBLE
3024 @section @code{DBLE} --- Double conversion function
3025 @fnindex DBLE
3026 @cindex conversion, to real
3027
3028 @table @asis
3029 @item @emph{Description}:
3030 @code{DBLE(A)} Converts @var{A} to double precision real type.
3031
3032 @item @emph{Standard}:
3033 Fortran 77 and later
3034
3035 @item @emph{Class}:
3036 Elemental function
3037
3038 @item @emph{Syntax}:
3039 @code{RESULT = DBLE(A)}
3040
3041 @item @emph{Arguments}:
3042 @multitable @columnfractions .15 .70
3043 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3044 or @code{COMPLEX}.
3045 @end multitable
3046
3047 @item @emph{Return value}:
3048 The return value is of type double precision real.
3049
3050 @item @emph{Example}:
3051 @smallexample
3052 program test_dble
3053     real    :: x = 2.18
3054     integer :: i = 5
3055     complex :: z = (2.3,1.14)
3056     print *, dble(x), dble(i), dble(z)
3057 end program test_dble
3058 @end smallexample
3059
3060 @item @emph{See also}:
3061 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3062 @end table
3063
3064
3065
3066 @node DCMPLX
3067 @section @code{DCMPLX} --- Double complex conversion function
3068 @fnindex DCMPLX
3069 @cindex complex numbers, conversion to
3070 @cindex conversion, to complex
3071
3072 @table @asis
3073 @item @emph{Description}:
3074 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3075 converted to the real component.  If @var{Y} is present it is converted to the
3076 imaginary component.  If @var{Y} is not present then the imaginary component is
3077 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3078
3079 @item @emph{Standard}:
3080 GNU extension
3081
3082 @item @emph{Class}:
3083 Elemental function
3084
3085 @item @emph{Syntax}:
3086 @code{RESULT = DCMPLX(X [, Y])}
3087
3088 @item @emph{Arguments}:
3089 @multitable @columnfractions .15 .70
3090 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3091 or @code{COMPLEX}.
3092 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3093 @code{INTEGER} or @code{REAL}.
3094 @end multitable
3095
3096 @item @emph{Return value}:
3097 The return value is of type @code{COMPLEX(8)}
3098
3099 @item @emph{Example}:
3100 @smallexample
3101 program test_dcmplx
3102     integer :: i = 42
3103     real :: x = 3.14
3104     complex :: z
3105     z = cmplx(i, x)
3106     print *, dcmplx(i)
3107     print *, dcmplx(x)
3108     print *, dcmplx(z)
3109     print *, dcmplx(x,i)
3110 end program test_dcmplx
3111 @end smallexample
3112 @end table
3113
3114
3115
3116 @node DFLOAT
3117 @section @code{DFLOAT} --- Double conversion function
3118 @fnindex DFLOAT
3119 @cindex conversion, to real
3120
3121 @table @asis
3122 @item @emph{Description}:
3123 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3124
3125 @item @emph{Standard}:
3126 GNU extension
3127
3128 @item @emph{Class}:
3129 Elemental function
3130
3131 @item @emph{Syntax}:
3132 @code{RESULT = DFLOAT(A)}
3133
3134 @item @emph{Arguments}:
3135 @multitable @columnfractions .15 .70
3136 @item @var{A} @tab The type shall be @code{INTEGER}.
3137 @end multitable
3138
3139 @item @emph{Return value}:
3140 The return value is of type double precision real.
3141
3142 @item @emph{Example}:
3143 @smallexample
3144 program test_dfloat
3145     integer :: i = 5
3146     print *, dfloat(i)
3147 end program test_dfloat
3148 @end smallexample
3149
3150 @item @emph{See also}:
3151 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3152 @end table
3153
3154
3155
3156 @node DIGITS
3157 @section @code{DIGITS} --- Significant digits function
3158 @fnindex DIGITS
3159 @cindex model representation, significant digits
3160
3161 @table @asis
3162 @item @emph{Description}:
3163 @code{DIGITS(X)} returns the number of significant digits of the internal model
3164 representation of @var{X}.  For example, on a system using a 32-bit
3165 floating point representation, a default real number would likely return 24.
3166
3167 @item @emph{Standard}:
3168 Fortran 95 and later
3169
3170 @item @emph{Class}:
3171 Inquiry function
3172
3173 @item @emph{Syntax}:
3174 @code{RESULT = DIGITS(X)}
3175
3176 @item @emph{Arguments}:
3177 @multitable @columnfractions .15 .70
3178 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3179 @end multitable
3180
3181 @item @emph{Return value}:
3182 The return value is of type @code{INTEGER}.
3183
3184 @item @emph{Example}:
3185 @smallexample
3186 program test_digits
3187     integer :: i = 12345
3188     real :: x = 3.143
3189     real(8) :: y = 2.33
3190     print *, digits(i)
3191     print *, digits(x)
3192     print *, digits(y)
3193 end program test_digits
3194 @end smallexample
3195 @end table
3196
3197
3198
3199 @node DIM
3200 @section @code{DIM} --- Positive difference
3201 @fnindex DIM
3202 @fnindex IDIM
3203 @fnindex DDIM
3204 @cindex positive difference
3205
3206 @table @asis
3207 @item @emph{Description}:
3208 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3209 otherwise returns zero.
3210
3211 @item @emph{Standard}:
3212 Fortran 77 and later
3213
3214 @item @emph{Class}:
3215 Elemental function
3216
3217 @item @emph{Syntax}:
3218 @code{RESULT = DIM(X, Y)}
3219
3220 @item @emph{Arguments}:
3221 @multitable @columnfractions .15 .70
3222 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3223 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3224 @end multitable
3225
3226 @item @emph{Return value}:
3227 The return value is of type @code{INTEGER} or @code{REAL}.
3228
3229 @item @emph{Example}:
3230 @smallexample
3231 program test_dim
3232     integer :: i
3233     real(8) :: x
3234     i = dim(4, 15)
3235     x = dim(4.345_8, 2.111_8)
3236     print *, i
3237     print *, x
3238 end program test_dim
3239 @end smallexample
3240
3241 @item @emph{Specific names}:
3242 @multitable @columnfractions .20 .20 .20 .25
3243 @item Name             @tab Argument              @tab Return type       @tab Standard
3244 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3245 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3246 @end multitable
3247 @end table
3248
3249
3250
3251 @node DOT_PRODUCT
3252 @section @code{DOT_PRODUCT} --- Dot product function
3253 @fnindex DOT_PRODUCT
3254 @cindex dot product
3255 @cindex vector product
3256 @cindex product, vector
3257
3258 @table @asis
3259 @item @emph{Description}:
3260 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3261 of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3262 either numeric or logical and must be arrays of rank one and of equal size. If
3263 the vectors are @code{INTEGER} or @code{REAL}, the result is
3264 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3265 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3266 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3267
3268 @item @emph{Standard}:
3269 Fortran 95 and later
3270
3271 @item @emph{Class}:
3272 Transformational function
3273
3274 @item @emph{Syntax}:
3275 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3276
3277 @item @emph{Arguments}:
3278 @multitable @columnfractions .15 .70
3279 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3280 @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.
3281 @end multitable
3282
3283 @item @emph{Return value}:
3284 If the arguments are numeric, the return value is a scaler of numeric type,
3285 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3286 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3287
3288 @item @emph{Example}:
3289 @smallexample
3290 program test_dot_prod
3291     integer, dimension(3) :: a, b
3292     a = (/ 1, 2, 3 /)
3293     b = (/ 4, 5, 6 /)
3294     print '(3i3)', a
3295     print *
3296     print '(3i3)', b
3297     print *
3298     print *, dot_product(a,b)
3299 end program test_dot_prod
3300 @end smallexample
3301 @end table
3302
3303
3304
3305 @node DPROD
3306 @section @code{DPROD} --- Double product function
3307 @fnindex DPROD
3308 @cindex product, double-precision
3309
3310 @table @asis
3311 @item @emph{Description}:
3312 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3313
3314 @item @emph{Standard}:
3315 Fortran 77 and later
3316
3317 @item @emph{Class}:
3318 Elemental function
3319
3320 @item @emph{Syntax}:
3321 @code{RESULT = DPROD(X, Y)}
3322
3323 @item @emph{Arguments}:
3324 @multitable @columnfractions .15 .70
3325 @item @var{X} @tab The type shall be @code{REAL}.
3326 @item @var{Y} @tab The type shall be @code{REAL}.
3327 @end multitable
3328
3329 @item @emph{Return value}:
3330 The return value is of type @code{REAL(8)}.
3331
3332 @item @emph{Example}:
3333 @smallexample
3334 program test_dprod
3335     real :: x = 5.2
3336     real :: y = 2.3
3337     real(8) :: d
3338     d = dprod(x,y)
3339     print *, d
3340 end program test_dprod
3341 @end smallexample
3342 @end table
3343
3344
3345
3346 @node DREAL
3347 @section @code{DREAL} --- Double real part function
3348 @fnindex DREAL
3349 @cindex complex numbers, real part
3350
3351 @table @asis
3352 @item @emph{Description}:
3353 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3354
3355 @item @emph{Standard}:
3356 GNU extension
3357
3358 @item @emph{Class}:
3359 Elemental function
3360
3361 @item @emph{Syntax}:
3362 @code{RESULT = DREAL(A)}
3363
3364 @item @emph{Arguments}:
3365 @multitable @columnfractions .15 .70
3366 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3367 @end multitable
3368
3369 @item @emph{Return value}:
3370 The return value is of type @code{REAL(8)}.
3371
3372 @item @emph{Example}:
3373 @smallexample
3374 program test_dreal
3375     complex(8) :: z = (1.3_8,7.2_8)
3376     print *, dreal(z)
3377 end program test_dreal
3378 @end smallexample
3379
3380 @item @emph{See also}:
3381 @ref{AIMAG}
3382
3383 @end table
3384
3385
3386
3387 @node DTIME
3388 @section @code{DTIME} --- Execution time subroutine (or function)
3389 @fnindex DTIME
3390 @cindex time, elapsed
3391 @cindex elapsed time
3392
3393 @table @asis
3394 @item @emph{Description}:
3395 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3396 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
3397 returns the user and system components of this time in @code{TARRAY(1)} and
3398 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3399 TARRAY(2)}.
3400
3401 Subsequent invocations of @code{DTIME} return values accumulated since the
3402 previous invocation.
3403
3404 On some systems, the underlying timings are represented using types with
3405 sufficiently small limits that overflows (wrap around) are possible, such as
3406 32-bit types. Therefore, the values returned by this intrinsic might be, or
3407 become, negative, or numerically less than previous values, during a single
3408 run of the compiled program.
3409
3410 Please note, that this implementation is thread safe if used within OpenMP
3411 directives, i.e., its state will be consistent while called from multiple
3412 threads. However, if @code{DTIME} is called from multiple threads, the result
3413 is still the time since the last invocation. This may not give the intended
3414 results. If possible, use @code{CPU_TIME} instead.
3415
3416 This intrinsic is provided in both subroutine and function forms; however,
3417 only one form can be used in any given program unit.
3418
3419 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3420
3421 @multitable @columnfractions .15 .30 .40
3422 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3423 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3424 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3425 @end multitable
3426
3427 @item @emph{Standard}:
3428 GNU extension
3429
3430 @item @emph{Class}:
3431 Subroutine, function
3432
3433 @item @emph{Syntax}:
3434 @multitable @columnfractions .80
3435 @item @code{CALL DTIME(TARRAY, RESULT)}.
3436 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3437 @end multitable
3438
3439 @item @emph{Arguments}:
3440 @multitable @columnfractions .15 .70
3441 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3442 @item @var{RESULT}@tab The type shall be @code{REAL}.
3443 @end multitable
3444
3445 @item @emph{Return value}:
3446 Elapsed time in seconds since the last invocation or since the start of program
3447 execution if not called before.
3448
3449 @item @emph{Example}:
3450 @smallexample
3451 program test_dtime
3452     integer(8) :: i, j
3453     real, dimension(2) :: tarray
3454     real :: result
3455     call dtime(tarray, result)
3456     print *, result
3457     print *, tarray(1)
3458     print *, tarray(2)
3459     do i=1,100000000    ! Just a delay
3460         j = i * i - i
3461     end do
3462     call dtime(tarray, result)
3463     print *, result
3464     print *, tarray(1)
3465     print *, tarray(2)
3466 end program test_dtime
3467 @end smallexample
3468
3469 @item @emph{See also}:
3470 @ref{CPU_TIME}
3471
3472 @end table
3473
3474
3475
3476 @node EOSHIFT
3477 @section @code{EOSHIFT} --- End-off shift elements of an array
3478 @fnindex EOSHIFT
3479 @cindex array, shift
3480
3481 @table @asis
3482 @item @emph{Description}:
3483 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3484 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3485 omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type
3486 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3487 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3488 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3489 then all complete rank one sections of @var{ARRAY} along the given dimension are
3490 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3491 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3492 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3493 following are copied in depending on the type of @var{ARRAY}.
3494
3495 @multitable @columnfractions .15 .80
3496 @item @emph{Array Type} @tab @emph{Boundary Value}
3497 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3498 @item Logical  @tab @code{.FALSE.}.
3499 @item Character(@var{len}) @tab @var{len} blanks.
3500 @end multitable
3501
3502 @item @emph{Standard}:
3503 Fortran 95 and later
3504
3505 @item @emph{Class}:
3506 Transformational function
3507
3508 @item @emph{Syntax}:
3509 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3510
3511 @item @emph{Arguments}:
3512 @multitable @columnfractions .15 .70
3513 @item @var{ARRAY}  @tab May be any type, not scaler.
3514 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3515 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3516 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3517 @end multitable
3518
3519 @item @emph{Return value}:
3520 Returns an array of same type and rank as the @var{ARRAY} argument.
3521
3522 @item @emph{Example}:
3523 @smallexample
3524 program test_eoshift
3525     integer, dimension(3,3) :: a
3526     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3527     print '(3i3)', a(1,:)
3528     print '(3i3)', a(2,:)
3529     print '(3i3)', a(3,:)
3530     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3531     print *
3532     print '(3i3)', a(1,:)
3533     print '(3i3)', a(2,:)
3534     print '(3i3)', a(3,:)
3535 end program test_eoshift
3536 @end smallexample
3537 @end table
3538
3539
3540
3541 @node EPSILON
3542 @section @code{EPSILON} --- Epsilon function
3543 @fnindex EPSILON
3544 @cindex model representation, epsilon
3545
3546 @table @asis
3547 @item @emph{Description}:
3548 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3549
3550 @item @emph{Standard}:
3551 Fortran 95 and later
3552
3553 @item @emph{Class}:
3554 Inquiry function
3555
3556 @item @emph{Syntax}:
3557 @code{RESULT = EPSILON(X)}
3558
3559 @item @emph{Arguments}:
3560 @multitable @columnfractions .15 .70
3561 @item @var{X} @tab The type shall be @code{REAL}.
3562 @end multitable
3563
3564 @item @emph{Return value}:
3565 The return value is of same type as the argument.
3566
3567 @item @emph{Example}:
3568 @smallexample
3569 program test_epsilon
3570     real :: x = 3.143
3571     real(8) :: y = 2.33
3572     print *, EPSILON(x)
3573     print *, EPSILON(y)
3574 end program test_epsilon
3575 @end smallexample
3576 @end table
3577
3578
3579
3580 @node ERF
3581 @section @code{ERF} --- Error function
3582 @fnindex ERF
3583 @cindex error function
3584
3585 @table @asis
3586 @item @emph{Description}:
3587 @code{ERF(X)} computes the error function of @var{X}.
3588
3589 @item @emph{Standard}:
3590 Fortran 2008 and later
3591
3592 @item @emph{Class}:
3593 Elemental function
3594
3595 @item @emph{Syntax}:
3596 @code{RESULT = ERF(X)}
3597
3598 @item @emph{Arguments}:
3599 @multitable @columnfractions .15 .70
3600 @item @var{X} @tab The type shall be @code{REAL}.
3601 @end multitable
3602
3603 @item @emph{Return value}:
3604 The return value is of type @code{REAL}, of the same kind as
3605 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3606
3607 @item @emph{Example}:
3608 @smallexample
3609 program test_erf
3610   real(8) :: x = 0.17_8
3611   x = erf(x)
3612 end program test_erf
3613 @end smallexample
3614
3615 @item @emph{Specific names}:
3616 @multitable @columnfractions .20 .20 .20 .25
3617 @item Name            @tab Argument          @tab Return type       @tab Standard
3618 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3619 @end multitable
3620 @end table
3621
3622
3623
3624 @node ERFC
3625 @section @code{ERFC} --- Error function
3626 @fnindex ERFC
3627 @cindex error function, complementary
3628
3629 @table @asis
3630 @item @emph{Description}:
3631 @code{ERFC(X)} computes the complementary error function of @var{X}.
3632
3633 @item @emph{Standard}:
3634 Fortran 2008 and later
3635
3636 @item @emph{Class}:
3637 Elemental function
3638
3639 @item @emph{Syntax}:
3640 @code{RESULT = ERFC(X)}
3641
3642 @item @emph{Arguments}:
3643 @multitable @columnfractions .15 .70
3644 @item @var{X} @tab The type shall be @code{REAL}.
3645 @end multitable
3646
3647 @item @emph{Return value}:
3648 The return value is of type @code{REAL} and of the same kind as @var{X}.
3649 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3650
3651 @item @emph{Example}:
3652 @smallexample
3653 program test_erfc
3654   real(8) :: x = 0.17_8
3655   x = erfc(x)
3656 end program test_erfc
3657 @end smallexample
3658
3659 @item @emph{Specific names}:
3660 @multitable @columnfractions .20 .20 .20 .25
3661 @item Name            @tab Argument          @tab Return type       @tab Standard
3662 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3663 @end multitable
3664 @end table
3665
3666
3667
3668 @node ERFC_SCALED
3669 @section @code{ERFC_SCALED} --- Error function
3670 @fnindex ERFC_SCALED
3671 @cindex error function, complementary, exponentially-scaled
3672
3673 @table @asis
3674 @item @emph{Description}:
3675 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3676 error function of @var{X}.
3677
3678 @item @emph{Standard}:
3679 Fortran 2008 and later
3680
3681 @item @emph{Class}:
3682 Elemental function
3683
3684 @item @emph{Syntax}:
3685 @code{RESULT = ERFC_SCALED(X)}
3686
3687 @item @emph{Arguments}:
3688 @multitable @columnfractions .15 .70
3689 @item @var{X} @tab The type shall be @code{REAL}.
3690 @end multitable
3691
3692 @item @emph{Return value}:
3693 The return value is of type @code{REAL} and of the same kind as @var{X}.
3694
3695 @item @emph{Example}:
3696 @smallexample
3697 program test_erfc_scaled
3698   real(8) :: x = 0.17_8
3699   x = erfc_scaled(x)
3700 end program test_erfc_scaled
3701 @end smallexample
3702 @end table
3703
3704
3705
3706 @node ETIME
3707 @section @code{ETIME} --- Execution time subroutine (or function)
3708 @fnindex ETIME
3709 @cindex time, elapsed
3710
3711 @table @asis
3712 @item @emph{Description}:
3713 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3714 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
3715 returns the user and system components of this time in @code{TARRAY(1)} and
3716 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3717
3718 On some systems, the underlying timings are represented using types with
3719 sufficiently small limits that overflows (wrap around) are possible, such as
3720 32-bit types. Therefore, the values returned by this intrinsic might be, or
3721 become, negative, or numerically less than previous values, during a single
3722 run of the compiled program.
3723
3724 This intrinsic is provided in both subroutine and function forms; however,
3725 only one form can be used in any given program unit.
3726
3727 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3728
3729 @multitable @columnfractions .15 .30 .60
3730 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3731 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3732 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3733 @end multitable
3734
3735 @item @emph{Standard}:
3736 GNU extension
3737
3738 @item @emph{Class}:
3739 Subroutine, function
3740
3741 @item @emph{Syntax}:
3742 @multitable @columnfractions .80
3743 @item @code{CALL ETIME(TARRAY, RESULT)}.
3744 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3745 @end multitable
3746
3747 @item @emph{Arguments}:
3748 @multitable @columnfractions .15 .70
3749 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3750 @item @var{RESULT}@tab The type shall be @code{REAL}.
3751 @end multitable
3752
3753 @item @emph{Return value}:
3754 Elapsed time in seconds since the start of program execution.
3755
3756 @item @emph{Example}:
3757 @smallexample
3758 program test_etime
3759     integer(8) :: i, j
3760     real, dimension(2) :: tarray
3761     real :: result
3762     call ETIME(tarray, result)
3763     print *, result
3764     print *, tarray(1)
3765     print *, tarray(2)
3766     do i=1,100000000    ! Just a delay
3767         j = i * i - i
3768     end do
3769     call ETIME(tarray, result)
3770     print *, result
3771     print *, tarray(1)
3772     print *, tarray(2)
3773 end program test_etime
3774 @end smallexample
3775
3776 @item @emph{See also}:
3777 @ref{CPU_TIME}
3778
3779 @end table
3780
3781
3782
3783 @node EXIT
3784 @section @code{EXIT} --- Exit the program with status.
3785 @fnindex EXIT
3786 @cindex program termination
3787 @cindex terminate program
3788
3789 @table @asis
3790 @item @emph{Description}:
3791 @code{EXIT} causes immediate termination of the program with status.  If status
3792 is omitted it returns the canonical @emph{success} for the system.  All Fortran
3793 I/O units are closed.
3794
3795 @item @emph{Standard}:
3796 GNU extension
3797
3798 @item @emph{Class}:
3799 Subroutine
3800
3801 @item @emph{Syntax}:
3802 @code{CALL EXIT([STATUS])}
3803
3804 @item @emph{Arguments}:
3805 @multitable @columnfractions .15 .70
3806 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3807 @end multitable
3808
3809 @item @emph{Return value}:
3810 @code{STATUS} is passed to the parent process on exit.
3811
3812 @item @emph{Example}:
3813 @smallexample
3814 program test_exit
3815   integer :: STATUS = 0
3816   print *, 'This program is going to exit.'
3817   call EXIT(STATUS)
3818 end program test_exit
3819 @end smallexample
3820
3821 @item @emph{See also}:
3822 @ref{ABORT}, @ref{KILL}
3823 @end table
3824
3825
3826
3827 @node EXP
3828 @section @code{EXP} --- Exponential function
3829 @fnindex EXP
3830 @fnindex DEXP
3831 @fnindex CEXP
3832 @fnindex ZEXP
3833 @fnindex CDEXP
3834 @cindex exponential function
3835 @cindex logarithmic function, inverse
3836
3837 @table @asis
3838 @item @emph{Description}:
3839 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3840
3841 @item @emph{Standard}:
3842 Fortran 77 and later, has overloads that are GNU extensions
3843
3844 @item @emph{Class}:
3845 Elemental function
3846
3847 @item @emph{Syntax}:
3848 @code{RESULT = EXP(X)}
3849
3850 @item @emph{Arguments}:
3851 @multitable @columnfractions .15 .70
3852 @item @var{X} @tab The type shall be @code{REAL} or
3853 @code{COMPLEX}.
3854 @end multitable
3855
3856 @item @emph{Return value}:
3857 The return value has same type and kind as @var{X}.
3858
3859 @item @emph{Example}:
3860 @smallexample
3861 program test_exp
3862   real :: x = 1.0
3863   x = exp(x)
3864 end program test_exp
3865 @end smallexample
3866
3867 @item @emph{Specific names}:
3868 @multitable @columnfractions .20 .20 .20 .25
3869 @item Name            @tab Argument             @tab Return type         @tab Standard
3870 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
3871 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
3872 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3873 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3874 @end multitable
3875 @end table
3876
3877
3878
3879 @node EXPONENT
3880 @section @code{EXPONENT} --- Exponent function
3881 @fnindex EXPONENT
3882 @cindex real number, exponent
3883 @cindex floating point, exponent
3884
3885 @table @asis
3886 @item @emph{Description}:
3887 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3888 is zero the value returned is zero.
3889
3890 @item @emph{Standard}:
3891 Fortran 95 and later
3892
3893 @item @emph{Class}:
3894 Elemental function
3895
3896 @item @emph{Syntax}:
3897 @code{RESULT = EXPONENT(X)}
3898
3899 @item @emph{Arguments}:
3900 @multitable @columnfractions .15 .70
3901 @item @var{X} @tab The type shall be @code{REAL}.
3902 @end multitable
3903
3904 @item @emph{Return value}:
3905 The return value is of type default @code{INTEGER}.
3906
3907 @item @emph{Example}:
3908 @smallexample
3909 program test_exponent
3910   real :: x = 1.0
3911   integer :: i
3912   i = exponent(x)
3913   print *, i
3914   print *, exponent(0.0)
3915 end program test_exponent
3916 @end smallexample
3917 @end table
3918
3919
3920
3921 @node FDATE
3922 @section @code{FDATE} --- Get the current time as a string
3923 @fnindex FDATE
3924 @cindex time, current
3925 @cindex current time
3926 @cindex date, current
3927 @cindex current date
3928
3929 @table @asis
3930 @item @emph{Description}:
3931 @code{FDATE(DATE)} returns the current date (using the same format as
3932 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3933 TIME())}.
3934
3935 This intrinsic is provided in both subroutine and function forms; however,
3936 only one form can be used in any given program unit.
3937
3938 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3939 default kind.
3940
3941 @item @emph{Standard}:
3942 GNU extension
3943
3944 @item @emph{Class}:
3945 Subroutine, function
3946
3947 @item @emph{Syntax}:
3948 @multitable @columnfractions .80
3949 @item @code{CALL FDATE(DATE)}.
3950 @item @code{DATE = FDATE()}, (not recommended).
3951 @end multitable
3952
3953 @item @emph{Arguments}:
3954 @multitable @columnfractions .15 .70
3955 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3956 default kind
3957 @end multitable
3958
3959 @item @emph{Return value}:
3960 The current date as a string.
3961
3962 @item @emph{Example}:
3963 @smallexample
3964 program test_fdate
3965     integer(8) :: i, j
3966     character(len=30) :: date
3967     call fdate(date)
3968     print *, 'Program started on ', date
3969     do i = 1, 100000000 ! Just a delay
3970         j = i * i - i
3971     end do
3972     call fdate(date)
3973     print *, 'Program ended on ', date
3974 end program test_fdate
3975 @end smallexample
3976 @end table
3977
3978
3979
3980 @node FLOAT
3981 @section @code{FLOAT} --- Convert integer to default real
3982 @fnindex FLOAT
3983 @cindex conversion, to real
3984
3985 @table @asis
3986 @item @emph{Description}:
3987 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
3988
3989 @item @emph{Standard}:
3990 Fortran 77 and later
3991
3992 @item @emph{Class}:
3993 Elemental function
3994
3995 @item @emph{Syntax}:
3996 @code{RESULT = FLOAT(A)}
3997
3998 @item @emph{Arguments}:
3999 @multitable @columnfractions .15 .70
4000 @item @var{A} @tab The type shall be @code{INTEGER}.
4001 @end multitable
4002
4003 @item @emph{Return value}:
4004 The return value is of type default @code{REAL}.
4005
4006 @item @emph{Example}:
4007 @smallexample
4008 program test_float
4009     integer :: i = 1
4010     if (float(i) /= 1.) call abort
4011 end program test_float
4012 @end smallexample
4013
4014 @item @emph{See also}:
4015 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
4016 @end table
4017
4018
4019
4020 @node FGET
4021 @section @code{FGET} --- Read a single character in stream mode from stdin
4022 @fnindex FGET
4023 @cindex read character, stream mode
4024 @cindex stream mode, read character
4025 @cindex file operation, read character
4026
4027 @table @asis
4028 @item @emph{Description}:
4029 Read a single character in stream mode from stdin by bypassing normal
4030 formatted output. Stream I/O should not be mixed with normal record-oriented
4031 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4032
4033 This intrinsic is provided in both subroutine and function forms; however,
4034 only one form can be used in any given program unit.
4035
4036 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4037 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4038 Programmers should consider the use of new stream IO feature in new code
4039 for future portability. See also @ref{Fortran 2003 status}.
4040
4041 @item @emph{Standard}:
4042 GNU extension
4043
4044 @item @emph{Class}:
4045 Subroutine, function
4046
4047 @item @emph{Syntax}:
4048 @code{CALL FGET(C [, STATUS])}
4049
4050 @item @emph{Arguments}:
4051 @multitable @columnfractions .15 .70
4052 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4053 kind.
4054 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4055 Returns 0 on success, -1 on end-of-file, and a system specific positive
4056 error code otherwise.
4057 @end multitable
4058
4059 @item @emph{Example}:
4060 @smallexample
4061 PROGRAM test_fget
4062   INTEGER, PARAMETER :: strlen = 100
4063   INTEGER :: status, i = 1
4064   CHARACTER(len=strlen) :: str = ""
4065
4066   WRITE (*,*) 'Enter text:'
4067   DO
4068     CALL fget(str(i:i), status)
4069     if (status /= 0 .OR. i > strlen) exit
4070     i = i + 1
4071   END DO
4072   WRITE (*,*) TRIM(str)
4073 END PROGRAM
4074 @end smallexample
4075
4076 @item @emph{See also}:
4077 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4078 @end table
4079
4080
4081
4082 @node FGETC
4083 @section @code{FGETC} --- Read a single character in stream mode
4084 @fnindex FGETC
4085 @cindex read character, stream mode
4086 @cindex stream mode, read character
4087 @cindex file operation, read character
4088
4089 @table @asis
4090 @item @emph{Description}:
4091 Read a single character in stream mode by bypassing normal formatted output.
4092 Stream I/O should not be mixed with normal record-oriented (formatted or
4093 unformatted) I/O on the same unit; the results are unpredictable.
4094
4095 This intrinsic is provided in both subroutine and function forms; however,
4096 only one form can be used in any given program unit.
4097
4098 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4099 with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4100 Programmers should consider the use of new stream IO feature in new code
4101 for future portability. See also @ref{Fortran 2003 status}.
4102
4103 @item @emph{Standard}:
4104 GNU extension
4105
4106 @item @emph{Class}:
4107 Subroutine, function
4108
4109 @item @emph{Syntax}:
4110 @code{CALL FGETC(UNIT, C [, STATUS])}
4111
4112 @item @emph{Arguments}:
4113 @multitable @columnfractions .15 .70
4114 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4115 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4116 kind.
4117 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4118 Returns 0 on success, -1 on end-of-file and a system specific positive
4119 error code otherwise.
4120 @end multitable
4121
4122 @item @emph{Example}:
4123 @smallexample
4124 PROGRAM test_fgetc
4125   INTEGER :: fd = 42, status
4126   CHARACTER :: c
4127
4128   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4129   DO
4130     CALL fgetc(fd, c, status)
4131     IF (status /= 0) EXIT
4132     call fput(c)
4133   END DO
4134   CLOSE(UNIT=fd)
4135 END PROGRAM
4136 @end smallexample
4137
4138 @item @emph{See also}:
4139 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4140 @end table
4141
4142
4143
4144 @node FLOOR
4145 @section @code{FLOOR} --- Integer floor function
4146 @fnindex FLOOR
4147 @cindex floor
4148 @cindex rounding, floor
4149
4150 @table @asis
4151 @item @emph{Description}:
4152 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4153
4154 @item @emph{Standard}:
4155 Fortran 95 and later
4156
4157 @item @emph{Class}:
4158 Elemental function
4159
4160 @item @emph{Syntax}:
4161 @code{RESULT = FLOOR(A [, KIND])}
4162
4163 @item @emph{Arguments}:
4164 @multitable @columnfractions .15 .70
4165 @item @var{A} @tab The type shall be @code{REAL}.
4166 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4167 expression indicating the kind parameter of the result.
4168 @end multitable
4169
4170 @item @emph{Return value}:
4171 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4172 and of default-kind @code{INTEGER} otherwise.
4173
4174 @item @emph{Example}:
4175 @smallexample
4176 program test_floor
4177     real :: x = 63.29
4178     real :: y = -63.59
4179     print *, floor(x) ! returns 63
4180     print *, floor(y) ! returns -64
4181 end program test_floor
4182 @end smallexample
4183
4184 @item @emph{See also}:
4185 @ref{CEILING}, @ref{NINT}
4186
4187 @end table
4188
4189
4190
4191 @node FLUSH
4192 @section @code{FLUSH} --- Flush I/O unit(s)
4193 @fnindex FLUSH
4194 @cindex file operation, flush
4195
4196 @table @asis
4197 @item @emph{Description}:
4198 Flushes Fortran unit(s) currently open for output. Without the optional
4199 argument, all units are flushed, otherwise just the unit specified.
4200
4201 @item @emph{Standard}:
4202 GNU extension
4203
4204 @item @emph{Class}:
4205 Subroutine
4206
4207 @item @emph{Syntax}:
4208 @code{CALL FLUSH(UNIT)}
4209
4210 @item @emph{Arguments}:
4211 @multitable @columnfractions .15 .70
4212 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4213 @end multitable
4214
4215 @item @emph{Note}:
4216 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4217 statement that should be preferred over the @code{FLUSH} intrinsic.
4218
4219 @end table
4220
4221
4222
4223 @node FNUM
4224 @section @code{FNUM} --- File number function
4225 @fnindex FNUM
4226 @cindex file operation, file number
4227
4228 @table @asis
4229 @item @emph{Description}:
4230 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4231 open Fortran I/O unit @code{UNIT}.
4232
4233 @item @emph{Standard}:
4234 GNU extension
4235
4236 @item @emph{Class}:
4237 Function
4238
4239 @item @emph{Syntax}:
4240 @code{RESULT = FNUM(UNIT)}
4241
4242 @item @emph{Arguments}:
4243 @multitable @columnfractions .15 .70
4244 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4245 @end multitable
4246
4247 @item @emph{Return value}:
4248 The return value is of type @code{INTEGER}
4249
4250 @item @emph{Example}:
4251 @smallexample
4252 program test_fnum
4253   integer :: i
4254   open (unit=10, status = "scratch")
4255   i = fnum(10)
4256   print *, i
4257   close (10)
4258 end program test_fnum
4259 @end smallexample
4260 @end table
4261
4262
4263
4264 @node FPUT
4265 @section @code{FPUT} --- Write a single character in stream mode to stdout
4266 @fnindex FPUT
4267 @cindex write character, stream mode
4268 @cindex stream mode, write character
4269 @cindex file operation, write character
4270
4271 @table @asis
4272 @item @emph{Description}:
4273 Write a single character in stream mode to stdout by bypassing normal
4274 formatted output. Stream I/O should not be mixed with normal record-oriented
4275 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4276
4277 This intrinsic is provided in both subroutine and function forms; however,
4278 only one form can be used in any given program unit.
4279
4280 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4281 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4282 Programmers should consider the use of new stream IO feature in new code
4283 for future portability. See also @ref{Fortran 2003 status}.
4284
4285 @item @emph{Standard}:
4286 GNU extension
4287
4288 @item @emph{Class}:
4289 Subroutine, function
4290
4291 @item @emph{Syntax}:
4292 @code{CALL FPUT(C [, STATUS])}
4293
4294 @item @emph{Arguments}:
4295 @multitable @columnfractions .15 .70
4296 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4297 kind.
4298 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4299 Returns 0 on success, -1 on end-of-file and a system specific positive
4300 error code otherwise.
4301 @end multitable
4302
4303 @item @emph{Example}:
4304 @smallexample
4305 PROGRAM test_fput
4306   CHARACTER(len=10) :: str = "gfortran"
4307   INTEGER :: i
4308   DO i = 1, len_trim(str)
4309     CALL fput(str(i:i))
4310   END DO
4311 END PROGRAM
4312 @end smallexample
4313
4314 @item @emph{See also}:
4315 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4316 @end table
4317
4318
4319
4320 @node FPUTC
4321 @section @code{FPUTC} --- Write a single character in stream mode
4322 @fnindex FPUTC
4323 @cindex write character, stream mode
4324 @cindex stream mode, write character
4325 @cindex file operation, write character
4326
4327 @table @asis
4328 @item @emph{Description}:
4329 Write a single character in stream mode by bypassing normal formatted
4330 output. Stream I/O should not be mixed with normal record-oriented
4331 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4332
4333 This intrinsic is provided in both subroutine and function forms; however,
4334 only one form can be used in any given program unit.
4335
4336 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4337 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4338 Programmers should consider the use of new stream IO feature in new code
4339 for future portability. See also @ref{Fortran 2003 status}.
4340
4341 @item @emph{Standard}:
4342 GNU extension
4343
4344 @item @emph{Class}:
4345 Subroutine, function
4346
4347 @item @emph{Syntax}:
4348 @code{CALL FPUTC(UNIT, C [, STATUS])}
4349
4350 @item @emph{Arguments}:
4351 @multitable @columnfractions .15 .70
4352 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4353 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4354 kind.
4355 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4356 Returns 0 on success, -1 on end-of-file and a system specific positive
4357 error code otherwise.
4358 @end multitable
4359
4360 @item @emph{Example}:
4361 @smallexample
4362 PROGRAM test_fputc
4363   CHARACTER(len=10) :: str = "gfortran"
4364   INTEGER :: fd = 42, i
4365
4366   OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4367   DO i = 1, len_trim(str)
4368     CALL fputc(fd, str(i:i))
4369   END DO
4370   CLOSE(fd)
4371 END PROGRAM
4372 @end smallexample
4373
4374 @item @emph{See also}:
4375 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4376 @end table
4377
4378
4379
4380 @node FRACTION
4381 @section @code{FRACTION} --- Fractional part of the model representation
4382 @fnindex FRACTION
4383 @cindex real number, fraction
4384 @cindex floating point, fraction
4385
4386 @table @asis
4387 @item @emph{Description}:
4388 @code{FRACTION(X)} returns the fractional part of the model
4389 representation of @code{X}.
4390
4391 @item @emph{Standard}:
4392 Fortran 95 and later
4393
4394 @item @emph{Class}:
4395 Elemental function
4396
4397 @item @emph{Syntax}:
4398 @code{Y = FRACTION(X)}
4399
4400 @item @emph{Arguments}:
4401 @multitable @columnfractions .15 .70
4402 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4403 @end multitable
4404
4405 @item @emph{Return value}:
4406 The return value is of the same type and kind as the argument.
4407 The fractional part of the model representation of @code{X} is returned;
4408 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4409
4410 @item @emph{Example}:
4411 @smallexample
4412 program test_fraction
4413   real :: x
4414   x = 178.1387e-4
4415   print *, fraction(x), x * radix(x)**(-exponent(x))
4416 end program test_fraction
4417 @end smallexample
4418
4419 @end table
4420
4421
4422
4423 @node FREE
4424 @section @code{FREE} --- Frees memory
4425 @fnindex FREE
4426 @cindex pointer, cray
4427
4428 @table @asis
4429 @item @emph{Description}:
4430 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4431 intrinsic is an extension intended to be used with Cray pointers, and is
4432 provided in GNU Fortran to allow user to compile legacy code. For
4433 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4434 @code{DEALLOCATE}.
4435
4436 @item @emph{Standard}:
4437 GNU extension
4438
4439 @item @emph{Class}:
4440 Subroutine
4441
4442 @item @emph{Syntax}:
4443 @code{CALL FREE(PTR)}
4444
4445 @item @emph{Arguments}:
4446 @multitable @columnfractions .15 .70
4447 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4448 location of the memory that should be de-allocated.
4449 @end multitable
4450
4451 @item @emph{Return value}:
4452 None
4453
4454 @item @emph{Example}:
4455 See @code{MALLOC} for an example.
4456
4457 @item @emph{See also}:
4458 @ref{MALLOC}
4459 @end table
4460
4461
4462
4463 @node FSEEK
4464 @section @code{FSEEK} --- Low level file positioning subroutine
4465 @fnindex FSEEK
4466 @cindex file operation, seek
4467 @cindex file operation, position
4468
4469 @table @asis
4470 @item @emph{Description}:
4471 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4472 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4473 if set to 1, @var{OFFSET} is taken to be relative to the current position
4474 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4475 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4476 fails silently.
4477
4478 This intrinsic routine is not fully backwards compatible with @command{g77}.
4479 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4480 @var{STATUS} variable. If FSEEK is used in old code, change
4481 @smallexample
4482   CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4483 @end smallexample
4484 to
4485 @smallexample
4486   INTEGER :: status
4487   CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4488   IF (status /= 0) GOTO label
4489 @end smallexample
4490
4491 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4492 Programmers should consider the use of new stream IO feature in new code
4493 for future portability. See also @ref{Fortran 2003 status}.
4494
4495 @item @emph{Standard}:
4496 GNU extension
4497
4498 @item @emph{Class}:
4499 Subroutine
4500
4501 @item @emph{Syntax}:
4502 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4503
4504 @item @emph{Arguments}:
4505 @multitable @columnfractions .15 .70
4506 @item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
4507 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4508 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4509 Its value shall be either 0, 1 or 2.
4510 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4511 @code{INTEGER(4)}.
4512 @end multitable
4513
4514 @item @emph{Example}:
4515 @smallexample
4516 PROGRAM test_fseek
4517   INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4518   INTEGER :: fd, offset, ierr
4519
4520   ierr   = 0
4521   offset = 5
4522   fd     = 10
4523
4524   OPEN(UNIT=fd, FILE="fseek.test")
4525   CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
4526   print *, FTELL(fd), ierr
4527
4528   CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
4529   print *, FTELL(fd), ierr
4530
4531   CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
4532   print *, FTELL(fd), ierr
4533
4534   CLOSE(UNIT=fd)
4535 END PROGRAM
4536 @end smallexample
4537
4538 @item @emph{See also}:
4539 @ref{FTELL}
4540 @end table
4541
4542
4543
4544 @node FSTAT
4545 @section @code{FSTAT} --- Get file status
4546 @fnindex FSTAT
4547 @cindex file system, file status
4548
4549 @table @asis
4550 @item @emph{Description}:
4551 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4552 already opened file is obtained.
4553
4554 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4555
4556 This intrinsic is provided in both subroutine and function forms; however,
4557 only one form can be used in any given program unit.
4558
4559 @item @emph{Standard}:
4560 GNU extension
4561
4562 @item @emph{Class}:
4563 Subroutine, function
4564
4565 @item @emph{Syntax}:
4566 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4567
4568 @item @emph{Arguments}:
4569 @multitable @columnfractions .15 .70
4570 @item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
4571 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4572 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4573 on success and a system specific error code otherwise.
4574 @end multitable
4575
4576 @item @emph{Example}:
4577 See @ref{STAT} for an example.
4578
4579 @item @emph{See also}:
4580 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4581 @end table
4582
4583
4584
4585 @node FTELL
4586 @section @code{FTELL} --- Current stream position
4587 @fnindex FTELL
4588 @cindex file operation, position
4589
4590 @table @asis
4591 @item @emph{Description}:
4592 Retrieves the current position within an open file.
4593
4594 This intrinsic is provided in both subroutine and function forms; however,
4595 only one form can be used in any given program unit.
4596
4597 @item @emph{Standard}:
4598 GNU extension
4599
4600 @item @emph{Class}:
4601 Subroutine, function
4602
4603 @item @emph{Syntax}:
4604 @multitable @columnfractions .80
4605 @item @code{CALL FTELL(UNIT, OFFSET)}
4606 @item @code{OFFSET = FTELL(UNIT)}
4607 @end multitable
4608
4609 @item @emph{Arguments}:
4610 @multitable @columnfractions .15 .70
4611 @item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
4612 @item @var{UNIT}    @tab Shall of type @code{INTEGER}.
4613 @end multitable
4614
4615 @item @emph{Return value}:
4616 In either syntax, @var{OFFSET} is set to the current offset of unit
4617 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4618
4619 @item @emph{Example}:
4620 @smallexample
4621 PROGRAM test_ftell
4622   INTEGER :: i
4623   OPEN(10, FILE="temp.dat")
4624   CALL ftell(10,i)
4625   WRITE(*,*) i
4626 END PROGRAM
4627 @end smallexample
4628
4629 @item @emph{See also}:
4630 @ref{FSEEK}
4631 @end table
4632
4633
4634
4635 @node GAMMA
4636 @section @code{GAMMA} --- Gamma function
4637 @fnindex GAMMA
4638 @fnindex DGAMMA
4639 @cindex Gamma function
4640 @cindex Factorial function
4641
4642 @table @asis
4643 @item @emph{Description}:
4644 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4645 integer values of @var{X} the Gamma function simplifies to the factorial
4646 function @math{\Gamma(x)=(x-1)!}.
4647
4648 @tex
4649 $$
4650 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4651 $$
4652 @end tex
4653
4654 @item @emph{Standard}:
4655 Fortran 2008 and later
4656
4657 @item @emph{Class}:
4658 Elemental function
4659
4660 @item @emph{Syntax}:
4661 @code{X = GAMMA(X)}
4662
4663 @item @emph{Arguments}:
4664 @multitable @columnfractions .15 .70
4665 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4666 nor a negative integer.
4667 @end multitable
4668
4669 @item @emph{Return value}:
4670 The return value is of type @code{REAL} of the same kind as @var{X}.
4671
4672 @item @emph{Example}:
4673 @smallexample
4674 program test_gamma
4675   real :: x = 1.0
4676   x = gamma(x) ! returns 1.0
4677 end program test_gamma
4678 @end smallexample
4679
4680 @item @emph{Specific names}:
4681 @multitable @columnfractions .20 .20 .20 .25
4682 @item Name             @tab Argument         @tab Return type       @tab Standard
4683 @item @code{GAMMA(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
4684 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
4685 @end multitable
4686
4687 @item @emph{See also}:
4688 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4689
4690 @end table
4691
4692
4693
4694 @node GERROR
4695 @section @code{GERROR} --- Get last system error message
4696 @fnindex GERROR
4697 @cindex system, error handling
4698
4699 @table @asis
4700 @item @emph{Description}:
4701 Returns the system error message corresponding to the last system error.
4702 This resembles the functionality of @code{strerror(3)} in C.
4703
4704 @item @emph{Standard}:
4705 GNU extension
4706
4707 @item @emph{Class}:
4708 Subroutine
4709
4710 @item @emph{Syntax}:
4711 @code{CALL GERROR(RESULT)}
4712
4713 @item @emph{Arguments}:
4714 @multitable @columnfractions .15 .70
4715 @item @var{RESULT}  @tab Shall of type @code{CHARACTER} and of default
4716 @end multitable
4717
4718 @item @emph{Example}:
4719 @smallexample
4720 PROGRAM test_gerror
4721   CHARACTER(len=100) :: msg
4722   CALL gerror(msg)
4723   WRITE(*,*) msg
4724 END PROGRAM
4725 @end smallexample
4726
4727 @item @emph{See also}:
4728 @ref{IERRNO}, @ref{PERROR}
4729 @end table
4730
4731
4732
4733 @node GETARG
4734 @section @code{GETARG} --- Get command line arguments
4735 @fnindex GETARG
4736 @cindex command-line arguments
4737 @cindex arguments, to program
4738
4739 @table @asis
4740 @item @emph{Description}:
4741 Retrieve the @var{POS}-th argument that was passed on the
4742 command line when the containing program was invoked.
4743
4744 This intrinsic routine is provided for backwards compatibility with
4745 GNU Fortran 77.  In new code, programmers should consider the use of
4746 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4747 standard.
4748
4749 @item @emph{Standard}:
4750 GNU extension
4751
4752 @item @emph{Class}:
4753 Subroutine
4754
4755 @item @emph{Syntax}:
4756 @code{CALL GETARG(POS, VALUE)}
4757
4758 @item @emph{Arguments}:
4759 @multitable @columnfractions .15 .70
4760 @item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
4761 the default integer kind; @math{@var{POS} \geq 0}
4762 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4763 kind.
4764 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4765 @end multitable
4766
4767 @item @emph{Return value}:
4768 After @code{GETARG} returns, the @var{VALUE} argument holds the
4769 @var{POS}th command line argument. If @var{VALUE} can not hold the
4770 argument, it is truncated to fit the length of @var{VALUE}. If there are
4771 less than @var{POS} arguments specified at the command line, @var{VALUE}
4772 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4773 to the name of the program (on systems that support this feature).
4774
4775 @item @emph{Example}:
4776 @smallexample
4777 PROGRAM test_getarg
4778   INTEGER :: i
4779   CHARACTER(len=32) :: arg
4780
4781   DO i = 1, iargc()
4782     CALL getarg(i, arg)
4783     WRITE (*,*) arg
4784   END DO
4785 END PROGRAM
4786 @end smallexample
4787
4788 @item @emph{See also}:
4789 GNU Fortran 77 compatibility function: @ref{IARGC}
4790
4791 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4792 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4793 @end table
4794
4795
4796
4797 @node GET_COMMAND
4798 @section @code{GET_COMMAND} --- Get the entire command line
4799 @fnindex GET_COMMAND
4800 @cindex command-line arguments
4801 @cindex arguments, to program
4802
4803 @table @asis
4804 @item @emph{Description}:
4805 Retrieve the entire command line that was used to invoke the program.
4806
4807 @item @emph{Standard}:
4808 Fortran 2003 and later
4809
4810 @item @emph{Class}:
4811 Subroutine
4812
4813 @item @emph{Syntax}:
4814 @code{CALL GET_COMMAND(COMMAND)}
4815
4816 @item @emph{Arguments}:
4817 @multitable @columnfractions .15 .70
4818 @item @var{COMMAND} @tab Shall be of type @code{CHARACTER} and of default
4819 kind.
4820 @end multitable
4821
4822 @item @emph{Return value}:
4823 Stores the entire command line that was used to invoke the program in
4824 @var{COMMAND}. If @var{COMMAND} is not large enough, the command will be
4825 truncated.
4826
4827 @item @emph{Example}:
4828 @smallexample
4829 PROGRAM test_get_command
4830   CHARACTER(len=255) :: cmd
4831   CALL get_command(cmd)
4832   WRITE (*,*) TRIM(cmd)
4833 END PROGRAM
4834 @end smallexample
4835
4836 @item @emph{See also}:
4837 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4838 @end table
4839
4840
4841
4842 @node GET_COMMAND_ARGUMENT
4843 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4844 @fnindex GET_COMMAND_ARGUMENT
4845 @cindex command-line arguments
4846 @cindex arguments, to program
4847
4848 @table @asis
4849 @item @emph{Description}:
4850 Retrieve the @var{NUMBER}-th argument that was passed on the
4851 command line when the containing program was invoked.
4852
4853 @item @emph{Standard}:
4854 Fortran 2003 and later
4855
4856 @item @emph{Class}:
4857 Subroutine
4858
4859 @item @emph{Syntax}:
4860 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4861
4862 @item @emph{Arguments}:
4863 @multitable @columnfractions .15 .70
4864 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER(4)},
4865 @math{@var{NUMBER} \geq 0}
4866 @item @var{VALUE}  @tab Shall be a scalar of type @code{CHARACTER}
4867 and of default kind.
4868 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER(4)}.
4869 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER(4)}.
4870 @end multitable
4871
4872 @item @emph{Return value}:
4873 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4874 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4875 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4876 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4877 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on systems
4878 that support this feature). The @var{LENGTH} argument contains the length of the
4879 @var{NUMBER}-th command line argument. If the argument retrival fails, @var{STATUS}
4880 is a positiv number; if @var{VALUE} contains a truncated command line argument,
4881 @var{STATUS} is -1; and otherwise the @var{STATUS} is zero.
4882
4883 @item @emph{Example}:
4884 @smallexample
4885 PROGRAM test_get_command_argument
4886   INTEGER :: i
4887   CHARACTER(len=32) :: arg
4888
4889   i = 0
4890   DO
4891     CALL get_command_argument(i, arg)
4892     IF (LEN_TRIM(arg) == 0) EXIT
4893
4894     WRITE (*,*) TRIM(arg)
4895     i = i+1
4896   END DO
4897 END PROGRAM
4898 @end smallexample
4899
4900 @item @emph{See also}:
4901 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4902 @end table
4903
4904
4905
4906 @node GETCWD
4907 @section @code{GETCWD} --- Get current working directory
4908 @fnindex GETCWD
4909 @cindex system, working directory
4910
4911 @table @asis
4912 @item @emph{Description}:
4913 Get current working directory.
4914
4915 This intrinsic is provided in both subroutine and function forms; however,
4916 only one form can be used in any given program unit.
4917
4918 @item @emph{Standard}:
4919 GNU extension
4920
4921 @item @emph{Class}:
4922 Subroutine, function
4923
4924 @item @emph{Syntax}:
4925 @code{CALL GETCWD(C [, STATUS])}
4926
4927 @item @emph{Arguments}:
4928 @multitable @columnfractions .15 .70
4929 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4930 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4931 a system specific and nonzero error code otherwise.
4932 @end multitable
4933
4934 @item @emph{Example}:
4935 @smallexample
4936 PROGRAM test_getcwd
4937   CHARACTER(len=255) :: cwd
4938   CALL getcwd(cwd)
4939   WRITE(*,*) TRIM(cwd)
4940 END PROGRAM
4941 @end smallexample
4942
4943 @item @emph{See also}:
4944 @ref{CHDIR}
4945 @end table
4946
4947
4948
4949 @node GETENV
4950 @section @code{GETENV} --- Get an environmental variable
4951 @fnindex GETENV
4952 @cindex environment variable
4953
4954 @table @asis
4955 @item @emph{Description}:
4956 Get the @var{VALUE} of the environmental variable @var{NAME}.
4957
4958 This intrinsic routine is provided for backwards compatibility with
4959 GNU Fortran 77.  In new code, programmers should consider the use of
4960 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4961 2003 standard.
4962
4963 @item @emph{Standard}:
4964 GNU extension
4965
4966 @item @emph{Class}:
4967 Subroutine
4968
4969 @item @emph{Syntax}:
4970 @code{CALL GETENV(NAME, VALUE)}
4971
4972 @item @emph{Arguments}:
4973 @multitable @columnfractions .15 .70
4974 @item @var{NAME}  @tab Shall be of type @code{CHARACTER} and of default kind.
4975 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
4976 @end multitable
4977
4978 @item @emph{Return value}:
4979 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
4980 not large enough to hold the data, it is truncated. If @var{NAME}
4981 is not set, @var{VALUE} will be filled with blanks.
4982
4983 @item @emph{Example}:
4984 @smallexample
4985 PROGRAM test_getenv
4986   CHARACTER(len=255) :: homedir
4987   CALL getenv("HOME", homedir)
4988   WRITE (*,*) TRIM(homedir)
4989 END PROGRAM
4990 @end smallexample
4991
4992 @item @emph{See also}:
4993 @ref{GET_ENVIRONMENT_VARIABLE}
4994 @end table
4995
4996
4997
4998 @node GET_ENVIRONMENT_VARIABLE
4999 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5000 @fnindex GET_ENVIRONMENT_VARIABLE
5001 @cindex environment variable
5002
5003 @table @asis
5004 @item @emph{Description}:
5005 Get the @var{VALUE} of the environmental variable @var{NAME}.
5006
5007 @item @emph{Standard}:
5008 Fortran 2003 and later
5009
5010 @item @emph{Class}:
5011 Subroutine
5012
5013 @item @emph{Syntax}:
5014 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5015
5016 @item @emph{Arguments}:
5017 @multitable @columnfractions .15 .70
5018 @item @var{NAME}      @tab Shall be a scalar of type @code{CHARACTER(1)}.
5019 @item @var{VALUE}     @tab Shall be a scalar of type @code{CHARACTER(1)}.
5020 @item @var{LENGTH}    @tab Shall be a scalar of type @code{INTEGER(4)}.
5021 @item @var{STATUS}    @tab Shall be a scalar of type @code{INTEGER(4)}.
5022 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL(4)}.
5023 @end multitable
5024
5025 @item @emph{Return value}:
5026 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5027 not large enough to hold the data, it is truncated. If @var{NAME}
5028 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5029 contains the length needed for storing the environment variable @var{NAME}
5030 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5031 but too short for the environment variable; it is 1 if the environment
5032 variable does not exist and 2 if the processor does not support environment
5033 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5034 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5035 are significant; otherwise they are not part of the environment variable
5036 name.
5037
5038 @item @emph{Example}:
5039 @smallexample
5040 PROGRAM test_getenv
5041   CHARACTER(len=255) :: homedir
5042   CALL get_environment_variable("HOME", homedir)
5043   WRITE (*,*) TRIM(homedir)
5044 END PROGRAM
5045 @end smallexample
5046 @end table
5047
5048
5049
5050 @node GETGID
5051 @section @code{GETGID} --- Group ID function
5052 @fnindex GETGID
5053 @cindex system, group id
5054
5055 @table @asis
5056 @item @emph{Description}:
5057 Returns the numerical group ID of the current process.
5058
5059 @item @emph{Standard}:
5060 GNU extension
5061
5062 @item @emph{Class}:
5063 Function
5064
5065 @item @emph{Syntax}:
5066 @code{RESULT = GETGID()}
5067
5068 @item @emph{Return value}:
5069 The return value of @code{GETGID} is an @code{INTEGER} of the default
5070 kind.
5071
5072
5073 @item @emph{Example}:
5074 See @code{GETPID} for an example.
5075
5076 @item @emph{See also}:
5077 @ref{GETPID}, @ref{GETUID}
5078 @end table
5079
5080
5081
5082 @node GETLOG
5083 @section @code{GETLOG} --- Get login name
5084 @fnindex GETLOG
5085 @cindex system, login name
5086 @cindex login name
5087
5088 @table @asis
5089 @item @emph{Description}:
5090 Gets the username under which the program is running.
5091
5092 @item @emph{Standard}:
5093 GNU extension
5094
5095 @item @emph{Class}:
5096 Subroutine
5097
5098 @item @emph{Syntax}:
5099 @code{CALL GETLOG(C)}
5100
5101 @item @emph{Arguments}:
5102 @multitable @columnfractions .15 .70
5103 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5104 @end multitable
5105
5106 @item @emph{Return value}:
5107 Stores the current user name in @var{LOGIN}.  (On systems where POSIX
5108 functions @code{geteuid} and @code{getpwuid} are not available, and
5109 the @code{getlogin} function is not implemented either, this will
5110 return a blank string.)
5111
5112 @item @emph{Example}:
5113 @smallexample
5114 PROGRAM TEST_GETLOG
5115   CHARACTER(32) :: login
5116   CALL GETLOG(login)
5117   WRITE(*,*) login
5118 END PROGRAM
5119 @end smallexample
5120
5121 @item @emph{See also}:
5122 @ref{GETUID}
5123 @end table
5124
5125
5126
5127 @node GETPID
5128 @section @code{GETPID} --- Process ID function
5129 @fnindex GETPID
5130 @cindex system, process id
5131 @cindex process id
5132
5133 @table @asis
5134 @item @emph{Description}:
5135 Returns the numerical process identifier of the current process.
5136
5137 @item @emph{Standard}:
5138 GNU extension
5139
5140 @item @emph{Class}:
5141 Function
5142
5143 @item @emph{Syntax}:
5144 @code{RESULT = GETPID()}
5145
5146 @item @emph{Return value}:
5147 The return value of @code{GETPID} is an @code{INTEGER} of the default
5148 kind.
5149
5150
5151 @item @emph{Example}:
5152 @smallexample
5153 program info
5154   print *, "The current process ID is ", getpid()
5155   print *, "Your numerical user ID is ", getuid()
5156   print *, "Your numerical group ID is ", getgid()
5157 end program info
5158 @end smallexample
5159
5160 @item @emph{See also}:
5161 @ref{GETGID}, @ref{GETUID}
5162 @end table
5163
5164
5165
5166 @node GETUID
5167 @section @code{GETUID} --- User ID function
5168 @fnindex GETUID
5169 @cindex system, user id
5170 @cindex user id
5171
5172 @table @asis
5173 @item @emph{Description}:
5174 Returns the numerical user ID of the current process.
5175
5176 @item @emph{Standard}:
5177 GNU extension
5178
5179 @item @emph{Class}:
5180 Function
5181
5182 @item @emph{Syntax}:
5183 @code{RESULT = GETUID()}
5184
5185 @item @emph{Return value}:
5186 The return value of @code{GETUID} is an @code{INTEGER} of the default
5187 kind.
5188
5189
5190 @item @emph{Example}:
5191 See @code{GETPID} for an example.
5192
5193 @item @emph{See also}:
5194 @ref{GETPID}, @ref{GETLOG}
5195 @end table
5196
5197
5198
5199 @node GMTIME
5200 @section @code{GMTIME} --- Convert time to GMT info
5201 @fnindex GMTIME
5202 @cindex time, conversion to GMT info
5203
5204 @table @asis
5205 @item @emph{Description}:
5206 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5207 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5208 to the UTC time zone (Universal Coordinated Time, also known in some
5209 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5210
5211 @item @emph{Standard}:
5212 GNU extension
5213
5214 @item @emph{Class}:
5215 Subroutine
5216
5217 @item @emph{Syntax}:
5218 @code{CALL GMTIME(TIME, VALUES)}
5219
5220 @item @emph{Arguments}:
5221 @multitable @columnfractions .15 .70
5222 @item @var{TIME}   @tab An @code{INTEGER} scalar expression
5223 corresponding to a system time, with @code{INTENT(IN)}.
5224 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5225 with @code{INTENT(OUT)}.
5226 @end multitable
5227
5228 @item @emph{Return value}:
5229 The elements of @var{VALUES} are assigned as follows:
5230 @enumerate
5231 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5232 seconds
5233 @item Minutes after the hour, range 0--59
5234 @item Hours past midnight, range 0--23
5235 @item Day of month, range 0--31
5236 @item Number of months since January, range 0--12
5237 @item Years since 1900
5238 @item Number of days since Sunday, range 0--6
5239 @item Days since January 1
5240 @item Daylight savings indicator: positive if daylight savings is in
5241 effect, zero if not, and negative if the information is not available.
5242 @end enumerate
5243
5244 @item @emph{See also}:
5245 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5246
5247 @end table
5248
5249
5250
5251 @node HOSTNM
5252 @section @code{HOSTNM} --- Get system host name
5253 @fnindex HOSTNM
5254 @cindex system, host name
5255
5256 @table @asis
5257 @item @emph{Description}:
5258 Retrieves the host name of the system on which the program is running.
5259
5260 This intrinsic is provided in both subroutine and function forms; however,
5261 only one form can be used in any given program unit.
5262
5263 @item @emph{Standard}:
5264 GNU extension
5265
5266 @item @emph{Class}:
5267 Subroutine, function
5268
5269 @item @emph{Syntax}:
5270 @multitable @columnfractions .80
5271 @item @code{CALL HOSTNM(C [, STATUS])}
5272 @item @code{STATUS = HOSTNM(NAME)}
5273 @end multitable
5274
5275 @item @emph{Arguments}:
5276 @multitable @columnfractions .15 .70
5277 @item @var{C}    @tab Shall of type @code{CHARACTER} and of default kind.
5278 @item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
5279 Returns 0 on success, or a system specific error code otherwise.
5280 @end multitable
5281
5282 @item @emph{Return value}:
5283 In either syntax, @var{NAME} is set to the current hostname if it can
5284 be obtained, or to a blank string otherwise.
5285
5286 @end table
5287
5288
5289
5290 @node HUGE
5291 @section @code{HUGE} --- Largest number of a kind
5292 @fnindex HUGE
5293 @cindex limits, largest number
5294 @cindex model representation, largest number
5295
5296 @table @asis
5297 @item @emph{Description}:
5298 @code{HUGE(X)} returns the largest number that is not an infinity in
5299 the model of the type of @code{X}.
5300
5301 @item @emph{Standard}:
5302 Fortran 95 and later
5303
5304 @item @emph{Class}:
5305 Inquiry function
5306
5307 @item @emph{Syntax}:
5308 @code{RESULT = HUGE(X)}
5309
5310 @item @emph{Arguments}:
5311 @multitable @columnfractions .15 .70
5312 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5313 @end multitable
5314
5315 @item @emph{Return value}:
5316 The return value is of the same type and kind as @var{X}
5317
5318 @item @emph{Example}:
5319 @smallexample
5320 program test_huge_tiny
5321   print *, huge(0), huge(0.0), huge(0.0d0)
5322   print *, tiny(0.0), tiny(0.0d0)
5323 end program test_huge_tiny
5324 @end smallexample
5325 @end table
5326
5327
5328
5329 @node HYPOT
5330 @section @code{HYPOT} --- Euclidean distance function
5331 @fnindex HYPOT
5332 @cindex Euclidean distance
5333
5334 @table @asis
5335 @item @emph{Description}:
5336 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5337 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5338
5339 @item @emph{Standard}:
5340 Fortran 2008 and later
5341
5342 @item @emph{Class}:
5343 Elemental function
5344
5345 @item @emph{Syntax}:
5346 @code{RESULT = HYPOT(X, Y)}
5347
5348 @item @emph{Arguments}:
5349 @multitable @columnfractions .15 .70
5350 @item @var{X} @tab The type shall be @code{REAL}.
5351 @item @var{Y} @tab The type and kind type parameter shall be the same as
5352 @var{X}.
5353 @end multitable
5354
5355 @item @emph{Return value}:
5356 The return value has the same type and kind type parameter as @var{X}.
5357
5358 @item @emph{Example}:
5359 @smallexample
5360 program test_hypot
5361   real(4) :: x = 1.e0_4, y = 0.5e0_4
5362   x = hypot(x,y)
5363 end program test_hypot
5364 @end smallexample
5365 @end table
5366
5367
5368
5369 @node IACHAR
5370 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5371 @fnindex IACHAR
5372 @cindex @acronym{ASCII} collating sequence
5373 @cindex collating sequence, @acronym{ASCII}
5374 @cindex conversion, to integer
5375
5376 @table @asis
5377 @item @emph{Description}:
5378 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5379 in the first character position of @code{C}.
5380
5381 @item @emph{Standard}:
5382 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5383
5384 @item @emph{Class}:
5385 Elemental function
5386
5387 @item @emph{Syntax}:
5388 @code{RESULT = IACHAR(C [, KIND])}
5389
5390 @item @emph{Arguments}:
5391 @multitable @columnfractions .15 .70
5392 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5393 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5394 expression indicating the kind parameter of the result.
5395 @end multitable
5396
5397 @item @emph{Return value}:
5398 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5399 @var{KIND} is absent, the return value is of default integer kind.
5400
5401 @item @emph{Example}:
5402 @smallexample
5403 program test_iachar
5404   integer i
5405   i = iachar(' ')
5406 end program test_iachar
5407 @end smallexample
5408
5409 @item @emph{Note}:
5410 See @ref{ICHAR} for a discussion of converting between numerical values
5411 and formatted string representations.
5412
5413 @item @emph{See also}:
5414 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5415
5416 @end table
5417
5418
5419
5420 @node IAND
5421 @section @code{IAND} --- Bitwise logical and
5422 @fnindex IAND
5423 @cindex bitwise logical and
5424 @cindex logical and, bitwise
5425
5426 @table @asis
5427 @item @emph{Description}:
5428 Bitwise logical @code{AND}.
5429
5430 @item @emph{Standard}:
5431 Fortran 95 and later
5432
5433 @item @emph{Class}:
5434 Elemental function
5435
5436 @item @emph{Syntax}:
5437 @code{RESULT = IAND(I, J)}
5438
5439 @item @emph{Arguments}:
5440 @multitable @columnfractions .15 .70
5441 @item @var{I} @tab The type shall be @code{INTEGER}.
5442 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5443 kind as @var{I}.  (As a GNU extension, different kinds are also
5444 permitted.)
5445 @end multitable
5446
5447 @item @emph{Return value}:
5448 The return type is @code{INTEGER}, of the same kind as the
5449 arguments.  (If the argument kinds differ, it is of the same kind as
5450 the larger argument.)
5451
5452 @item @emph{Example}:
5453 @smallexample
5454 PROGRAM test_iand
5455   INTEGER :: a, b
5456   DATA a / Z'F' /, b / Z'3' /
5457   WRITE (*,*) IAND(a, b)
5458 END PROGRAM
5459 @end smallexample
5460
5461 @item @emph{See also}:
5462 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5463
5464 @end table
5465
5466
5467
5468 @node IARGC
5469 @section @code{IARGC} --- Get the number of command line arguments
5470 @fnindex IARGC
5471 @cindex command-line arguments
5472 @cindex command-line arguments, number of
5473 @cindex arguments, to program
5474
5475 @table @asis
5476 @item @emph{Description}:
5477 @code{IARGC()} returns the number of arguments passed on the
5478 command line when the containing program was invoked.
5479
5480 This intrinsic routine is provided for backwards compatibility with
5481 GNU Fortran 77.  In new code, programmers should consider the use of
5482 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5483 standard.
5484
5485 @item @emph{Standard}:
5486 GNU extension
5487
5488 @item @emph{Class}:
5489 Function
5490
5491 @item @emph{Syntax}:
5492 @code{RESULT = IARGC()}
5493
5494 @item @emph{Arguments}:
5495 None.
5496
5497 @item @emph{Return value}:
5498 The number of command line arguments, type @code{INTEGER(4)}.
5499
5500 @item @emph{Example}:
5501 See @ref{GETARG}
5502
5503 @item @emph{See also}:
5504 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5505
5506 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5507 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5508 @end table
5509
5510
5511
5512 @node IBCLR
5513 @section @code{IBCLR} --- Clear bit
5514 @fnindex IBCLR
5515 @cindex bits, unset
5516 @cindex bits, clear
5517
5518 @table @asis
5519 @item @emph{Description}:
5520 @code{IBCLR} returns the value of @var{I} with the bit at position
5521 @var{POS} set to zero.
5522
5523 @item @emph{Standard}:
5524 Fortran 95 and later
5525
5526 @item @emph{Class}:
5527 Elemental function
5528
5529 @item @emph{Syntax}:
5530 @code{RESULT = IBCLR(I, POS)}
5531
5532 @item @emph{Arguments}:
5533 @multitable @columnfractions .15 .70
5534 @item @var{I} @tab The type shall be @code{INTEGER}.
5535 @item @var{POS} @tab The type shall be @code{INTEGER}.
5536 @end multitable
5537
5538 @item @emph{Return value}:
5539 The return value is of type @code{INTEGER} and of the same kind as
5540 @var{I}.
5541
5542 @item @emph{See also}:
5543 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5544
5545 @end table
5546
5547
5548
5549 @node IBITS
5550 @section @code{IBITS} --- Bit extraction
5551 @fnindex IBITS
5552 @cindex bits, get
5553 @cindex bits, extract
5554
5555 @table @asis
5556 @item @emph{Description}:
5557 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5558 starting from bit position @var{POS} and extending left for @var{LEN}
5559 bits.  The result is right-justified and the remaining bits are
5560 zeroed.  The value of @code{POS+LEN} must be less than or equal to the
5561 value @code{BIT_SIZE(I)}.
5562
5563 @item @emph{Standard}:
5564 Fortran 95 and later
5565
5566 @item @emph{Class}:
5567 Elemental function
5568
5569 @item @emph{Syntax}:
5570 @code{RESULT = IBITS(I, POS, LEN)}
5571
5572 @item @emph{Arguments}:
5573 @multitable @columnfractions .15 .70
5574 @item @var{I}   @tab The type shall be @code{INTEGER}.
5575 @item @var{POS} @tab The type shall be @code{INTEGER}.
5576 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5577 @end multitable
5578
5579 @item @emph{Return value}:
5580 The return value is of type @code{INTEGER} and of the same kind as
5581 @var{I}.
5582
5583 @item @emph{See also}:
5584 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5585 @end table
5586
5587
5588
5589 @node IBSET
5590 @section @code{IBSET} --- Set bit
5591 @fnindex IBSET
5592 @cindex bits, set
5593
5594 @table @asis
5595 @item @emph{Description}:
5596 @code{IBSET} returns the value of @var{I} with the bit at position
5597 @var{POS} set to one.
5598
5599 @item @emph{Standard}:
5600 Fortran 95 and later
5601
5602 @item @emph{Class}:
5603 Elemental function
5604
5605 @item @emph{Syntax}:
5606 @code{RESULT = IBSET(I, POS)}
5607
5608 @item @emph{Arguments}:
5609 @multitable @columnfractions .15 .70
5610 @item @var{I} @tab The type shall be @code{INTEGER}.
5611 @item @var{POS} @tab The type shall be @code{INTEGER}.
5612 @end multitable
5613
5614 @item @emph{Return value}:
5615 The return value is of type @code{INTEGER} and of the same kind as
5616 @var{I}.
5617
5618 @item @emph{See also}:
5619 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5620
5621 @end table
5622
5623
5624
5625 @node ICHAR
5626 @section @code{ICHAR} --- Character-to-integer conversion function
5627 @fnindex ICHAR
5628 @cindex conversion, to integer
5629
5630 @table @asis
5631 @item @emph{Description}:
5632 @code{ICHAR(C)} returns the code for the character in the first character
5633 position of @code{C} in the system's native character set.
5634 The correspondence between characters and their codes is not necessarily
5635 the same across different GNU Fortran implementations.
5636
5637 @item @emph{Standard}:
5638 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5639
5640 @item @emph{Class}:
5641 Elemental function
5642
5643 @item @emph{Syntax}:
5644 @code{RESULT = ICHAR(C [, KIND])}
5645
5646 @item @emph{Arguments}:
5647 @multitable @columnfractions .15 .70
5648 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5649 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5650 expression indicating the kind parameter of the result.
5651 @end multitable
5652
5653 @item @emph{Return value}:
5654 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5655 @var{KIND} is absent, the return value is of default integer kind.
5656
5657 @item @emph{Example}:
5658 @smallexample
5659 program test_ichar
5660   integer i
5661   i = ichar(' ')
5662 end program test_ichar
5663 @end smallexample
5664
5665 @item @emph{Note}:
5666 No intrinsic exists to convert between a numeric value and a formatted
5667 character string representation -- for instance, given the
5668 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5669 @code{REAL} value with the value 154, or vice versa. Instead, this
5670 functionality is provided by internal-file I/O, as in the following
5671 example:
5672 @smallexample
5673 program read_val
5674   integer value
5675   character(len=10) string, string2
5676   string = '154'
5677
5678   ! Convert a string to a numeric value
5679   read (string,'(I10)') value
5680   print *, value
5681
5682   ! Convert a value to a formatted string
5683   write (string2,'(I10)') value
5684   print *, string2
5685 end program read_val
5686 @end smallexample
5687
5688 @item @emph{See also}:
5689 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5690
5691 @end table
5692
5693
5694
5695 @node IDATE
5696 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5697 @fnindex IDATE
5698 @cindex date, current
5699 @cindex current date
5700
5701 @table @asis
5702 @item @emph{Description}:
5703 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5704 current local time. The day (in the range 1-31), month (in the range 1-12),
5705 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5706 The year has four significant digits.
5707
5708 @item @emph{Standard}:
5709 GNU extension
5710
5711 @item @emph{Class}:
5712 Subroutine
5713
5714 @item @emph{Syntax}:
5715 @code{CALL IDATE(VALUES)}
5716
5717 @item @emph{Arguments}:
5718 @multitable @columnfractions .15 .70
5719 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5720 the kind shall be the default integer kind.
5721 @end multitable
5722
5723 @item @emph{Return value}:
5724 Does not return.
5725
5726 @item @emph{Example}:
5727 @smallexample
5728 program test_idate
5729   integer, dimension(3) :: tarray
5730   call idate(tarray)
5731   print *, tarray(1)
5732   print *, tarray(2)
5733   print *, tarray(3)
5734 end program test_idate
5735 @end smallexample
5736 @end table
5737
5738
5739
5740 @node IEOR
5741 @section @code{IEOR} --- Bitwise logical exclusive or
5742 @fnindex IEOR
5743 @cindex bitwise logical exclusive or
5744 @cindex logical exclusive or, bitwise
5745
5746 @table @asis
5747 @item @emph{Description}:
5748 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5749 @var{J}.
5750
5751 @item @emph{Standard}:
5752 Fortran 95 and later
5753
5754 @item @emph{Class}:
5755 Elemental function
5756
5757 @item @emph{Syntax}:
5758 @code{RESULT = IEOR(I, J)}
5759
5760 @item @emph{Arguments}:
5761 @multitable @columnfractions .15 .70
5762 @item @var{I} @tab The type shall be @code{INTEGER}.
5763 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5764 kind as @var{I}.  (As a GNU extension, different kinds are also
5765 permitted.)
5766 @end multitable
5767
5768 @item @emph{Return value}:
5769 The return type is @code{INTEGER}, of the same kind as the
5770 arguments.  (If the argument kinds differ, it is of the same kind as
5771 the larger argument.)
5772
5773 @item @emph{See also}:
5774 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5775 @end table
5776
5777
5778
5779 @node IERRNO
5780 @section @code{IERRNO} --- Get the last system error number
5781 @fnindex IERRNO
5782 @cindex system, error handling
5783
5784 @table @asis
5785 @item @emph{Description}:
5786 Returns the last system error number, as given by the C @code{errno()}
5787 function.
5788
5789 @item @emph{Standard}:
5790 GNU extension
5791
5792 @item @emph{Class}:
5793 Function
5794
5795 @item @emph{Syntax}:
5796 @code{RESULT = IERRNO()}
5797
5798 @item @emph{Arguments}:
5799 None.
5800
5801 @item @emph{Return value}:
5802 The return value is of type @code{INTEGER} and of the default integer
5803 kind.
5804
5805 @item @emph{See also}:
5806 @ref{PERROR}
5807 @end table
5808
5809
5810
5811 @node INDEX intrinsic
5812 @section @code{INDEX} --- Position of a substring within a string
5813 @fnindex INDEX
5814 @cindex substring position
5815 @cindex string, find substring
5816
5817 @table @asis
5818 @item @emph{Description}:
5819 Returns the position of the start of the first occurrence of string
5820 @var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
5821 @var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
5822 the @var{BACK} argument is present and true, the return value is the
5823 start of the last occurrence rather than the first.
5824
5825 @item @emph{Standard}:
5826 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5827
5828 @item @emph{Class}:
5829 Elemental function
5830
5831 @item @emph{Syntax}:
5832 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5833
5834 @item @emph{Arguments}:
5835 @multitable @columnfractions .15 .70
5836 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5837 @code{INTENT(IN)}
5838 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5839 @code{INTENT(IN)}
5840 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5841 @code{INTENT(IN)}
5842 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5843 expression indicating the kind parameter of the result.
5844 @end multitable
5845
5846 @item @emph{Return value}:
5847 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5848 @var{KIND} is absent, the return value is of default integer kind.
5849
5850 @item @emph{See also}:
5851 @ref{SCAN}, @ref{VERIFY}
5852 @end table
5853
5854
5855
5856 @node INT
5857 @section @code{INT} --- Convert to integer type
5858 @fnindex INT
5859 @fnindex IFIX
5860 @fnindex IDINT
5861 @cindex conversion, to integer
5862
5863 @table @asis
5864 @item @emph{Description}:
5865 Convert to integer type
5866
5867 @item @emph{Standard}:
5868 Fortran 77 and later
5869
5870 @item @emph{Class}:
5871 Elemental function
5872
5873 @item @emph{Syntax}:
5874 @code{RESULT = INT(A [, KIND))}
5875
5876 @item @emph{Arguments}:
5877 @multitable @columnfractions .15 .70
5878 @item @var{A}    @tab Shall be of type @code{INTEGER},
5879 @code{REAL}, or @code{COMPLEX}.
5880 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5881 expression indicating the kind parameter of the result.
5882 @end multitable
5883
5884 @item @emph{Return value}:
5885 These functions return a @code{INTEGER} variable or array under
5886 the following rules:
5887
5888 @table @asis
5889 @item (A)
5890 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5891 @item (B)
5892 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5893 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5894 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5895 @item (C)
5896 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5897 @end table
5898
5899 @item @emph{Example}:
5900 @smallexample
5901 program test_int
5902   integer :: i = 42
5903   complex :: z = (-3.7, 1.0)
5904   print *, int(i)
5905   print *, int(z), int(z,8)
5906 end program
5907 @end smallexample
5908
5909 @item @emph{Specific names}:
5910 @multitable @columnfractions .20 .20 .20 .25
5911 @item Name             @tab Argument            @tab Return type       @tab Standard
5912 @item @code{IFIX(A)}   @tab @code{REAL(4) A}    @tab @code{INTEGER}    @tab Fortran 77 and later
5913 @item @code{IDINT(A)}  @tab @code{REAL(8) A}    @tab @code{INTEGER}    @tab Fortran 77 and later
5914 @end multitable
5915
5916 @end table
5917
5918
5919
5920 @node INT2
5921 @section @code{INT2} --- Convert to 16-bit integer type
5922 @fnindex INT2
5923 @fnindex SHORT
5924 @cindex conversion, to integer
5925
5926 @table @asis
5927 @item @emph{Description}:
5928 Convert to a @code{KIND=2} integer type. This is equivalent to the
5929 standard @code{INT} intrinsic with an optional argument of
5930 @code{KIND=2}, and is only included for backwards compatibility.
5931
5932 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5933
5934 @item @emph{Standard}:
5935 GNU extension
5936
5937 @item @emph{Class}:
5938 Elemental function
5939
5940 @item @emph{Syntax}:
5941 @code{RESULT = INT2(A)}
5942
5943 @item @emph{Arguments}:
5944 @multitable @columnfractions .15 .70
5945 @item @var{A}    @tab Shall be of type @code{INTEGER},
5946 @code{REAL}, or @code{COMPLEX}.
5947 @end multitable
5948
5949 @item @emph{Return value}:
5950 The return value is a @code{INTEGER(2)} variable.
5951
5952 @item @emph{See also}:
5953 @ref{INT}, @ref{INT8}, @ref{LONG}
5954 @end table
5955
5956
5957
5958 @node INT8
5959 @section @code{INT8} --- Convert to 64-bit integer type
5960 @fnindex INT8
5961 @cindex conversion, to integer
5962
5963 @table @asis
5964 @item @emph{Description}:
5965 Convert to a @code{KIND=8} integer type. This is equivalent to the
5966 standard @code{INT} intrinsic with an optional argument of
5967 @code{KIND=8}, and is only included for backwards compatibility.
5968
5969 @item @emph{Standard}:
5970 GNU extension
5971
5972 @item @emph{Class}:
5973 Elemental function
5974
5975 @item @emph{Syntax}:
5976 @code{RESULT = INT8(A)}
5977
5978 @item @emph{Arguments}:
5979 @multitable @columnfractions .15 .70
5980 @item @var{A}    @tab Shall be of type @code{INTEGER},
5981 @code{REAL}, or @code{COMPLEX}.
5982 @end multitable
5983
5984 @item @emph{Return value}:
5985 The return value is a @code{INTEGER(8)} variable.
5986
5987 @item @emph{See also}:
5988 @ref{INT}, @ref{INT2}, @ref{LONG}
5989 @end table
5990
5991
5992
5993 @node IOR
5994 @section @code{IOR} --- Bitwise logical or
5995 @fnindex IOR
5996 @cindex bitwise logical or
5997 @cindex logical or, bitwise
5998
5999 @table @asis
6000 @item @emph{Description}:
6001 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6002 @var{J}.
6003
6004 @item @emph{Standard}:
6005 Fortran 95 and later
6006
6007 @item @emph{Class}:
6008 Elemental function
6009
6010 @item @emph{Syntax}:
6011 @code{RESULT = IOR(I, J)}
6012
6013 @item @emph{Arguments}:
6014 @multitable @columnfractions .15 .70
6015 @item @var{I} @tab The type shall be @code{INTEGER}.
6016 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6017 kind as @var{I}.  (As a GNU extension, different kinds are also
6018 permitted.)
6019 @end multitable
6020
6021 @item @emph{Return value}:
6022 The return type is @code{INTEGER}, of the same kind as the
6023 arguments.  (If the argument kinds differ, it is of the same kind as
6024 the larger argument.)
6025
6026 @item @emph{See also}:
6027 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6028 @end table
6029
6030
6031
6032 @node IRAND
6033 @section @code{IRAND} --- Integer pseudo-random number
6034 @fnindex IRAND
6035 @cindex random number generation
6036
6037 @table @asis
6038 @item @emph{Description}:
6039 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6040 distribution between 0 and a system-dependent limit (which is in most
6041 cases 2147483647). If @var{FLAG} is 0, the next number
6042 in the current sequence is returned; if @var{FLAG} is 1, the generator
6043 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6044 it is used as a new seed with @code{SRAND}.
6045
6046 This intrinsic routine is provided for backwards compatibility with
6047 GNU Fortran 77. It implements a simple modulo generator as provided
6048 by @command{g77}. For new code, one should consider the use of
6049 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6050
6051 @item @emph{Standard}:
6052 GNU extension
6053
6054 @item @emph{Class}:
6055 Function
6056
6057 @item @emph{Syntax}:
6058 @code{RESULT = IRAND(I)}
6059
6060 @item @emph{Arguments}:
6061 @multitable @columnfractions .15 .70
6062 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6063 @end multitable
6064
6065 @item @emph{Return value}:
6066 The return value is of @code{INTEGER(kind=4)} type.
6067
6068 @item @emph{Example}:
6069 @smallexample
6070 program test_irand
6071   integer,parameter :: seed = 86456
6072
6073   call srand(seed)
6074   print *, irand(), irand(), irand(), irand()
6075   print *, irand(seed), irand(), irand(), irand()
6076 end program test_irand
6077 @end smallexample
6078
6079 @end table
6080
6081
6082
6083 @node IS_IOSTAT_END
6084 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6085 @fnindex IS_IOSTAT_END
6086 @cindex IOSTAT, end of file
6087
6088 @table @asis
6089 @item @emph{Description}:
6090 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6091 status ``end of file''. The function is equivalent to comparing the variable
6092 with the @code{IOSTAT_END} parameter of the intrinsic module
6093 @code{ISO_FORTRAN_ENV}.
6094
6095 @item @emph{Standard}:
6096 Fortran 2003 and later
6097
6098 @item @emph{Class}:
6099 Elemental function
6100
6101 @item @emph{Syntax}:
6102 @code{RESULT = IS_IOSTAT_END(I)}
6103
6104 @item @emph{Arguments}:
6105 @multitable @columnfractions .15 .70
6106 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6107 @end multitable
6108
6109 @item @emph{Return value}:
6110 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6111 @var{I} has the value which indicates an end of file condition for
6112 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6113
6114 @item @emph{Example}:
6115 @smallexample
6116 PROGRAM iostat
6117   IMPLICIT NONE
6118   INTEGER :: stat, i
6119   OPEN(88, FILE='test.dat')
6120   READ(88, *, IOSTAT=stat) i
6121   IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6122 END PROGRAM
6123 @end smallexample
6124 @end table
6125
6126
6127
6128 @node IS_IOSTAT_EOR
6129 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6130 @fnindex IS_IOSTAT_EOR
6131 @cindex IOSTAT, end of record
6132
6133 @table @asis
6134 @item @emph{Description}:
6135 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6136 status ``end of record''. The function is equivalent to comparing the
6137 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6138 @code{ISO_FORTRAN_ENV}.
6139
6140 @item @emph{Standard}:
6141 Fortran 2003 and later
6142
6143 @item @emph{Class}:
6144 Elemental function
6145
6146 @item @emph{Syntax}:
6147 @code{RESULT = IS_IOSTAT_EOR(I)}
6148
6149 @item @emph{Arguments}:
6150 @multitable @columnfractions .15 .70
6151 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6152 @end multitable
6153
6154 @item @emph{Return value}:
6155 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6156 @var{I} has the value which indicates an end of file condition for
6157 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6158
6159 @item @emph{Example}:
6160 @smallexample
6161 PROGRAM iostat
6162   IMPLICIT NONE
6163   INTEGER :: stat, i(50)
6164   OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6165   READ(88, IOSTAT=stat) i
6166   IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6167 END PROGRAM
6168 @end smallexample
6169 @end table
6170
6171
6172
6173 @node ISATTY
6174 @section @code{ISATTY} --- Whether a unit is a terminal device.
6175 @fnindex ISATTY
6176 @cindex system, terminal
6177
6178 @table @asis
6179 @item @emph{Description}:
6180 Determine whether a unit is connected to a terminal device.
6181
6182 @item @emph{Standard}:
6183 GNU extension
6184
6185 @item @emph{Class}:
6186 Function
6187
6188 @item @emph{Syntax}:
6189 @code{RESULT = ISATTY(UNIT)}
6190
6191 @item @emph{Arguments}:
6192 @multitable @columnfractions .15 .70
6193 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6194 @end multitable
6195
6196 @item @emph{Return value}:
6197 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6198 device, @code{.FALSE.} otherwise.
6199
6200 @item @emph{Example}:
6201 @smallexample
6202 PROGRAM test_isatty
6203   INTEGER(kind=1) :: unit
6204   DO unit = 1, 10
6205     write(*,*) isatty(unit=unit)
6206   END DO
6207 END PROGRAM
6208 @end smallexample
6209 @item @emph{See also}:
6210 @ref{TTYNAM}
6211 @end table
6212
6213
6214
6215 @node ISHFT
6216 @section @code{ISHFT} --- Shift bits
6217 @fnindex ISHFT
6218 @cindex bits, shift
6219
6220 @table @asis
6221 @item @emph{Description}:
6222 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6223 bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
6224 zero corresponds to a left shift, a value of zero corresponds to no
6225 shift, and a value less than zero corresponds to a right shift.  If the
6226 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6227 value is undefined.  Bits shifted out from the left end or right end are
6228 lost; zeros are shifted in from the opposite end.
6229
6230 @item @emph{Standard}:
6231 Fortran 95 and later
6232
6233 @item @emph{Class}:
6234 Elemental function
6235
6236 @item @emph{Syntax}:
6237 @code{RESULT = ISHFT(I, SHIFT)}
6238
6239 @item @emph{Arguments}:
6240 @multitable @columnfractions .15 .70
6241 @item @var{I} @tab The type shall be @code{INTEGER}.
6242 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6243 @end multitable
6244
6245 @item @emph{Return value}:
6246 The return value is of type @code{INTEGER} and of the same kind as
6247 @var{I}.
6248
6249 @item @emph{See also}:
6250 @ref{ISHFTC}
6251 @end table
6252
6253
6254
6255 @node ISHFTC
6256 @section @code{ISHFTC} --- Shift bits circularly
6257 @fnindex ISHFTC
6258 @cindex bits, shift circular
6259
6260 @table @asis
6261 @item @emph{Description}:
6262 @code{ISHFTC} returns a value corresponding to @var{I} with the
6263 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6264 is, bits shifted out one end are shifted into the opposite end.  A value
6265 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6266 zero corresponds to no shift, and a value less than zero corresponds to
6267 a right shift.  The absolute value of @var{SHIFT} must be less than
6268 @var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
6269 equivalent to @code{BIT_SIZE(I)}.
6270
6271 @item @emph{Standard}:
6272 Fortran 95 and later
6273
6274 @item @emph{Class}:
6275 Elemental function
6276
6277 @item @emph{Syntax}:
6278 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6279
6280 @item @emph{Arguments}:
6281 @multitable @columnfractions .15 .70
6282 @item @var{I} @tab The type shall be @code{INTEGER}.
6283 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6284 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6285 the value must be greater than zero and less than or equal to
6286 @code{BIT_SIZE(I)}.
6287 @end multitable
6288
6289 @item @emph{Return value}:
6290 The return value is of type @code{INTEGER} and of the same kind as
6291 @var{I}.
6292
6293 @item @emph{See also}:
6294 @ref{ISHFT}
6295 @end table
6296
6297
6298
6299 @node ISNAN
6300 @section @code{ISNAN} --- Test for a NaN
6301 @fnindex ISNAN
6302 @cindex IEEE, ISNAN
6303
6304 @table @asis
6305 @item @emph{Description}:
6306 @code{ISNAN} tests whether a floating-point value is an IEEE
6307 Not-a-Number (NaN).
6308 @item @emph{Standard}:
6309 GNU extension
6310
6311 @item @emph{Class}:
6312 Elemental function
6313
6314 @item @emph{Syntax}:
6315 @code{ISNAN(X)}
6316
6317 @item @emph{Arguments}:
6318 @multitable @columnfractions .15 .70
6319 @item @var{X} @tab Variable of the type @code{REAL}.
6320
6321 @end multitable
6322
6323 @item @emph{Return value}:
6324 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6325 if @var{X} is a NaN and @code{FALSE} otherwise.
6326
6327 @item @emph{Example}:
6328 @smallexample
6329 program test_nan
6330   implicit none
6331   real :: x
6332   x = -1.0
6333   x = sqrt(x)
6334   if (isnan(x)) stop '"x" is a NaN'
6335 end program test_nan
6336 @end smallexample
6337 @end table
6338
6339
6340
6341 @node ITIME
6342 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6343 @fnindex ITIME
6344 @cindex time, current
6345 @cindex current time
6346
6347 @table @asis
6348 @item @emph{Description}:
6349 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6350 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6351 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6352 respectively.
6353
6354 @item @emph{Standard}:
6355 GNU extension
6356
6357 @item @emph{Class}:
6358 Subroutine
6359
6360 @item @emph{Syntax}:
6361 @code{CALL ITIME(VALUES)}
6362
6363 @item @emph{Arguments}:
6364 @multitable @columnfractions .15 .70
6365 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6366 and the kind shall be the default integer kind.
6367 @end multitable
6368
6369 @item @emph{Return value}:
6370 Does not return.
6371
6372
6373 @item @emph{Example}:
6374 @smallexample
6375 program test_itime
6376   integer, dimension(3) :: tarray
6377   call itime(tarray)
6378   print *, tarray(1)
6379   print *, tarray(2)
6380   print *, tarray(3)
6381 end program test_itime
6382 @end smallexample
6383 @end table
6384
6385
6386
6387 @node KILL
6388 @section @code{KILL} --- Send a signal to a process
6389 @fnindex KILL
6390
6391 @table @asis
6392 @item @emph{Description}:
6393 @item @emph{Standard}:
6394 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6395 See @code{kill(2)}.
6396
6397 This intrinsic is provided in both subroutine and function forms; however,
6398 only one form can be used in any given program unit.
6399
6400 @item @emph{Class}:
6401 Subroutine, function
6402
6403 @item @emph{Syntax}:
6404 @code{CALL KILL(C, VALUE [, STATUS])}
6405
6406 @item @emph{Arguments}:
6407 @multitable @columnfractions .15 .70
6408 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6409 @code{INTENT(IN)}
6410 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6411 @code{INTENT(IN)}
6412 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6413 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6414 otherwise.
6415 @end multitable
6416
6417 @item @emph{See also}:
6418 @ref{ABORT}, @ref{EXIT}
6419 @end table
6420
6421
6422
6423 @node KIND
6424 @section @code{KIND} --- Kind of an entity
6425 @fnindex KIND
6426 @cindex kind
6427
6428 @table @asis
6429 @item @emph{Description}:
6430 @code{KIND(X)} returns the kind value of the entity @var{X}.
6431
6432 @item @emph{Standard}:
6433 Fortran 95 and later
6434
6435 @item @emph{Class}:
6436 Inquiry function
6437
6438 @item @emph{Syntax}:
6439 @code{K = KIND(X)}
6440
6441 @item @emph{Arguments}:
6442 @multitable @columnfractions .15 .70
6443 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6444 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6445 @end multitable
6446
6447 @item @emph{Return value}:
6448 The return value is a scalar of type @code{INTEGER} and of the default
6449 integer kind.
6450
6451 @item @emph{Example}:
6452 @smallexample
6453 program test_kind
6454   integer,parameter :: kc = kind(' ')
6455   integer,parameter :: kl = kind(.true.)
6456
6457   print *, "The default character kind is ", kc
6458   print *, "The default logical kind is ", kl
6459 end program test_kind
6460 @end smallexample
6461
6462 @end table
6463
6464
6465
6466 @node LBOUND
6467 @section @code{LBOUND} --- Lower dimension bounds of an array
6468 @fnindex LBOUND
6469 @cindex array, lower bound
6470
6471 @table @asis
6472 @item @emph{Description}:
6473 Returns the lower bounds of an array, or a single lower bound
6474 along the @var{DIM} dimension.
6475 @item @emph{Standard}:
6476 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6477
6478 @item @emph{Class}:
6479 Inquiry function
6480
6481 @item @emph{Syntax}:
6482 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6483
6484 @item @emph{Arguments}:
6485 @multitable @columnfractions .15 .70
6486 @item @var{ARRAY} @tab Shall be an array, of any type.
6487 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6488 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6489 expression indicating the kind parameter of the result.
6490 @end multitable
6491
6492 @item @emph{Return value}:
6493 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6494 @var{KIND} is absent, the return value is of default integer kind.
6495 If @var{DIM} is absent, the result is an array of the lower bounds of
6496 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
6497 corresponding to the lower bound of the array along that dimension.  If
6498 @var{ARRAY} is an expression rather than a whole array or array
6499 structure component, or if it has a zero extent along the relevant
6500 dimension, the lower bound is taken to be 1.
6501
6502 @item @emph{See also}:
6503 @ref{UBOUND}
6504 @end table
6505
6506
6507
6508 @node LEN
6509 @section @code{LEN} --- Length of a character entity
6510 @fnindex LEN
6511 @cindex string, length
6512
6513 @table @asis
6514 @item @emph{Description}:
6515 Returns the length of a character string.  If @var{STRING} is an array,
6516 the length of an element of @var{STRING} is returned.  Note that
6517 @var{STRING} need not be defined when this intrinsic is invoked, since
6518 only the length, not the content, of @var{STRING} is needed.
6519
6520 @item @emph{Standard}:
6521 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6522
6523 @item @emph{Class}:
6524 Inquiry function
6525
6526 @item @emph{Syntax}:
6527 @code{L = LEN(STRING [, KIND])}
6528
6529 @item @emph{Arguments}:
6530 @multitable @columnfractions .15 .70
6531 @item @var{STRING} @tab Shall be a scalar or array of type
6532 @code{CHARACTER}, with @code{INTENT(IN)}
6533 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6534 expression indicating the kind parameter of the result.
6535 @end multitable
6536
6537 @item @emph{Return value}:
6538 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6539 @var{KIND} is absent, the return value is of default integer kind.
6540
6541 @item @emph{See also}:
6542 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6543 @end table
6544
6545
6546
6547 @node LEN_TRIM
6548 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6549 @fnindex LEN_TRIM
6550 @cindex string, length, without trailing whitespace
6551
6552 @table @asis
6553 @item @emph{Description}:
6554 Returns the length of a character string, ignoring any trailing blanks.
6555
6556 @item @emph{Standard}:
6557 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6558
6559 @item @emph{Class}:
6560 Elemental function
6561
6562 @item @emph{Syntax}:
6563 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6564
6565 @item @emph{Arguments}:
6566 @multitable @columnfractions .15 .70
6567 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6568 with @code{INTENT(IN)}
6569 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6570 expression indicating the kind parameter of the result.
6571 @end multitable
6572
6573 @item @emph{Return value}:
6574 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6575 @var{KIND} is absent, the return value is of default integer kind.
6576
6577 @item @emph{See also}:
6578 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6579 @end table
6580
6581
6582
6583 @node LGE
6584 @section @code{LGE} --- Lexical greater than or equal
6585 @fnindex LGE
6586 @cindex lexical comparison of strings
6587 @cindex string, comparison
6588
6589 @table @asis
6590 @item @emph{Description}:
6591 Determines whether one string is lexically greater than or equal to
6592 another string, where the two strings are interpreted as containing
6593 ASCII character codes.  If the String A and String B are not the same
6594 length, the shorter is compared as if spaces were appended to it to form
6595 a value that has the same length as the longer.
6596
6597 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6598 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6599 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6600 that the latter use the processor's character ordering (which is not
6601 ASCII on some targets), whereas the former always use the ASCII
6602 ordering.
6603
6604 @item @emph{Standard}:
6605 Fortran 77 and later
6606
6607 @item @emph{Class}:
6608 Elemental function
6609
6610 @item @emph{Syntax}:
6611 @code{RESULT = LGE(STRING_A, STRING_B)}
6612
6613 @item @emph{Arguments}:
6614 @multitable @columnfractions .15 .70
6615 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6616 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6617 @end multitable
6618
6619 @item @emph{Return value}:
6620 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6621 otherwise, based on the ASCII ordering.
6622
6623 @item @emph{See also}:
6624 @ref{LGT}, @ref{LLE}, @ref{LLT}
6625 @end table
6626
6627
6628
6629 @node LGT
6630 @section @code{LGT} --- Lexical greater than
6631 @fnindex LGT
6632 @cindex lexical comparison of strings
6633 @cindex string, comparison
6634
6635 @table @asis
6636 @item @emph{Description}:
6637 Determines whether one string is lexically greater than another string,
6638 where the two strings are interpreted as containing ASCII character
6639 codes.  If the String A and String B are not the same length, the
6640 shorter is compared as if spaces were appended to it to form a value
6641 that has the same length as the longer.
6642
6643 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6644 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6645 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6646 that the latter use the processor's character ordering (which is not
6647 ASCII on some targets), whereas the former always use the ASCII
6648 ordering.
6649
6650 @item @emph{Standard}:
6651 Fortran 77 and later
6652
6653 @item @emph{Class}:
6654 Elemental function
6655
6656 @item @emph{Syntax}:
6657 @code{RESULT = LGT(STRING_A, STRING_B)}
6658
6659 @item @emph{Arguments}:
6660 @multitable @columnfractions .15 .70
6661 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6662 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6663 @end multitable
6664
6665 @item @emph{Return value}:
6666 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6667 otherwise, based on the ASCII ordering.
6668
6669 @item @emph{See also}:
6670 @ref{LGE}, @ref{LLE}, @ref{LLT}
6671 @end table
6672
6673
6674
6675 @node LINK
6676 @section @code{LINK} --- Create a hard link
6677 @fnindex LINK
6678 @cindex file system, create link
6679 @cindex file system, hard link
6680
6681 @table @asis
6682 @item @emph{Description}:
6683 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6684 character (@code{CHAR(0)}) can be used to mark the end of the names in
6685 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6686 names are ignored.  If the @var{STATUS} argument is supplied, it
6687 contains 0 on success or a nonzero error code upon return; see
6688 @code{link(2)}.
6689
6690 This intrinsic is provided in both subroutine and function forms;
6691 however, only one form can be used in any given program unit.
6692
6693 @item @emph{Standard}:
6694 GNU extension
6695
6696 @item @emph{Class}:
6697 Subroutine, function
6698
6699 @item @emph{Syntax}:
6700 @multitable @columnfractions .80
6701 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6702 @item @code{STATUS = LINK(PATH1, PATH2)}
6703 @end multitable
6704
6705 @item @emph{Arguments}:
6706 @multitable @columnfractions .15 .70
6707 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6708 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6709 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6710 @end multitable
6711
6712 @item @emph{See also}:
6713 @ref{SYMLNK}, @ref{UNLINK}
6714 @end table
6715
6716
6717
6718 @node LLE
6719 @section @code{LLE} --- Lexical less than or equal
6720 @fnindex LLE
6721 @cindex lexical comparison of strings
6722 @cindex string, comparison
6723
6724 @table @asis
6725 @item @emph{Description}:
6726 Determines whether one string is lexically less than or equal to another
6727 string, where the two strings are interpreted as containing ASCII
6728 character codes.  If the String A and String B are not the same length,
6729 the shorter is compared as if spaces were appended to it to form a value
6730 that has the same length as the longer.
6731
6732 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6733 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6734 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6735 that the latter use the processor's character ordering (which is not
6736 ASCII on some targets), whereas the former always use the ASCII
6737 ordering.
6738
6739 @item @emph{Standard}:
6740 Fortran 77 and later
6741
6742 @item @emph{Class}:
6743 Elemental function
6744
6745 @item @emph{Syntax}:
6746 @code{RESULT = LLE(STRING_A, STRING_B)}
6747
6748 @item @emph{Arguments}:
6749 @multitable @columnfractions .15 .70
6750 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6751 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6752 @end multitable
6753
6754 @item @emph{Return value}:
6755 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6756 otherwise, based on the ASCII ordering.
6757
6758 @item @emph{See also}:
6759 @ref{LGE}, @ref{LGT}, @ref{LLT}
6760 @end table
6761
6762
6763
6764 @node LLT
6765 @section @code{LLT} --- Lexical less than
6766 @fnindex LLT
6767 @cindex lexical comparison of strings
6768 @cindex string, comparison
6769
6770 @table @asis
6771 @item @emph{Description}:
6772 Determines whether one string is lexically less than another string,
6773 where the two strings are interpreted as containing ASCII character
6774 codes.  If the String A and String B are not the same length, the
6775 shorter is compared as if spaces were appended to it to form a value
6776 that has the same length as the longer.
6777
6778 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6779 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6780 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6781 that the latter use the processor's character ordering (which is not
6782 ASCII on some targets), whereas the former always use the ASCII
6783 ordering.
6784
6785 @item @emph{Standard}:
6786 Fortran 77 and later
6787
6788 @item @emph{Class}:
6789 Elemental function
6790
6791 @item @emph{Syntax}:
6792 @code{RESULT = LLT(STRING_A, STRING_B)}
6793
6794 @item @emph{Arguments}:
6795 @multitable @columnfractions .15 .70
6796 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6797 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6798 @end multitable
6799
6800 @item @emph{Return value}:
6801 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6802 otherwise, based on the ASCII ordering.
6803
6804 @item @emph{See also}:
6805 @ref{LGE}, @ref{LGT}, @ref{LLE}
6806 @end table
6807
6808
6809
6810 @node LNBLNK
6811 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6812 @fnindex LNBLNK
6813 @cindex string, find non-blank character
6814
6815 @table @asis
6816 @item @emph{Description}:
6817 Returns the length of a character string, ignoring any trailing blanks.
6818 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6819 included for backwards compatibility.
6820
6821 @item @emph{Standard}:
6822 GNU extension
6823
6824 @item @emph{Class}:
6825 Elemental function
6826
6827 @item @emph{Syntax}:
6828 @code{RESULT = LNBLNK(STRING)}
6829
6830 @item @emph{Arguments}:
6831 @multitable @columnfractions .15 .70
6832 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6833 with @code{INTENT(IN)}
6834 @end multitable
6835
6836 @item @emph{Return value}:
6837 The return value is of @code{INTEGER(kind=4)} type.
6838
6839 @item @emph{See also}:
6840 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6841 @end table
6842
6843
6844
6845 @node LOC
6846 @section @code{LOC} --- Returns the address of a variable
6847 @fnindex LOC
6848 @cindex location of a variable in memory
6849
6850 @table @asis
6851 @item @emph{Description}:
6852 @code{LOC(X)} returns the address of @var{X} as an integer.
6853
6854 @item @emph{Standard}:
6855 GNU extension
6856
6857 @item @emph{Class}:
6858 Inquiry function
6859
6860 @item @emph{Syntax}:
6861 @code{RESULT = LOC(X)}
6862
6863 @item @emph{Arguments}:
6864 @multitable @columnfractions .15 .70
6865 @item @var{X} @tab Variable of any type.
6866 @end multitable
6867
6868 @item @emph{Return value}:
6869 The return value is of type @code{INTEGER}, with a @code{KIND}
6870 corresponding to the size (in bytes) of a memory address on the target
6871 machine.
6872
6873 @item @emph{Example}:
6874 @smallexample
6875 program test_loc
6876   integer :: i
6877   real :: r
6878   i = loc(r)
6879   print *, i
6880 end program test_loc
6881 @end smallexample
6882 @end table
6883
6884
6885
6886 @node LOG
6887 @section @code{LOG} --- Logarithm function
6888 @fnindex LOG
6889 @fnindex ALOG
6890 @fnindex DLOG
6891 @fnindex CLOG
6892 @fnindex ZLOG
6893 @fnindex CDLOG
6894 @cindex exponential function, inverse
6895 @cindex logarithmic function
6896
6897 @table @asis
6898 @item @emph{Description}:
6899 @code{LOG(X)} computes the logarithm of @var{X}.
6900
6901 @item @emph{Standard}:
6902 Fortran 77 and later
6903
6904 @item @emph{Class}:
6905 Elemental function
6906
6907 @item @emph{Syntax}:
6908 @code{RESULT = LOG(X)}
6909
6910 @item @emph{Arguments}:
6911 @multitable @columnfractions .15 .70
6912 @item @var{X} @tab The type shall be @code{REAL} or
6913 @code{COMPLEX}.
6914 @end multitable
6915
6916 @item @emph{Return value}:
6917 The return value is of type @code{REAL} or @code{COMPLEX}.
6918 The kind type parameter is the same as @var{X}.
6919
6920 @item @emph{Example}:
6921 @smallexample
6922 program test_log
6923   real(8) :: x = 1.0_8
6924   complex :: z = (1.0, 2.0)
6925   x = log(x)
6926   z = log(z)
6927 end program test_log
6928 @end smallexample
6929
6930 @item @emph{Specific names}:
6931 @multitable @columnfractions .20 .20 .20 .25
6932 @item Name            @tab Argument          @tab Return type       @tab Standard
6933 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
6934 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
6935 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
6936 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
6937 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
6938 @end multitable
6939 @end table
6940
6941
6942
6943 @node LOG10
6944 @section @code{LOG10} --- Base 10 logarithm function
6945 @fnindex LOG10
6946 @fnindex ALOG10
6947 @fnindex DLOG10
6948 @cindex exponential function, inverse
6949 @cindex logarithmic function
6950
6951 @table @asis
6952 @item @emph{Description}:
6953 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6954
6955 @item @emph{Standard}:
6956 Fortran 77 and later
6957
6958 @item @emph{Class}:
6959 Elemental function
6960
6961 @item @emph{Syntax}:
6962 @code{RESULT = LOG10(X)}
6963
6964 @item @emph{Arguments}:
6965 @multitable @columnfractions .15 .70
6966 @item @var{X} @tab The type shall be @code{REAL}.
6967 @end multitable
6968
6969 @item @emph{Return value}:
6970 The return value is of type @code{REAL} or @code{COMPLEX}.
6971 The kind type parameter is the same as @var{X}.
6972
6973 @item @emph{Example}:
6974 @smallexample
6975 program test_log10
6976   real(8) :: x = 10.0_8
6977   x = log10(x)
6978 end program test_log10
6979 @end smallexample
6980
6981 @item @emph{Specific names}:
6982 @multitable @columnfractions .20 .20 .20 .25
6983 @item Name            @tab Argument          @tab Return type       @tab Standard
6984 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
6985 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
6986 @end multitable
6987 @end table
6988
6989
6990
6991 @node LOG_GAMMA
6992 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
6993 @fnindex LOG_GAMMA
6994 @fnindex LGAMMA
6995 @fnindex ALGAMA
6996 @fnindex DLGAMA
6997 @cindex Gamma function, logarithm of
6998
6999 @table @asis
7000 @item @emph{Description}:
7001 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7002 of the Gamma (@math{\Gamma}) function.
7003
7004 @item @emph{Standard}:
7005 Fortran 2008 and later
7006
7007 @item @emph{Class}:
7008 Elemental function
7009
7010 @item @emph{Syntax}:
7011 @code{X = LOG_GAMMA(X)}
7012
7013 @item @emph{Arguments}:
7014 @multitable @columnfractions .15 .70
7015 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7016 nor a negative integer.
7017 @end multitable
7018
7019 @item @emph{Return value}:
7020 The return value is of type @code{REAL} of the same kind as @var{X}.
7021
7022 @item @emph{Example}:
7023 @smallexample
7024 program test_log_gamma
7025   real :: x = 1.0
7026   x = lgamma(x) ! returns 0.0
7027 end program test_log_gamma
7028 @end smallexample
7029
7030 @item @emph{Specific names}:
7031 @multitable @columnfractions .20 .20 .20 .25
7032 @item Name             @tab Argument         @tab Return type       @tab Standard
7033 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
7034 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
7035 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
7036 @end multitable
7037
7038 @item @emph{See also}:
7039 Gamma function: @ref{GAMMA}
7040
7041 @end table
7042
7043
7044
7045 @node LOGICAL
7046 @section @code{LOGICAL} --- Convert to logical type
7047 @fnindex LOGICAL
7048 @cindex conversion, to logical
7049
7050 @table @asis
7051 @item @emph{Description}:
7052 Converts one kind of @code{LOGICAL} variable to another.
7053
7054 @item @emph{Standard}:
7055 Fortran 95 and later
7056
7057 @item @emph{Class}:
7058 Elemental function
7059
7060 @item @emph{Syntax}:
7061 @code{RESULT = LOGICAL(L [, KIND])}
7062
7063 @item @emph{Arguments}:
7064 @multitable @columnfractions .15 .70
7065 @item @var{L}    @tab The type shall be @code{LOGICAL}.
7066 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7067 expression indicating the kind parameter of the result.
7068 @end multitable
7069
7070 @item @emph{Return value}:
7071 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7072 kind corresponding to @var{KIND}, or of the default logical kind if
7073 @var{KIND} is not given.
7074
7075 @item @emph{See also}:
7076 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7077 @end table
7078
7079
7080
7081 @node LONG
7082 @section @code{LONG} --- Convert to integer type
7083 @fnindex LONG
7084 @cindex conversion, to integer
7085
7086 @table @asis
7087 @item @emph{Description}:
7088 Convert to a @code{KIND=4} integer type, which is the same size as a C
7089 @code{long} integer.  This is equivalent to the standard @code{INT}
7090 intrinsic with an optional argument of @code{KIND=4}, and is only
7091 included for backwards compatibility.
7092
7093 @item @emph{Standard}:
7094 GNU extension
7095
7096 @item @emph{Class}:
7097 Elemental function
7098
7099 @item @emph{Syntax}:
7100 @code{RESULT = LONG(A)}
7101
7102 @item @emph{Arguments}:
7103 @multitable @columnfractions .15 .70
7104 @item @var{A}    @tab Shall be of type @code{INTEGER},
7105 @code{REAL}, or @code{COMPLEX}.
7106 @end multitable
7107
7108 @item @emph{Return value}:
7109 The return value is a @code{INTEGER(4)} variable.
7110
7111 @item @emph{See also}:
7112 @ref{INT}, @ref{INT2}, @ref{INT8}
7113 @end table
7114
7115
7116
7117 @node LSHIFT
7118 @section @code{LSHIFT} --- Left shift bits
7119 @fnindex LSHIFT
7120 @cindex bits, shift left
7121
7122 @table @asis
7123 @item @emph{Description}:
7124 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7125 bits shifted left by @var{SHIFT} places.  If the absolute value of
7126 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7127 Bits shifted out from the left end are lost; zeros are shifted in from
7128 the opposite end.
7129
7130 This function has been superseded by the @code{ISHFT} intrinsic, which
7131 is standard in Fortran 95 and later.
7132
7133 @item @emph{Standard}:
7134 GNU extension
7135
7136 @item @emph{Class}:
7137 Elemental function
7138
7139 @item @emph{Syntax}:
7140 @code{RESULT = LSHIFT(I, SHIFT)}
7141
7142 @item @emph{Arguments}:
7143 @multitable @columnfractions .15 .70
7144 @item @var{I} @tab The type shall be @code{INTEGER}.
7145 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7146 @end multitable
7147
7148 @item @emph{Return value}:
7149 The return value is of type @code{INTEGER} and of the same kind as
7150 @var{I}.
7151
7152 @item @emph{See also}:
7153 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7154
7155 @end table
7156
7157
7158
7159 @node LSTAT
7160 @section @code{LSTAT} --- Get file status
7161 @fnindex LSTAT
7162 @cindex file system, file status
7163
7164 @table @asis
7165 @item @emph{Description}:
7166 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
7167 then the link itself is statted, not the file that it refers to.
7168
7169 The elements in @code{BUFF} are the same as described by @ref{STAT}.
7170
7171 This intrinsic is provided in both subroutine and function forms; however,
7172 only one form can be used in any given program unit.
7173
7174 @item @emph{Standard}:
7175 GNU extension
7176
7177 @item @emph{Class}:
7178 Subroutine, function
7179
7180 @item @emph{Syntax}:
7181 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
7182
7183 @item @emph{Arguments}:
7184 @multitable @columnfractions .15 .70
7185 @item @var{FILE}   @tab The type shall be @code{CHARACTER} of the default
7186 kind, a valid path within the file system.
7187 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7188 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7189 Returns 0 on success and a system specific error code otherwise.
7190 @end multitable
7191
7192 @item @emph{Example}:
7193 See @ref{STAT} for an example.
7194
7195 @item @emph{See also}:
7196 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7197 @end table
7198
7199
7200
7201 @node LTIME
7202 @section @code{LTIME} --- Convert time to local time info
7203 @fnindex LTIME
7204 @cindex time, conversion to local time info
7205
7206 @table @asis
7207 @item @emph{Description}:
7208 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
7209 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
7210 to the local time zone using @code{localtime(3)}.
7211
7212 @item @emph{Standard}:
7213 GNU extension
7214
7215 @item @emph{Class}:
7216 Subroutine
7217
7218 @item @emph{Syntax}:
7219 @code{CALL LTIME(STIME, TARRAY)}
7220
7221 @item @emph{Arguments}:
7222 @multitable @columnfractions .15 .70
7223 @item @var{STIME}  @tab An @code{INTEGER} scalar expression
7224 corresponding to a system time, with @code{INTENT(IN)}.
7225 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
7226 with @code{INTENT(OUT)}.
7227 @end multitable
7228
7229 @item @emph{Return value}:
7230 The elements of @var{TARRAY} are assigned as follows:
7231 @enumerate
7232 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7233 seconds
7234 @item Minutes after the hour, range 0--59
7235 @item Hours past midnight, range 0--23
7236 @item Day of month, range 0--31
7237 @item Number of months since January, range 0--12
7238 @item Years since 1900
7239 @item Number of days since Sunday, range 0--6
7240 @item Days since January 1
7241 @item Daylight savings indicator: positive if daylight savings is in
7242 effect, zero if not, and negative if the information is not available.
7243 @end enumerate
7244
7245 @item @emph{See also}:
7246 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7247
7248 @end table
7249
7250
7251
7252 @node MALLOC
7253 @section @code{MALLOC} --- Allocate dynamic memory
7254 @fnindex MALLOC
7255 @cindex pointer, cray
7256
7257 @table @asis
7258 @item @emph{Description}:
7259 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7260 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7261 is an extension intended to be used with Cray pointers, and is provided
7262 in GNU Fortran to allow the user to compile legacy code. For new code
7263 using Fortran 95 pointers, the memory allocation intrinsic is
7264 @code{ALLOCATE}.
7265
7266 @item @emph{Standard}:
7267 GNU extension
7268
7269 @item @emph{Class}:
7270 Function
7271
7272 @item @emph{Syntax}:
7273 @code{PTR = MALLOC(SIZE)}
7274
7275 @item @emph{Arguments}:
7276 @multitable @columnfractions .15 .70
7277 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7278 @end multitable
7279
7280 @item @emph{Return value}:
7281 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7282 variables of type @code{INTEGER(K)} have the same size as
7283 C pointers (@code{sizeof(void *)}).
7284
7285 @item @emph{Example}:
7286 The following example demonstrates the use of @code{MALLOC} and
7287 @code{FREE} with Cray pointers. This example is intended to run on
7288 32-bit systems, where the default integer kind is suitable to store
7289 pointers; on 64-bit systems, ptr_x would need to be declared as
7290 @code{integer(kind=8)}.
7291
7292 @smallexample
7293 program test_malloc
7294   integer i
7295   integer ptr_x
7296   real*8 x(*), z
7297   pointer(ptr_x,x)
7298
7299   ptr_x = malloc(20*8)
7300   do i = 1, 20
7301     x(i) = sqrt(1.0d0 / i)
7302   end do
7303   z = 0
7304   do i = 1, 20
7305     z = z + x(i)
7306     print *, z
7307   end do
7308   call free(ptr_x)
7309 end program test_malloc
7310 @end smallexample
7311
7312 @item @emph{See also}:
7313 @ref{FREE}
7314 @end table
7315
7316
7317
7318 @node MATMUL
7319 @section @code{MATMUL} --- matrix multiplication
7320 @fnindex MATMUL
7321 @cindex matrix multiplication
7322 @cindex product, matrix
7323
7324 @table @asis
7325 @item @emph{Description}:
7326 Performs a matrix multiplication on numeric or logical arguments.
7327
7328 @item @emph{Standard}:
7329 Fortran 95 and later
7330
7331 @item @emph{Class}:
7332 Transformational function
7333
7334 @item @emph{Syntax}:
7335 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7336
7337 @item @emph{Arguments}:
7338 @multitable @columnfractions .15 .70
7339 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7340 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7341 one or two.
7342 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7343 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7344 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7345 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7346 equal to the last (or only) dimension of @var{MATRIX_A}.
7347 @end multitable
7348
7349 @item @emph{Return value}:
7350 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
7351 kind of the result follow the usual type and kind promotion rules, as
7352 for the @code{*} or @code{.AND.} operators.
7353
7354 @item @emph{See also}:
7355 @end table
7356
7357
7358
7359 @node MAX
7360 @section @code{MAX} --- Maximum value of an argument list
7361 @fnindex MAX
7362 @fnindex MAX0
7363 @fnindex AMAX0
7364 @fnindex MAX1
7365 @fnindex AMAX1
7366 @fnindex DMAX1
7367 @cindex maximum value
7368
7369 @table @asis
7370 @item @emph{Description}:
7371 Returns the argument with the largest (most positive) value.
7372
7373 @item @emph{Standard}:
7374 Fortran 77 and later
7375
7376 @item @emph{Class}:
7377 Elemental function
7378
7379 @item @emph{Syntax}:
7380 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7381
7382 @item @emph{Arguments}:
7383 @multitable @columnfractions .15 .70
7384 @item @var{A1}          @tab The type shall be @code{INTEGER} or
7385 @code{REAL}.
7386 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7387 as @var{A1}.  (As a GNU extension, arguments of different kinds are
7388 permitted.)
7389 @end multitable
7390
7391 @item @emph{Return value}:
7392 The return value corresponds to the maximum value among the arguments,
7393 and has the same type and kind as the first argument.
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{MAX0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
7399 @item @code{AMAX0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7400 @item @code{MAX1(X)}   @tab @code{REAL X}    @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
7401 @item @code{AMAX1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab Fortran 77 and later
7402 @item @code{DMAX1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab Fortran 77 and later
7403 @end multitable
7404
7405 @item @emph{See also}:
7406 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7407
7408 @end table
7409
7410
7411
7412 @node MAXEXPONENT
7413 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7414 @fnindex MAXEXPONENT
7415 @cindex model representation, maximum exponent
7416
7417 @table @asis
7418 @item @emph{Description}:
7419 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7420 type of @code{X}.
7421
7422 @item @emph{Standard}:
7423 Fortran 95 and later
7424
7425 @item @emph{Class}:
7426 Inquiry function
7427
7428 @item @emph{Syntax}:
7429 @code{RESULT = MAXEXPONENT(X)}
7430
7431 @item @emph{Arguments}:
7432 @multitable @columnfractions .15 .70
7433 @item @var{X} @tab Shall be of type @code{REAL}.
7434 @end multitable
7435
7436 @item @emph{Return value}:
7437 The return value is of type @code{INTEGER} and of the default integer
7438 kind.
7439
7440 @item @emph{Example}:
7441 @smallexample
7442 program exponents
7443   real(kind=4) :: x
7444   real(kind=8) :: y
7445
7446   print *, minexponent(x), maxexponent(x)
7447   print *, minexponent(y), maxexponent(y)
7448 end program exponents
7449 @end smallexample
7450 @end table
7451
7452
7453
7454 @node MAXLOC
7455 @section @code{MAXLOC} --- Location of the maximum value within an array
7456 @fnindex MAXLOC
7457 @cindex array, location of maximum element
7458
7459 @table @asis
7460 @item @emph{Description}:
7461 Determines the location of the element in the array with the maximum
7462 value, or, if the @var{DIM} argument is supplied, determines the
7463 locations of the maximum element along each row of the array in the
7464 @var{DIM} direction.  If @var{MASK} is present, only the elements for
7465 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
7466 element in the array has the maximum value, the location returned is
7467 that of the first such element in array element order.  If the array has
7468 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7469 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
7470 and all of the elements of @var{MASK} along a given row are zero, the
7471 result value for that row is zero.
7472
7473 @item @emph{Standard}:
7474 Fortran 95 and later
7475
7476 @item @emph{Class}:
7477 Transformational function
7478
7479 @item @emph{Syntax}:
7480 @multitable @columnfractions .80
7481 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7482 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7483 @end multitable
7484
7485 @item @emph{Arguments}:
7486 @multitable @columnfractions .15 .70
7487 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7488 @code{REAL}, or @code{CHARACTER}.
7489 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7490 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7491 inclusive.  It may not be an optional dummy argument.
7492 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
7493 and conformable with @var{ARRAY}.
7494 @end multitable
7495
7496 @item @emph{Return value}:
7497 If @var{DIM} is absent, the result is a rank-one array with a length
7498 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
7499 is an array with a rank one less than the rank of @var{ARRAY}, and a
7500 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7501 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
7502 of one, the result is a scalar.  In all cases, the result is of default
7503 @code{INTEGER} type.
7504
7505 @item @emph{See also}:
7506 @ref{MAX}, @ref{MAXVAL}
7507
7508 @end table
7509
7510
7511
7512 @node MAXVAL
7513 @section @code{MAXVAL} --- Maximum value of an array
7514 @fnindex MAXVAL
7515 @cindex array, maximum value
7516 @cindex maximum value
7517
7518 @table @asis
7519 @item @emph{Description}:
7520 Determines the maximum value of the elements in an array value, or, if
7521 the @var{DIM} argument is supplied, determines the maximum value along
7522 each row of the array in the @var{DIM} direction.  If @var{MASK} is
7523 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7524 considered.  If the array has zero size, or all of the elements of
7525 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7526 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7527 a string of nulls if @var{ARRAY} is of character type.
7528
7529 @item @emph{Standard}:
7530 Fortran 95 and later
7531
7532 @item @emph{Class}:
7533 Transformational function
7534
7535 @item @emph{Syntax}:
7536 @multitable @columnfractions .80
7537 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7538 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7539 @end multitable
7540
7541 @item @emph{Arguments}:
7542 @multitable @columnfractions .15 .70
7543 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7544 @code{REAL}, or @code{CHARACTER}.
7545 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7546 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7547 inclusive.  It may not be an optional dummy argument.
7548 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
7549 and conformable with @var{ARRAY}.
7550 @end multitable
7551
7552 @item @emph{Return value}:
7553 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7554 is a scalar.  If @var{DIM} is present, the result is an array with a
7555 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7556 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
7557 cases, the result is of the same type and kind as @var{ARRAY}.
7558
7559 @item @emph{See also}:
7560 @ref{MAX}, @ref{MAXLOC}
7561 @end table
7562
7563
7564
7565 @node MCLOCK
7566 @section @code{MCLOCK} --- Time function
7567 @fnindex MCLOCK
7568 @cindex time, clock ticks
7569 @cindex clock ticks
7570
7571 @table @asis
7572 @item @emph{Description}:
7573 Returns the number of clock ticks since the start of the process, based
7574 on the UNIX function @code{clock(3)}.
7575
7576 This intrinsic is not fully portable, such as to systems with 32-bit
7577 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7578 the values returned by this intrinsic might be, or become, negative, or
7579 numerically less than previous values, during a single run of the
7580 compiled program.
7581
7582 @item @emph{Standard}:
7583 GNU extension
7584
7585 @item @emph{Class}:
7586 Function
7587
7588 @item @emph{Syntax}:
7589 @code{RESULT = MCLOCK()}
7590
7591 @item @emph{Return value}:
7592 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7593 number of clock ticks since the start of the process, or @code{-1} if
7594 the system does not support @code{clock(3)}.
7595
7596 @item @emph{See also}:
7597 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7598
7599 @end table
7600
7601
7602
7603 @node MCLOCK8
7604 @section @code{MCLOCK8} --- Time function (64-bit)
7605 @fnindex MCLOCK8
7606 @cindex time, clock ticks
7607 @cindex clock ticks
7608
7609 @table @asis
7610 @item @emph{Description}:
7611 Returns the number of clock ticks since the start of the process, based
7612 on the UNIX function @code{clock(3)}.
7613
7614 @emph{Warning:} this intrinsic does not increase the range of the timing
7615 values over that returned by @code{clock(3)}. On a system with a 32-bit
7616 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7617 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7618 overflows of the 32-bit value can still occur. Therefore, the values
7619 returned by this intrinsic might be or become negative or numerically
7620 less than previous values during a single run of the compiled program.
7621
7622 @item @emph{Standard}:
7623 GNU extension
7624
7625 @item @emph{Class}:
7626 Function
7627
7628 @item @emph{Syntax}:
7629 @code{RESULT = MCLOCK8()}
7630
7631 @item @emph{Return value}:
7632 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7633 number of clock ticks since the start of the process, or @code{-1} if
7634 the system does not support @code{clock(3)}.
7635
7636 @item @emph{See also}:
7637 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7638
7639 @end table
7640
7641
7642
7643 @node MERGE
7644 @section @code{MERGE} --- Merge variables
7645 @fnindex MERGE
7646 @cindex array, merge arrays
7647 @cindex array, combine arrays
7648
7649 @table @asis
7650 @item @emph{Description}:
7651 Select values from two arrays according to a logical mask.  The result
7652 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7653 @var{FSOURCE} if it is @code{.FALSE.}.
7654
7655 @item @emph{Standard}:
7656 Fortran 95 and later
7657
7658 @item @emph{Class}:
7659 Elemental function
7660
7661 @item @emph{Syntax}:
7662 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7663
7664 @item @emph{Arguments}:
7665 @multitable @columnfractions .15 .70
7666 @item @var{TSOURCE} @tab May be of any type.
7667 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7668 as @var{TSOURCE}.
7669 @item @var{MASK}    @tab Shall be of type @code{LOGICAL}.
7670 @end multitable
7671
7672 @item @emph{Return value}:
7673 The result is of the same type and type parameters as @var{TSOURCE}.
7674
7675 @end table
7676
7677
7678
7679 @node MIN
7680 @section @code{MIN} --- Minimum value of an argument list
7681 @fnindex MIN
7682 @fnindex MIN0
7683 @fnindex AMIN0
7684 @fnindex MIN1
7685 @fnindex AMIN1
7686 @fnindex DMIN1
7687 @cindex minimum value
7688
7689 @table @asis
7690 @item @emph{Description}:
7691 Returns the argument with the smallest (most negative) value.
7692
7693 @item @emph{Standard}:
7694 Fortran 77 and later
7695
7696 @item @emph{Class}:
7697 Elemental function
7698
7699 @item @emph{Syntax}:
7700 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7701
7702 @item @emph{Arguments}:
7703 @multitable @columnfractions .15 .70
7704 @item @var{A1}          @tab The type shall be @code{INTEGER} or
7705 @code{REAL}.
7706 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7707 as @var{A1}.  (As a GNU extension, arguments of different kinds are
7708 permitted.)
7709 @end multitable
7710
7711 @item @emph{Return value}:
7712 The return value corresponds to the maximum value among the arguments,
7713 and has the same type and kind as the first argument.
7714
7715 @item @emph{Specific names}:
7716 @multitable @columnfractions .20 .20 .20 .25
7717 @item Name             @tab Argument            @tab Return type         @tab Standard
7718 @item @code{MIN0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
7719 @item @code{AMIN0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab Fortran 77 and later
7720 @item @code{MIN1(X)}   @tab @code{REAL X}    @tab @code{INT(MIN(X))}  @tab Fortran 77 and later
7721 @item @code{AMIN1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab Fortran 77 and later
7722 @item @code{DMIN1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab Fortran 77 and later
7723 @end multitable
7724
7725 @item @emph{See also}:
7726 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7727 @end table
7728
7729
7730
7731 @node MINEXPONENT
7732 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7733 @fnindex MINEXPONENT
7734 @cindex model representation, minimum exponent
7735
7736 @table @asis
7737 @item @emph{Description}:
7738 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7739 type of @code{X}.
7740
7741 @item @emph{Standard}:
7742 Fortran 95 and later
7743
7744 @item @emph{Class}:
7745 Inquiry function
7746
7747 @item @emph{Syntax}:
7748 @code{RESULT = MINEXPONENT(X)}
7749
7750 @item @emph{Arguments}:
7751 @multitable @columnfractions .15 .70
7752 @item @var{X} @tab Shall be of type @code{REAL}.
7753 @end multitable
7754
7755 @item @emph{Return value}:
7756 The return value is of type @code{INTEGER} and of the default integer
7757 kind.
7758
7759 @item @emph{Example}:
7760 See @code{MAXEXPONENT} for an example.
7761 @end table
7762
7763
7764
7765 @node MINLOC
7766 @section @code{MINLOC} --- Location of the minimum value within an array
7767 @fnindex MINLOC
7768 @cindex array, location of minimum element
7769
7770 @table @asis
7771 @item @emph{Description}:
7772 Determines the location of the element in the array with the minimum
7773 value, or, if the @var{DIM} argument is supplied, determines the
7774 locations of the minimum element along each row of the array in the
7775 @var{DIM} direction.  If @var{MASK} is present, only the elements for
7776 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
7777 element in the array has the minimum value, the location returned is
7778 that of the first such element in array element order.  If the array has
7779 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7780 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
7781 and all of the elements of @var{MASK} along a given row are zero, the
7782 result value for that row is zero.
7783
7784 @item @emph{Standard}:
7785 Fortran 95 and later
7786
7787 @item @emph{Class}:
7788 Transformational function
7789
7790 @item @emph{Syntax}:
7791 @multitable @columnfractions .80
7792 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7793 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7794 @end multitable
7795
7796 @item @emph{Arguments}:
7797 @multitable @columnfractions .15 .70
7798 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7799 @code{REAL}, or @code{CHARACTER}.
7800 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7801 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7802 inclusive.  It may not be an optional dummy argument.
7803 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
7804 and conformable with @var{ARRAY}.
7805 @end multitable
7806
7807 @item @emph{Return value}:
7808 If @var{DIM} is absent, the result is a rank-one array with a length
7809 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
7810 is an array with a rank one less than the rank of @var{ARRAY}, and a
7811 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7812 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
7813 of one, the result is a scalar.  In all cases, the result is of default
7814 @code{INTEGER} type.
7815
7816 @item @emph{See also}:
7817 @ref{MIN}, @ref{MINVAL}
7818
7819 @end table
7820
7821
7822
7823 @node MINVAL
7824 @section @code{MINVAL} --- Minimum value of an array
7825 @fnindex MINVAL
7826 @cindex array, minimum value
7827 @cindex minimum value
7828
7829 @table @asis
7830 @item @emph{Description}:
7831 Determines the minimum value of the elements in an array value, or, if
7832 the @var{DIM} argument is supplied, determines the minimum value along
7833 each row of the array in the @var{DIM} direction.  If @var{MASK} is
7834 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7835 considered.  If the array has zero size, or all of the elements of
7836 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7837 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7838 @var{ARRAY} is of character type.
7839
7840 @item @emph{Standard}:
7841 Fortran 95 and later
7842
7843 @item @emph{Class}:
7844 Transformational function
7845
7846 @item @emph{Syntax}:
7847 @multitable @columnfractions .80
7848 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7849 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7850 @end multitable
7851
7852 @item @emph{Arguments}:
7853 @multitable @columnfractions .15 .70
7854 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7855 @code{REAL}, or @code{CHARACTER}.
7856 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7857 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7858 inclusive.  It may not be an optional dummy argument.
7859 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
7860 and conformable with @var{ARRAY}.
7861 @end multitable
7862
7863 @item @emph{Return value}:
7864 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7865 is a scalar.  If @var{DIM} is present, the result is an array with a
7866 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7867 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
7868 cases, the result is of the same type and kind as @var{ARRAY}.
7869
7870 @item @emph{See also}:
7871 @ref{MIN}, @ref{MINLOC}
7872
7873 @end table
7874
7875
7876
7877 @node MOD
7878 @section @code{MOD} --- Remainder function
7879 @fnindex MOD
7880 @fnindex AMOD
7881 @fnindex DMOD
7882 @cindex remainder
7883 @cindex division, remainder
7884
7885 @table @asis
7886 @item @emph{Description}:
7887 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7888 calculated as @code{A - (INT(A/P) * P)}.
7889
7890 @item @emph{Standard}:
7891 Fortran 77 and later
7892
7893 @item @emph{Class}:
7894 Elemental function
7895
7896 @item @emph{Syntax}:
7897 @code{RESULT = MOD(A, P)}
7898
7899 @item @emph{Arguments}:
7900 @multitable @columnfractions .15 .70
7901 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7902 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7903 equal to zero
7904 @end multitable
7905
7906 @item @emph{Return value}:
7907 The kind of the return value is the result of cross-promoting
7908 the kinds of the arguments.
7909
7910 @item @emph{Example}:
7911 @smallexample
7912 program test_mod
7913   print *, mod(17,3)
7914   print *, mod(17.5,5.5)
7915   print *, mod(17.5d0,5.5)
7916   print *, mod(17.5,5.5d0)
7917
7918   print *, mod(-17,3)
7919   print *, mod(-17.5,5.5)
7920   print *, mod(-17.5d0,5.5)
7921   print *, mod(-17.5,5.5d0)
7922
7923   print *, mod(17,-3)
7924   print *, mod(17.5,-5.5)
7925   print *, mod(17.5d0,-5.5)
7926   print *, mod(17.5,-5.5d0)
7927 end program test_mod
7928 @end smallexample
7929
7930 @item @emph{Specific names}:
7931 @multitable @columnfractions .20 .20 .20 .25
7932 @item Name             @tab Arguments      @tab Return type    @tab Standard
7933 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab Fortran 95 and later
7934 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab Fortran 95 and later
7935 @end multitable
7936 @end table
7937
7938
7939
7940 @node MODULO
7941 @section @code{MODULO} --- Modulo function
7942 @fnindex MODULO
7943 @cindex modulo
7944 @cindex division, modulo
7945
7946 @table @asis
7947 @item @emph{Description}:
7948 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7949
7950 @item @emph{Standard}:
7951 Fortran 95 and later
7952
7953 @item @emph{Class}:
7954 Elemental function
7955
7956 @item @emph{Syntax}:
7957 @code{RESULT = MODULO(A, P)}
7958
7959 @item @emph{Arguments}:
7960 @multitable @columnfractions .15 .70
7961 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7962 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7963 @end multitable
7964
7965 @item @emph{Return value}:
7966 The type and kind of the result are those of the arguments.
7967 @table @asis
7968 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7969 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7970 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7971 (exclusive).
7972 @item If @var{A} and @var{P} are of type @code{REAL}:
7973 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7974 @end table
7975 In all cases, if @var{P} is zero the result is processor-dependent.
7976
7977 @item @emph{Example}:
7978 @smallexample
7979 program test_modulo
7980   print *, modulo(17,3)
7981   print *, modulo(17.5,5.5)
7982
7983   print *, modulo(-17,3)
7984   print *, modulo(-17.5,5.5)
7985
7986   print *, modulo(17,-3)
7987   print *, modulo(17.5,-5.5)
7988 end program
7989 @end smallexample
7990
7991 @end table
7992
7993
7994
7995 @node MOVE_ALLOC
7996 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7997 @fnindex MOVE_ALLOC
7998 @cindex moving allocation
7999 @cindex allocation, moving
8000
8001 @table @asis
8002 @item @emph{Description}:
8003 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
8004 @var{DEST}.  @var{SRC} will become deallocated in the process.
8005
8006 @item @emph{Standard}:
8007 Fortran 2003 and later
8008
8009 @item @emph{Class}:
8010 Subroutine
8011
8012 @item @emph{Syntax}:
8013 @code{CALL MOVE_ALLOC(SRC, DEST)}
8014
8015 @item @emph{Arguments}:
8016 @multitable @columnfractions .15 .70
8017 @item @var{SRC}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8018 of any type and kind.
8019 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8020 of the same type, kind and rank as @var{SRC}.
8021 @end multitable
8022
8023 @item @emph{Return value}:
8024 None
8025
8026 @item @emph{Example}:
8027 @smallexample
8028 program test_move_alloc
8029     integer, allocatable :: a(:), b(:)
8030
8031     allocate(a(3))
8032     a = [ 1, 2, 3 ]
8033     call move_alloc(a, b)
8034     print *, allocated(a), allocated(b)
8035     print *, b
8036 end program test_move_alloc
8037 @end smallexample
8038 @end table
8039
8040
8041
8042 @node MVBITS
8043 @section @code{MVBITS} --- Move bits from one integer to another
8044 @fnindex MVBITS
8045 @cindex bits, move
8046
8047 @table @asis
8048 @item @emph{Description}:
8049 Moves @var{LEN} bits from positions @var{FROMPOS} through
8050 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8051 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8052 affected by the movement of bits is unchanged. The values of
8053 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8054 @code{BIT_SIZE(FROM)}.
8055
8056 @item @emph{Standard}:
8057 Fortran 95 and later
8058
8059 @item @emph{Class}:
8060 Elemental subroutine
8061
8062 @item @emph{Syntax}:
8063 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8064
8065 @item @emph{Arguments}:
8066 @multitable @columnfractions .15 .70
8067 @item @var{FROM}    @tab The type shall be @code{INTEGER}.
8068 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8069 @item @var{LEN}     @tab The type shall be @code{INTEGER}.
8070 @item @var{TO}      @tab The type shall be @code{INTEGER}, of the
8071 same kind as @var{FROM}.
8072 @item @var{TOPOS}   @tab The type shall be @code{INTEGER}.
8073 @end multitable
8074
8075 @item @emph{See also}:
8076 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8077 @end table
8078
8079
8080
8081 @node NEAREST
8082 @section @code{NEAREST} --- Nearest representable number
8083 @fnindex NEAREST
8084 @cindex real number, nearest different
8085 @cindex floating point, nearest different
8086
8087 @table @asis
8088 @item @emph{Description}:
8089 @code{NEAREST(X, S)} returns the processor-representable number nearest
8090 to @code{X} in the direction indicated by the sign of @code{S}.
8091
8092 @item @emph{Standard}:
8093 Fortran 95 and later
8094
8095 @item @emph{Class}:
8096 Elemental function
8097
8098 @item @emph{Syntax}:
8099 @code{RESULT = NEAREST(X, S)}
8100
8101 @item @emph{Arguments}:
8102 @multitable @columnfractions .15 .70
8103 @item @var{X} @tab Shall be of type @code{REAL}.
8104 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8105 not equal to zero.
8106 @end multitable
8107
8108 @item @emph{Return value}:
8109 The return value is of the same type as @code{X}. If @code{S} is
8110 positive, @code{NEAREST} returns the processor-representable number
8111 greater than @code{X} and nearest to it. If @code{S} is negative,
8112 @code{NEAREST} returns the processor-representable number smaller than
8113 @code{X} and nearest to it.
8114
8115 @item @emph{Example}:
8116 @smallexample
8117 program test_nearest
8118   real :: x, y
8119   x = nearest(42.0, 1.0)
8120   y = nearest(42.0, -1.0)
8121   write (*,"(3(G20.15))") x, y, x - y
8122 end program test_nearest
8123 @end smallexample
8124 @end table
8125
8126
8127
8128 @node NEW_LINE
8129 @section @code{NEW_LINE} --- New line character
8130 @fnindex NEW_LINE
8131 @cindex newline
8132 @cindex output, newline
8133
8134 @table @asis
8135 @item @emph{Description}:
8136 @code{NEW_LINE(C)} returns the new-line character.
8137
8138 @item @emph{Standard}:
8139 Fortran 2003 and later
8140
8141 @item @emph{Class}:
8142 Inquiry function
8143
8144 @item @emph{Syntax}:
8145 @code{RESULT = NEW_LINE(C)}
8146
8147 @item @emph{Arguments}:
8148 @multitable @columnfractions .15 .70
8149 @item @var{C}    @tab The argument shall be a scalar or array of the
8150 type @code{CHARACTER}.
8151 @end multitable
8152
8153 @item @emph{Return value}:
8154 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8155 the same kind as parameter @var{C}.
8156
8157 @item @emph{Example}:
8158 @smallexample
8159 program newline
8160   implicit none
8161   write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8162 end program newline
8163 @end smallexample
8164 @end table
8165
8166
8167
8168 @node NINT
8169 @section @code{NINT} --- Nearest whole number
8170 @fnindex NINT
8171 @fnindex IDNINT
8172 @cindex rounding, nearest whole number
8173
8174 @table @asis
8175 @item @emph{Description}:
8176 @code{NINT(X)} rounds its argument to the nearest whole number.
8177
8178 @item @emph{Standard}:
8179 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8180
8181 @item @emph{Class}:
8182 Elemental function
8183
8184 @item @emph{Syntax}:
8185 @code{RESULT = NINT(X [, KIND])}
8186
8187 @item @emph{Arguments}:
8188 @multitable @columnfractions .15 .70
8189 @item @var{X}    @tab The type of the argument shall be @code{REAL}.
8190 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8191 expression indicating the kind parameter of the result.
8192 @end multitable
8193
8194 @item @emph{Return value}:
8195 Returns @var{A} with the fractional portion of its magnitude eliminated by
8196 rounding to the nearest whole number and with its sign preserved,
8197 converted to an @code{INTEGER} of the default kind.
8198
8199 @item @emph{Example}:
8200 @smallexample
8201 program test_nint
8202   real(4) x4
8203   real(8) x8
8204   x4 = 1.234E0_4
8205   x8 = 4.321_8
8206   print *, nint(x4), idnint(x8)
8207 end program test_nint
8208 @end smallexample
8209
8210 @item @emph{Specific names}:
8211 @multitable @columnfractions .25 .25 .25
8212 @item Name             @tab Argument         @tab Standard
8213 @item @code{IDNINT(X)} @tab @code{REAL(8)}   @tab Fortran 95 and later
8214 @end multitable
8215
8216 @item @emph{See also}:
8217 @ref{CEILING}, @ref{FLOOR}
8218
8219 @end table
8220
8221
8222
8223 @node NOT
8224 @section @code{NOT} --- Logical negation
8225 @fnindex NOT
8226 @cindex bits, negate
8227 @cindex bitwise logical not
8228 @cindex logical not, bitwise
8229
8230 @table @asis
8231 @item @emph{Description}:
8232 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8233
8234 @item @emph{Standard}:
8235 Fortran 95 and later
8236
8237 @item @emph{Class}:
8238 Elemental function
8239
8240 @item @emph{Syntax}:
8241 @code{RESULT = NOT(I)}
8242
8243 @item @emph{Arguments}:
8244 @multitable @columnfractions .15 .70
8245 @item @var{I} @tab The type shall be @code{INTEGER}.
8246 @end multitable
8247
8248 @item @emph{Return value}:
8249 The return type is @code{INTEGER}, of the same kind as the
8250 argument.
8251
8252 @item @emph{See also}:
8253 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8254
8255 @end table
8256
8257
8258
8259 @node NULL
8260 @section @code{NULL} --- Function that returns an disassociated pointer
8261 @fnindex NULL
8262 @cindex pointer, status
8263 @cindex pointer, disassociated
8264
8265 @table @asis
8266 @item @emph{Description}:
8267 Returns a disassociated pointer.
8268
8269 If @var{MOLD} is present, a dissassociated pointer of the same type is
8270 returned, otherwise the type is determined by context.
8271
8272 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8273 includes cases where it is required.
8274
8275 @item @emph{Standard}:
8276 Fortran 95 and later
8277
8278 @item @emph{Class}:
8279 Transformational function
8280
8281 @item @emph{Syntax}:
8282 @code{PTR => NULL([MOLD])}
8283
8284 @item @emph{Arguments}:
8285 @multitable @columnfractions .15 .70
8286 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8287 status and of any type.
8288 @end multitable
8289
8290 @item @emph{Return value}:
8291 A disassociated pointer.
8292
8293 @item @emph{Example}:
8294 @smallexample
8295 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8296 @end smallexample
8297
8298 @item @emph{See also}:
8299 @ref{ASSOCIATED}
8300 @end table
8301
8302
8303
8304 @node OR
8305 @section @code{OR} --- Bitwise logical OR
8306 @fnindex OR
8307 @cindex bitwise logical or
8308 @cindex logical or, bitwise
8309
8310 @table @asis
8311 @item @emph{Description}:
8312 Bitwise logical @code{OR}.
8313
8314 This intrinsic routine is provided for backwards compatibility with
8315 GNU Fortran 77.  For integer arguments, programmers should consider
8316 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8317
8318 @item @emph{Standard}:
8319 GNU extension
8320
8321 @item @emph{Class}:
8322 Function
8323
8324 @item @emph{Syntax}:
8325 @code{RESULT = OR(X, Y)}
8326
8327 @item @emph{Arguments}:
8328 @multitable @columnfractions .15 .70
8329 @item @var{X} @tab The type shall be either a scalar @code{INTEGER}
8330 type or a scalar @code{LOGICAL} type.
8331 @item @var{Y} @tab The type shall be the same as the type of @var{X}.
8332 @end multitable
8333
8334 @item @emph{Return value}:
8335 The return type is either a scalar @code{INTEGER} or a scalar
8336 @code{LOGICAL}.  If the kind type parameters differ, then the
8337 smaller kind type is implicitly converted to larger kind, and the
8338 return has the larger kind.
8339
8340 @item @emph{Example}:
8341 @smallexample
8342 PROGRAM test_or
8343   LOGICAL :: T = .TRUE., F = .FALSE.
8344   INTEGER :: a, b
8345   DATA a / Z'F' /, b / Z'3' /
8346
8347   WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8348   WRITE (*,*) OR(a, b)
8349 END PROGRAM
8350 @end smallexample
8351
8352 @item @emph{See also}:
8353 Fortran 95 elemental function: @ref{IOR}
8354 @end table
8355
8356
8357
8358 @node PACK
8359 @section @code{PACK} --- Pack an array into an array of rank one
8360 @fnindex PACK
8361 @cindex array, packing
8362 @cindex array, reduce dimension
8363 @cindex array, gather elements
8364
8365 @table @asis
8366 @item @emph{Description}:
8367 Stores the elements of @var{ARRAY} in an array of rank one.
8368
8369 The beginning of the resulting array is made up of elements whose @var{MASK}
8370 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8371 @var{VECTOR}.
8372
8373 @item @emph{Standard}:
8374 Fortran 95 and later
8375
8376 @item @emph{Class}:
8377 Transformational function
8378
8379 @item @emph{Syntax}:
8380 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8381
8382 @item @emph{Arguments}:
8383 @multitable @columnfractions .15 .70
8384 @item @var{ARRAY}  @tab Shall be an array of any type.
8385 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
8386 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8387 scalar.
8388 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8389 as @var{ARRAY} and of rank one. If present, the number of elements in
8390 @var{VECTOR} shall be equal to or greater than the number of true elements
8391 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8392 @var{VECTOR} shall be equal to or greater than the number of elements in
8393 @var{ARRAY}.
8394 @end multitable
8395
8396 @item @emph{Return value}:
8397 The result is an array of rank one and the same type as that of @var{ARRAY}.
8398 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8399 number of @code{TRUE} values in @var{MASK} otherwise.
8400
8401 @item @emph{Example}:
8402 Gathering nonzero elements from an array:
8403 @smallexample
8404 PROGRAM test_pack_1
8405   INTEGER :: m(6)
8406   m = (/ 1, 0, 0, 0, 5, 0 /)
8407   WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
8408 END PROGRAM
8409 @end smallexample
8410
8411 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8412 @smallexample
8413 PROGRAM test_pack_2
8414   INTEGER :: m(4)
8415   m = (/ 1, 0, 0, 2 /)
8416   WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
8417 END PROGRAM
8418 @end smallexample
8419
8420 @item @emph{See also}:
8421 @ref{UNPACK}
8422 @end table
8423
8424
8425
8426 @node PERROR
8427 @section @code{PERROR} --- Print system error message
8428 @fnindex PERROR
8429 @cindex system, error handling
8430
8431 @table @asis
8432 @item @emph{Description}:
8433 Prints (on the C @code{stderr} stream) a newline-terminated error
8434 message corresponding to the last system error. This is prefixed by
8435 @var{STRING}, a colon and a space. See @code{perror(3)}.
8436
8437 @item @emph{Standard}:
8438 GNU extension
8439
8440 @item @emph{Class}:
8441 Subroutine
8442
8443 @item @emph{Syntax}:
8444 @code{CALL PERROR(STRING)}
8445
8446 @item @emph{Arguments}:
8447 @multitable @columnfractions .15 .70
8448 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8449 default kind.
8450 @end multitable
8451
8452 @item @emph{See also}:
8453 @ref{IERRNO}
8454 @end table
8455
8456
8457
8458 @node PRECISION
8459 @section @code{PRECISION} --- Decimal precision of a real kind
8460 @fnindex PRECISION
8461 @cindex model representation, precision
8462
8463 @table @asis
8464 @item @emph{Description}:
8465 @code{PRECISION(X)} returns the decimal precision in the model of the
8466 type of @code{X}.
8467
8468 @item @emph{Standard}:
8469 Fortran 95 and later
8470
8471 @item @emph{Class}:
8472 Inquiry function
8473
8474 @item @emph{Syntax}:
8475 @code{RESULT = PRECISION(X)}
8476
8477 @item @emph{Arguments}:
8478 @multitable @columnfractions .15 .70
8479 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8480 @end multitable
8481
8482 @item @emph{Return value}:
8483 The return value is of type @code{INTEGER} and of the default integer
8484 kind.
8485
8486 @item @emph{Example}:
8487 @smallexample
8488 program prec_and_range
8489   real(kind=4) :: x(2)
8490   complex(kind=8) :: y
8491
8492   print *, precision(x), range(x)
8493   print *, precision(y), range(y)
8494 end program prec_and_range
8495 @end smallexample
8496 @end table
8497
8498
8499
8500 @node PRESENT
8501 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8502 @fnindex PRESENT
8503
8504 @table @asis
8505 @item @emph{Description}:
8506 Determines whether an optional dummy argument is present.
8507
8508 @item @emph{Standard}:
8509 Fortran 95 and later
8510
8511 @item @emph{Class}:
8512 Inquiry function
8513
8514 @item @emph{Syntax}:
8515 @code{RESULT = PRESENT(A)}
8516
8517 @item @emph{Arguments}:
8518 @multitable @columnfractions .15 .70
8519 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8520 value, or a dummy procedure. It shall be the name of an optional dummy argument
8521 accessible within the current subroutine or function.
8522 @end multitable
8523
8524 @item @emph{Return value}:
8525 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8526 @code{FALSE} otherwise.
8527
8528 @item @emph{Example}:
8529 @smallexample
8530 PROGRAM test_present
8531   WRITE(*,*) f(), f(42)      ! "F T"
8532 CONTAINS
8533   LOGICAL FUNCTION f(x)
8534     INTEGER, INTENT(IN), OPTIONAL :: x
8535     f = PRESENT(x)
8536   END FUNCTION
8537 END PROGRAM
8538 @end smallexample
8539 @end table
8540
8541
8542
8543 @node PRODUCT
8544 @section @code{PRODUCT} --- Product of array elements
8545 @fnindex PRODUCT
8546 @cindex array, product
8547 @cindex array, multiply elements
8548 @cindex array, conditionally multiply elements
8549 @cindex multiply array elements
8550
8551 @table @asis
8552 @item @emph{Description}:
8553 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8554 the corresponding element in @var{MASK} is @code{TRUE}.
8555
8556 @item @emph{Standard}:
8557 Fortran 95 and later
8558
8559 @item @emph{Class}:
8560 Transformational function
8561
8562 @item @emph{Syntax}:
8563 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8564 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8565
8566 @item @emph{Arguments}:
8567 @multitable @columnfractions .15 .70
8568 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8569 @code{REAL} or @code{COMPLEX}.
8570 @item @var{DIM}   @tab (Optional) shall be a scalar of type
8571 @code{INTEGER} with a value in the range from 1 to n, where n
8572 equals the rank of @var{ARRAY}.
8573 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
8574 and either be a scalar or an array of the same shape as @var{ARRAY}.
8575 @end multitable
8576
8577 @item @emph{Return value}:
8578 The result is of the same type as @var{ARRAY}.
8579
8580 If @var{DIM} is absent, a scalar with the product of all elements in
8581 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8582 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8583 dimension @var{DIM} dropped is returned.
8584
8585
8586 @item @emph{Example}:
8587 @smallexample
8588 PROGRAM test_product
8589   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8590   print *, PRODUCT(x)                    ! all elements, product = 120
8591   print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8592 END PROGRAM
8593 @end smallexample
8594
8595 @item @emph{See also}:
8596 @ref{SUM}
8597 @end table
8598
8599
8600
8601 @node RADIX
8602 @section @code{RADIX} --- Base of a model number
8603 @fnindex RADIX
8604 @cindex model representation, base
8605 @cindex model representation, radix
8606
8607 @table @asis
8608 @item @emph{Description}:
8609 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8610
8611 @item @emph{Standard}:
8612 Fortran 95 and later
8613
8614 @item @emph{Class}:
8615 Inquiry function
8616
8617 @item @emph{Syntax}:
8618 @code{RESULT = RADIX(X)}
8619
8620 @item @emph{Arguments}:
8621 @multitable @columnfractions .15 .70
8622 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8623 @end multitable
8624
8625 @item @emph{Return value}:
8626 The return value is a scalar of type @code{INTEGER} and of the default
8627 integer kind.
8628
8629 @item @emph{Example}:
8630 @smallexample
8631 program test_radix
8632   print *, "The radix for the default integer kind is", radix(0)
8633   print *, "The radix for the default real kind is", radix(0.0)
8634 end program test_radix
8635 @end smallexample
8636
8637 @end table
8638
8639
8640
8641 @node RAN
8642 @section @code{RAN} --- Real pseudo-random number
8643 @fnindex RAN
8644 @cindex random number generation
8645
8646 @table @asis
8647 @item @emph{Description}:
8648 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8649 provided as an alias for @code{RAND}.  See @ref{RAND} for complete
8650 documentation.
8651
8652 @item @emph{Standard}:
8653 GNU extension
8654
8655 @item @emph{Class}:
8656 Function
8657
8658 @item @emph{See also}:
8659 @ref{RAND}, @ref{RANDOM_NUMBER}
8660 @end table
8661
8662
8663
8664 @node RAND
8665 @section @code{RAND} --- Real pseudo-random number
8666 @fnindex RAND
8667 @cindex random number generation
8668
8669 @table @asis
8670 @item @emph{Description}:
8671 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8672 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8673 in the current sequence is returned; if @var{FLAG} is 1, the generator
8674 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8675 it is used as a new seed with @code{SRAND}.
8676
8677 This intrinsic routine is provided for backwards compatibility with
8678 GNU Fortran 77. It implements a simple modulo generator as provided
8679 by @command{g77}. For new code, one should consider the use of
8680 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8681
8682 @item @emph{Standard}:
8683 GNU extension
8684
8685 @item @emph{Class}:
8686 Function
8687
8688 @item @emph{Syntax}:
8689 @code{RESULT = RAND(FLAG)}
8690
8691 @item @emph{Arguments}:
8692 @multitable @columnfractions .15 .70
8693 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8694 @end multitable
8695
8696 @item @emph{Return value}:
8697 The return value is of @code{REAL} type and the default kind.
8698
8699 @item @emph{Example}:
8700 @smallexample
8701 program test_rand
8702   integer,parameter :: seed = 86456
8703
8704   call srand(seed)
8705   print *, rand(), rand(), rand(), rand()
8706   print *, rand(seed), rand(), rand(), rand()
8707 end program test_rand
8708 @end smallexample
8709
8710 @item @emph{See also}:
8711 @ref{SRAND}, @ref{RANDOM_NUMBER}
8712
8713 @end table
8714
8715
8716
8717 @node RANDOM_NUMBER
8718 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8719 @fnindex RANDOM_NUMBER
8720 @cindex random number generation
8721
8722 @table @asis
8723 @item @emph{Description}:
8724 Returns a single pseudorandom number or an array of pseudorandom numbers
8725 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8726
8727 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8728 Stupid) random number generator (RNG). This RNG combines:
8729 @enumerate
8730 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8731 with a period of @math{2^{32}},
8732 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8733 @item  Two 16-bit multiply-with-carry generators with a period of
8734 @math{597273182964842497 > 2^{59}}.
8735 @end enumerate
8736 The overall period exceeds @math{2^{123}}.
8737
8738 Please note, this RNG is thread safe if used within OpenMP directives,
8739 i.e., its state will be consistent while called from multiple threads.
8740 However, the KISS generator does not create random numbers in parallel
8741 from multiple sources, but in sequence from a single source. If an
8742 OpenMP-enabled application heavily relies on random numbers, one should
8743 consider employing a dedicated parallel random number generator instead.
8744
8745 @item @emph{Standard}:
8746 Fortran 95 and later
8747
8748 @item @emph{Class}:
8749 Subroutine
8750
8751 @item @emph{Syntax}:
8752 @code{RANDOM_NUMBER(HARVEST)}
8753
8754 @item @emph{Arguments}:
8755 @multitable @columnfractions .15 .70
8756 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
8757 @end multitable
8758
8759 @item @emph{Example}:
8760 @smallexample
8761 program test_random_number
8762   REAL :: r(5,5)
8763   CALL init_random_seed()         ! see example of RANDOM_SEED
8764   CALL RANDOM_NUMBER(r)
8765 end program
8766 @end smallexample
8767
8768 @item @emph{See also}:
8769 @ref{RANDOM_SEED}
8770 @end table
8771
8772
8773
8774 @node RANDOM_SEED
8775 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8776 @fnindex RANDOM_SEED
8777 @cindex random number generation, seeding
8778 @cindex seeding a random number generator
8779
8780 @table @asis
8781 @item @emph{Description}:
8782 Restarts or queries the state of the pseudorandom number generator used by
8783 @code{RANDOM_NUMBER}.
8784
8785 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8786 a default state. The example below shows how to initialize the random
8787 seed based on the system's time.
8788
8789 @item @emph{Standard}:
8790 Fortran 95 and later
8791
8792 @item @emph{Class}:
8793 Subroutine
8794
8795 @item @emph{Syntax}:
8796 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8797
8798 @item @emph{Arguments}:
8799 @multitable @columnfractions .15 .70
8800 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8801 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8802 of the arrays used with the @var{PUT} and @var{GET} arguments.
8803 @item @var{PUT}  @tab (Optional) Shall be an array of type default
8804 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8805 the array must be larger than or equal to the number returned by the
8806 @var{SIZE} argument.
8807 @item @var{GET}  @tab (Optional) Shall be an array of type default
8808 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8809 of the array must be larger than or equal to the number returned by
8810 the @var{SIZE} argument.
8811 @end multitable
8812
8813 @item @emph{Example}:
8814 @smallexample
8815 SUBROUTINE init_random_seed()
8816   INTEGER :: i, n, clock
8817   INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8818
8819   CALL RANDOM_SEED(size = n)
8820   ALLOCATE(seed(n))
8821
8822   CALL SYSTEM_CLOCK(COUNT=clock)
8823
8824   seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8825   CALL RANDOM_SEED(PUT = seed)
8826
8827   DEALLOCATE(seed)
8828 END SUBROUTINE
8829 @end smallexample
8830
8831 @item @emph{See also}:
8832 @ref{RANDOM_NUMBER}
8833 @end table
8834
8835
8836
8837 @node RANGE
8838 @section @code{RANGE} --- Decimal exponent range of a real kind
8839 @fnindex RANGE
8840 @cindex model representation, range
8841
8842 @table @asis
8843 @item @emph{Description}:
8844 @code{RANGE(X)} returns the decimal exponent range in the model of the
8845 type of @code{X}.
8846
8847 @item @emph{Standard}:
8848 Fortran 95 and later
8849
8850 @item @emph{Class}:
8851 Inquiry function
8852
8853 @item @emph{Syntax}:
8854 @code{RESULT = RANGE(X)}
8855
8856 @item @emph{Arguments}:
8857 @multitable @columnfractions .15 .70
8858 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8859 @end multitable
8860
8861 @item @emph{Return value}:
8862 The return value is of type @code{INTEGER} and of the default integer
8863 kind.
8864
8865 @item @emph{Example}:
8866 See @code{PRECISION} for an example.
8867 @end table
8868
8869
8870
8871 @node REAL
8872 @section @code{REAL} --- Convert to real type
8873 @fnindex REAL
8874 @fnindex REALPART
8875 @cindex conversion, to real
8876 @cindex complex numbers, real part
8877
8878 @table @asis
8879 @item @emph{Description}:
8880 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type.  The
8881 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8882 and its use is strongly discouraged.
8883
8884 @item @emph{Standard}:
8885 Fortran 77 and later
8886
8887 @item @emph{Class}:
8888 Elemental function
8889
8890 @item @emph{Syntax}:
8891 @multitable @columnfractions .80
8892 @item @code{RESULT = REAL(X [, KIND])}
8893 @item @code{RESULT = REALPART(Z)}
8894 @end multitable
8895
8896 @item @emph{Arguments}:
8897 @multitable @columnfractions .15 .70
8898 @item @var{X}    @tab Shall be @code{INTEGER}, @code{REAL}, or
8899 @code{COMPLEX}.
8900 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8901 expression indicating the kind parameter of the result.
8902 @end multitable
8903
8904 @item @emph{Return value}:
8905 These functions return a @code{REAL} variable or array under
8906 the following rules:
8907
8908 @table @asis
8909 @item (A)
8910 @code{REAL(X)} is converted to a default real type if @var{X} is an
8911 integer or real variable.
8912 @item (B)
8913 @code{REAL(X)} is converted to a real type with the kind type parameter
8914 of @var{X} if @var{X} is a complex variable.
8915 @item (C)
8916 @code{REAL(X, KIND)} is converted to a real type with kind type
8917 parameter @var{KIND} if @var{X} is a complex, integer, or real
8918 variable.
8919 @end table
8920
8921 @item @emph{Example}:
8922 @smallexample
8923 program test_real
8924   complex :: x = (1.0, 2.0)
8925   print *, real(x), real(x,8), realpart(x)
8926 end program test_real
8927 @end smallexample
8928
8929 @item @emph{See also}:
8930 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8931
8932 @end table
8933
8934
8935
8936 @node RENAME
8937 @section @code{RENAME} --- Rename a file
8938 @fnindex RENAME
8939 @cindex file system, rename file
8940
8941 @table @asis
8942 @item @emph{Description}:
8943 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8944 character (@code{CHAR(0)}) can be used to mark the end of the names in
8945 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8946 names are ignored.  If the @var{STATUS} argument is supplied, it
8947 contains 0 on success or a nonzero error code upon return; see
8948 @code{rename(2)}.
8949
8950 This intrinsic is provided in both subroutine and function forms;
8951 however, only one form can be used in any given program unit.
8952
8953 @item @emph{Standard}:
8954 GNU extension
8955
8956 @item @emph{Class}:
8957 Subroutine, function
8958
8959 @item @emph{Syntax}:
8960 @multitable @columnfractions .80
8961 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8962 @item @code{STATUS = RENAME(PATH1, PATH2)}
8963 @end multitable
8964
8965 @item @emph{Arguments}:
8966 @multitable @columnfractions .15 .70
8967 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8968 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8969 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8970 @end multitable
8971
8972 @item @emph{See also}:
8973 @ref{LINK}
8974
8975 @end table
8976
8977
8978
8979 @node REPEAT
8980 @section @code{REPEAT} --- Repeated string concatenation
8981 @fnindex REPEAT
8982 @cindex string, repeat
8983 @cindex string, concatenate
8984
8985 @table @asis
8986 @item @emph{Description}:
8987 Concatenates @var{NCOPIES} copies of a string.
8988
8989 @item @emph{Standard}:
8990 Fortran 95 and later
8991
8992 @item @emph{Class}:
8993 Transformational function
8994
8995 @item @emph{Syntax}:
8996 @code{RESULT = REPEAT(STRING, NCOPIES)}
8997
8998 @item @emph{Arguments}:
8999 @multitable @columnfractions .15 .70
9000 @item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER}.
9001 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9002 @end multitable
9003
9004 @item @emph{Return value}:
9005 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9006 of @var{STRING}.
9007
9008 @item @emph{Example}:
9009 @smallexample
9010 program test_repeat
9011   write(*,*) repeat("x", 5)   ! "xxxxx"
9012 end program
9013 @end smallexample
9014 @end table
9015
9016
9017
9018 @node RESHAPE
9019 @section @code{RESHAPE} --- Function to reshape an array
9020 @fnindex RESHAPE
9021 @cindex array, change dimensions
9022 @cindex array, transmogrify
9023
9024 @table @asis
9025 @item @emph{Description}:
9026 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9027 the new array may be padded with elements from @var{PAD} or permuted
9028 as defined by @var{ORDER}.
9029
9030 @item @emph{Standard}:
9031 Fortran 95 and later
9032
9033 @item @emph{Class}:
9034 Transformational function
9035
9036 @item @emph{Syntax}:
9037 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9038
9039 @item @emph{Arguments}:
9040 @multitable @columnfractions .15 .70
9041 @item @var{SOURCE} @tab Shall be an array of any type.
9042 @item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
9043 array of rank one. Its values must be positive or zero.
9044 @item @var{PAD}    @tab (Optional) shall be an array of the same
9045 type as @var{SOURCE}.
9046 @item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
9047 and an array of the same shape as @var{SHAPE}. Its values shall
9048 be a permutation of the numbers from 1 to n, where n is the size of
9049 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9050 be assumed.
9051 @end multitable
9052
9053 @item @emph{Return value}:
9054 The result is an array of shape @var{SHAPE} with the same type as
9055 @var{SOURCE}.
9056
9057 @item @emph{Example}:
9058 @smallexample
9059 PROGRAM test_reshape
9060   INTEGER, DIMENSION(4) :: x
9061   WRITE(*,*) SHAPE(x)                       ! prints "4"
9062   WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
9063 END PROGRAM
9064 @end smallexample
9065
9066 @item @emph{See also}:
9067 @ref{SHAPE}
9068 @end table
9069
9070
9071
9072 @node RRSPACING
9073 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9074 @fnindex RRSPACING
9075 @cindex real number, relative spacing
9076 @cindex floating point, relative spacing
9077
9078
9079 @table @asis
9080 @item @emph{Description}:
9081 @code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
9082 model numbers near @var{X}.
9083
9084 @item @emph{Standard}:
9085 Fortran 95 and later
9086
9087 @item @emph{Class}:
9088 Elemental function
9089
9090 @item @emph{Syntax}:
9091 @code{RESULT = RRSPACING(X)}
9092
9093 @item @emph{Arguments}:
9094 @multitable @columnfractions .15 .70
9095 @item @var{X} @tab Shall be of type @code{REAL}.
9096 @end multitable
9097
9098 @item @emph{Return value}:
9099 The return value is of the same type and kind as @var{X}.
9100 The value returned is equal to
9101 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9102
9103 @item @emph{See also}:
9104 @ref{SPACING}
9105 @end table
9106
9107
9108
9109 @node RSHIFT
9110 @section @code{RSHIFT} --- Right shift bits
9111 @fnindex RSHIFT
9112 @cindex bits, shift right
9113
9114 @table @asis
9115 @item @emph{Description}:
9116 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9117 bits shifted right by @var{SHIFT} places.  If the absolute value of
9118 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9119 Bits shifted out from the left end are lost; zeros are shifted in from
9120 the opposite end.
9121
9122 This function has been superseded by the @code{ISHFT} intrinsic, which
9123 is standard in Fortran 95 and later.
9124
9125 @item @emph{Standard}:
9126 GNU extension
9127
9128 @item @emph{Class}:
9129 Elemental function
9130
9131 @item @emph{Syntax}:
9132 @code{RESULT = RSHIFT(I, SHIFT)}
9133
9134 @item @emph{Arguments}:
9135 @multitable @columnfractions .15 .70
9136 @item @var{I} @tab The type shall be @code{INTEGER}.
9137 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9138 @end multitable
9139
9140 @item @emph{Return value}:
9141 The return value is of type @code{INTEGER} and of the same kind as
9142 @var{I}.
9143
9144 @item @emph{See also}:
9145 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9146
9147 @end table
9148
9149
9150
9151 @node SCALE
9152 @section @code{SCALE} --- Scale a real value
9153 @fnindex SCALE
9154 @cindex real number, scale
9155 @cindex floating point, scale
9156
9157 @table @asis
9158 @item @emph{Description}:
9159 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9160
9161 @item @emph{Standard}:
9162 Fortran 95 and later
9163
9164 @item @emph{Class}:
9165 Elemental function
9166
9167 @item @emph{Syntax}:
9168 @code{RESULT = SCALE(X, I)}
9169
9170 @item @emph{Arguments}:
9171 @multitable @columnfractions .15 .70
9172 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9173 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9174 @end multitable
9175
9176 @item @emph{Return value}:
9177 The return value is of the same type and kind as @var{X}.
9178 Its value is @code{X * RADIX(X)**I}.
9179
9180 @item @emph{Example}:
9181 @smallexample
9182 program test_scale
9183   real :: x = 178.1387e-4
9184   integer :: i = 5
9185   print *, scale(x,i), x*radix(x)**i
9186 end program test_scale
9187 @end smallexample
9188
9189 @end table
9190
9191
9192
9193 @node SCAN
9194 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9195 @fnindex SCAN
9196 @cindex string, find subset
9197
9198 @table @asis
9199 @item @emph{Description}:
9200 Scans a @var{STRING} for any of the characters in a @var{SET}
9201 of characters.
9202
9203 If @var{BACK} is either absent or equals @code{FALSE}, this function
9204 returns the position of the leftmost character of @var{STRING} that is
9205 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9206 is returned. If no character of @var{SET} is found in @var{STRING}, the
9207 result is zero.
9208
9209 @item @emph{Standard}:
9210 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9211
9212 @item @emph{Class}:
9213 Elemental function
9214
9215 @item @emph{Syntax}:
9216 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9217
9218 @item @emph{Arguments}:
9219 @multitable @columnfractions .15 .70
9220 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9221 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
9222 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
9223 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
9224 expression indicating the kind parameter of the result.
9225 @end multitable
9226
9227 @item @emph{Return value}:
9228 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9229 @var{KIND} is absent, the return value is of default integer kind.
9230
9231 @item @emph{Example}:
9232 @smallexample
9233 PROGRAM test_scan
9234   WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
9235   WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
9236   WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
9237 END PROGRAM
9238 @end smallexample
9239
9240 @item @emph{See also}:
9241 @ref{INDEX intrinsic}, @ref{VERIFY}
9242 @end table
9243
9244
9245
9246 @node SECNDS
9247 @section @code{SECNDS} --- Time function
9248 @fnindex SECNDS
9249 @cindex time, elapsed
9250 @cindex elapsed time
9251
9252 @table @asis
9253 @item @emph{Description}:
9254 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9255 @var{X} is a reference time, also in seconds. If this is zero, the time in
9256 seconds from midnight is returned. This function is non-standard and its
9257 use is discouraged.
9258
9259 @item @emph{Standard}:
9260 GNU extension
9261
9262 @item @emph{Class}:
9263 Function
9264
9265 @item @emph{Syntax}:
9266 @code{RESULT = SECNDS (X)}
9267
9268 @item @emph{Arguments}:
9269 @multitable @columnfractions .15 .70
9270 @item @var{T}     @tab Shall be of type @code{REAL(4)}.
9271 @item @var{X}     @tab Shall be of type @code{REAL(4)}.
9272 @end multitable
9273
9274 @item @emph{Return value}:
9275 None
9276
9277 @item @emph{Example}:
9278 @smallexample
9279 program test_secnds
9280     integer :: i
9281     real(4) :: t1, t2
9282     print *, secnds (0.0)   ! seconds since midnight
9283     t1 = secnds (0.0)       ! reference time
9284     do i = 1, 10000000      ! do something
9285     end do
9286     t2 = secnds (t1)        ! elapsed time
9287     print *, "Something took ", t2, " seconds."
9288 end program test_secnds
9289 @end smallexample
9290 @end table
9291
9292
9293
9294 @node SECOND
9295 @section @code{SECOND} --- CPU time function
9296 @fnindex SECOND
9297 @cindex time, elapsed
9298 @cindex elapsed time
9299
9300 @table @asis
9301 @item @emph{Description}:
9302 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9303 seconds.  This provides the same functionality as the standard
9304 @code{CPU_TIME} intrinsic, and is only included for backwards
9305 compatibility.
9306
9307 This intrinsic is provided in both subroutine and function forms;
9308 however, only one form can be used in any given program unit.
9309
9310 @item @emph{Standard}:
9311 GNU extension
9312
9313 @item @emph{Class}:
9314 Subroutine, function
9315
9316 @item @emph{Syntax}:
9317 @multitable @columnfractions .80
9318 @item @code{CALL SECOND(TIME)}
9319 @item @code{TIME = SECOND()}
9320 @end multitable
9321
9322 @item @emph{Arguments}:
9323 @multitable @columnfractions .15 .70
9324 @item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
9325 @end multitable
9326
9327 @item @emph{Return value}:
9328 In either syntax, @var{TIME} is set to the process's current runtime in
9329 seconds.
9330
9331 @item @emph{See also}:
9332 @ref{CPU_TIME}
9333
9334 @end table
9335
9336
9337
9338 @node SELECTED_CHAR_KIND
9339 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9340 @fnindex SELECTED_CHAR_KIND
9341 @cindex character kind
9342 @cindex kind, character
9343
9344 @table @asis
9345 @item @emph{Description}:
9346
9347 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9348 set named @var{NAME}, if a character set with such a name is supported,
9349 or @math{-1} otherwise. Currently, supported character sets include
9350 ``ASCII'' and ``DEFAULT'', which are equivalent.
9351
9352 @item @emph{Standard}:
9353 Fortran 2003 and later
9354
9355 @item @emph{Class}:
9356 Transformational function
9357
9358 @item @emph{Syntax}:
9359 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9360
9361 @item @emph{Arguments}:
9362 @multitable @columnfractions .15 .70
9363 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9364 @end multitable
9365
9366 @item @emph{Example}:
9367 @smallexample
9368 program ascii_kind
9369   integer,parameter :: ascii = selected_char_kind("ascii")
9370   character(kind=ascii, len=26) :: s
9371
9372   s = ascii_"abcdefghijklmnopqrstuvwxyz"
9373   print *, s
9374 end program ascii_kind
9375 @end smallexample
9376 @end table
9377
9378
9379
9380 @node SELECTED_INT_KIND
9381 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9382 @fnindex SELECTED_INT_KIND
9383 @cindex integer kind
9384 @cindex kind, integer
9385
9386 @table @asis
9387 @item @emph{Description}:
9388 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
9389 type that can represent all values ranging from @math{-10^I} (exclusive)
9390 to @math{10^I} (exclusive). If there is no integer kind that accommodates
9391 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9392
9393 @item @emph{Standard}:
9394 Fortran 95 and later
9395
9396 @item @emph{Class}:
9397 Transformational function
9398
9399 @item @emph{Syntax}:
9400 @code{RESULT = SELECTED_INT_KIND(I)}
9401
9402 @item @emph{Arguments}:
9403 @multitable @columnfractions .15 .70
9404 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
9405 @end multitable
9406
9407 @item @emph{Example}:
9408 @smallexample
9409 program large_integers
9410   integer,parameter :: k5 = selected_int_kind(5)
9411   integer,parameter :: k15 = selected_int_kind(15)
9412   integer(kind=k5) :: i5
9413   integer(kind=k15) :: i15
9414
9415   print *, huge(i5), huge(i15)
9416
9417   ! The following inequalities are always true
9418   print *, huge(i5) >= 10_k5**5-1
9419   print *, huge(i15) >= 10_k15**15-1
9420 end program large_integers
9421 @end smallexample
9422 @end table
9423
9424
9425
9426 @node SELECTED_REAL_KIND
9427 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9428 @fnindex SELECTED_REAL_KIND
9429 @cindex real kind
9430 @cindex kind, real
9431
9432 @table @asis
9433 @item @emph{Description}:
9434 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
9435 with decimal precision greater of at least @code{P} digits and exponent
9436 range greater at least @code{R}.
9437
9438 @item @emph{Standard}:
9439 Fortran 95 and later
9440
9441 @item @emph{Class}:
9442 Transformational function
9443
9444 @item @emph{Syntax}:
9445 @code{RESULT = SELECTED_REAL_KIND(P, R)}
9446
9447 @item @emph{Arguments}:
9448 @multitable @columnfractions .15 .70
9449 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9450 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9451 @end multitable
9452 At least one argument shall be present.
9453
9454 @item @emph{Return value}:
9455
9456 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9457 a real data type with decimal precision of at least @code{P} digits and a
9458 decimal exponent range of at least @code{R}. If more than one real data
9459 type meet the criteria, the kind of the data type with the smallest
9460 decimal precision is returned. If no real data type matches the criteria,
9461 the result is
9462 @table @asis
9463 @item -1 if the processor does not support a real data type with a
9464 precision greater than or equal to @code{P}
9465 @item -2 if the processor does not support a real type with an exponent
9466 range greater than or equal to @code{R}
9467 @item -3 if neither is supported.
9468 @end table
9469
9470 @item @emph{Example}:
9471 @smallexample
9472 program real_kinds
9473   integer,parameter :: p6 = selected_real_kind(6)
9474   integer,parameter :: p10r100 = selected_real_kind(10,100)
9475   integer,parameter :: r400 = selected_real_kind(r=400)
9476   real(kind=p6) :: x
9477   real(kind=p10r100) :: y
9478   real(kind=r400) :: z
9479
9480   print *, precision(x), range(x)
9481   print *, precision(y), range(y)
9482   print *, precision(z), range(z)
9483 end program real_kinds
9484 @end smallexample
9485 @end table
9486
9487
9488
9489 @node SET_EXPONENT
9490 @section @code{SET_EXPONENT} --- Set the exponent of the model
9491 @fnindex SET_EXPONENT
9492 @cindex real number, set exponent
9493 @cindex floating point, set exponent
9494
9495 @table @asis
9496 @item @emph{Description}:
9497 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9498 is that that of @var{X} and whose exponent part is @var{I}.
9499
9500 @item @emph{Standard}:
9501 Fortran 95 and later
9502
9503 @item @emph{Class}:
9504 Elemental function
9505
9506 @item @emph{Syntax}:
9507 @code{RESULT = SET_EXPONENT(X, I)}
9508
9509 @item @emph{Arguments}:
9510 @multitable @columnfractions .15 .70
9511 @item @var{X} @tab Shall be of type @code{REAL}.
9512 @item @var{I} @tab Shall be of type @code{INTEGER}.
9513 @end multitable
9514
9515 @item @emph{Return value}:
9516 The return value is of the same type and kind as @var{X}.
9517 The real number whose fractional part
9518 is that that of @var{X} and whose exponent part if @var{I} is returned;
9519 it is @code{FRACTION(X) * RADIX(X)**I}.
9520
9521 @item @emph{Example}:
9522 @smallexample
9523 PROGRAM test_setexp
9524   REAL :: x = 178.1387e-4
9525   INTEGER :: i = 17
9526   PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9527 END PROGRAM
9528 @end smallexample
9529
9530 @end table
9531
9532
9533
9534 @node SHAPE
9535 @section @code{SHAPE} --- Determine the shape of an array
9536 @fnindex SHAPE
9537 @cindex array, shape
9538
9539 @table @asis
9540 @item @emph{Description}:
9541 Determines the shape of an array.
9542
9543 @item @emph{Standard}:
9544 Fortran 95 and later
9545
9546 @item @emph{Class}:
9547 Inquiry function
9548
9549 @item @emph{Syntax}:
9550 @code{RESULT = SHAPE(SOURCE)}
9551
9552 @item @emph{Arguments}:
9553 @multitable @columnfractions .15 .70
9554 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9555 If @var{SOURCE} is a pointer it must be associated and allocatable
9556 arrays must be allocated.
9557 @end multitable
9558
9559 @item @emph{Return value}:
9560 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9561 has dimensions. The elements of the resulting array correspond to the extend
9562 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9563 the result is the rank one array of size zero.
9564
9565 @item @emph{Example}:
9566 @smallexample
9567 PROGRAM test_shape
9568   INTEGER, DIMENSION(-1:1, -1:2) :: A
9569   WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
9570   WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
9571 END PROGRAM
9572 @end smallexample
9573
9574 @item @emph{See also}:
9575 @ref{RESHAPE}, @ref{SIZE}
9576 @end table
9577
9578
9579
9580 @node SIGN
9581 @section @code{SIGN} --- Sign copying function
9582 @fnindex SIGN
9583 @fnindex ISIGN
9584 @fnindex DSIGN
9585 @cindex sign copying
9586
9587 @table @asis
9588 @item @emph{Description}:
9589 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9590
9591 @item @emph{Standard}:
9592 Fortran 77 and later
9593
9594 @item @emph{Class}:
9595 Elemental function
9596
9597 @item @emph{Syntax}:
9598 @code{RESULT = SIGN(A, B)}
9599
9600 @item @emph{Arguments}:
9601 @multitable @columnfractions .15 .70
9602 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9603 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9604 @end multitable
9605
9606 @item @emph{Return value}:
9607 The kind of the return value is that of @var{A} and @var{B}.
9608 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9609 it is @code{-ABS(A)}.
9610
9611 @item @emph{Example}:
9612 @smallexample
9613 program test_sign
9614   print *, sign(-12,1)
9615   print *, sign(-12,0)
9616   print *, sign(-12,-1)
9617
9618   print *, sign(-12.,1.)
9619   print *, sign(-12.,0.)
9620   print *, sign(-12.,-1.)
9621 end program test_sign
9622 @end smallexample
9623
9624 @item @emph{Specific names}:
9625 @multitable @columnfractions .20 .20 .20 .25
9626 @item Name              @tab Arguments      @tab Return type    @tab Standard
9627 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9628 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9629 @end multitable
9630 @end table
9631
9632
9633
9634 @node SIGNAL
9635 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9636 @fnindex SIGNAL
9637 @cindex system, signal handling
9638
9639 @table @asis
9640 @item @emph{Description}:
9641 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9642 @var{HANDLER} to be executed with a single integer argument when signal
9643 @var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
9644 turn off handling of signal @var{NUMBER} or revert to its default
9645 action.  See @code{signal(2)}.
9646
9647 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9648 is supplied, it is set to the value returned by @code{signal(2)}.
9649
9650 @item @emph{Standard}:
9651 GNU extension
9652
9653 @item @emph{Class}:
9654 Subroutine, function
9655
9656 @item @emph{Syntax}:
9657 @multitable @columnfractions .80
9658 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9659 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9660 @end multitable
9661
9662 @item @emph{Arguments}:
9663 @multitable @columnfractions .15 .70
9664 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9665 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9666 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9667 @code{INTEGER}. It is @code{INTENT(IN)}.
9668 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9669 integer. It has @code{INTENT(OUT)}.
9670 @end multitable
9671
9672 @item @emph{Return value}:
9673 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9674
9675 @item @emph{Example}:
9676 @smallexample
9677 program test_signal
9678   intrinsic signal
9679   external handler_print
9680
9681   call signal (12, handler_print)
9682   call signal (10, 1)
9683
9684   call sleep (30)
9685 end program test_signal
9686 @end smallexample
9687 @end table
9688
9689
9690
9691 @node SIN
9692 @section @code{SIN} --- Sine function
9693 @fnindex SIN
9694 @fnindex DSIN
9695 @fnindex CSIN
9696 @fnindex ZSIN
9697 @fnindex CDSIN
9698 @cindex trigonometric function, sine
9699 @cindex sine
9700
9701 @table @asis
9702 @item @emph{Description}:
9703 @code{SIN(X)} computes the sine of @var{X}.
9704
9705 @item @emph{Standard}:
9706 Fortran 77 and later
9707
9708 @item @emph{Class}:
9709 Elemental function
9710
9711 @item @emph{Syntax}:
9712 @code{RESULT = SIN(X)}
9713
9714 @item @emph{Arguments}:
9715 @multitable @columnfractions .15 .70
9716 @item @var{X} @tab The type shall be @code{REAL} or
9717 @code{COMPLEX}.
9718 @end multitable
9719
9720 @item @emph{Return value}:
9721 The return value has same type and kind as @var{X}.
9722
9723 @item @emph{Example}:
9724 @smallexample
9725 program test_sin
9726   real :: x = 0.0
9727   x = sin(x)
9728 end program test_sin
9729 @end smallexample
9730
9731 @item @emph{Specific names}:
9732 @multitable @columnfractions .20 .20 .20 .25
9733 @item Name            @tab Argument          @tab Return type       @tab Standard
9734 @item @code{DSIN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
9735 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
9736 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
9737 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
9738 @end multitable
9739
9740 @item @emph{See also}:
9741 @ref{ASIN}
9742 @end table
9743
9744
9745
9746 @node SINH
9747 @section @code{SINH} --- Hyperbolic sine function
9748 @fnindex SINH
9749 @fnindex DSINH
9750 @cindex hyperbolic sine
9751 @cindex hyperbolic function, sine
9752 @cindex sine, hyperbolic
9753
9754 @table @asis
9755 @item @emph{Description}:
9756 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9757
9758 @item @emph{Standard}:
9759 Fortran 95 and later
9760
9761 @item @emph{Class}:
9762 Elemental function
9763
9764 @item @emph{Syntax}:
9765 @code{RESULT = SINH(X)}
9766
9767 @item @emph{Arguments}:
9768 @multitable @columnfractions .15 .70
9769 @item @var{X} @tab The type shall be @code{REAL}.
9770 @end multitable
9771
9772 @item @emph{Return value}:
9773 The return value is of type @code{REAL}.
9774
9775 @item @emph{Example}:
9776 @smallexample
9777 program test_sinh
9778   real(8) :: x = - 1.0_8
9779   x = sinh(x)
9780 end program test_sinh
9781 @end smallexample
9782
9783 @item @emph{Specific names}:
9784 @multitable @columnfractions .20 .20 .20 .25
9785 @item Name            @tab Argument          @tab Return type       @tab Standard
9786 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
9787 @end multitable
9788
9789 @item @emph{See also}:
9790 @ref{ASINH}
9791 @end table
9792
9793
9794
9795 @node SIZE
9796 @section @code{SIZE} --- Determine the size of an array
9797 @fnindex SIZE
9798 @cindex array, size
9799 @cindex array, number of elements
9800 @cindex array, count elements
9801
9802 @table @asis
9803 @item @emph{Description}:
9804 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9805 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9806
9807 @item @emph{Standard}:
9808 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9809
9810 @item @emph{Class}:
9811 Inquiry function
9812
9813 @item @emph{Syntax}:
9814 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9815
9816 @item @emph{Arguments}:
9817 @multitable @columnfractions .15 .70
9818 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9819 a pointer it must be associated and allocatable arrays must be allocated.
9820 @item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
9821 and its value shall be in the range from 1 to n, where n equals the rank
9822 of @var{ARRAY}.
9823 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9824 expression indicating the kind parameter of the result.
9825 @end multitable
9826
9827 @item @emph{Return value}:
9828 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9829 @var{KIND} is absent, the return value is of default integer kind.
9830
9831 @item @emph{Example}:
9832 @smallexample
9833 PROGRAM test_size
9834   WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
9835 END PROGRAM
9836 @end smallexample
9837
9838 @item @emph{See also}:
9839 @ref{SHAPE}, @ref{RESHAPE}
9840 @end table
9841
9842
9843 @node SIZEOF
9844 @section @code{SIZEOF} --- Size in bytes of an expression
9845 @fnindex SIZEOF
9846 @cindex expression size
9847 @cindex size of an expression
9848
9849 @table @asis
9850 @item @emph{Description}:
9851 @code{SIZEOF(X)} calculates the number of bytes of storage the
9852 expression @code{X} occupies.
9853
9854 @item @emph{Standard}:
9855 GNU extension
9856
9857 @item @emph{Class}:
9858 Intrinsic function
9859
9860 @item @emph{Syntax}:
9861 @code{N = SIZEOF(X)}
9862
9863 @item @emph{Arguments}:
9864 @multitable @columnfractions .15 .70
9865 @item @var{X} @tab The argument shall be of any type, rank or shape.
9866 @end multitable
9867
9868 @item @emph{Return value}:
9869 The return value is of type integer and of the system-dependent kind
9870 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9871 number of bytes occupied by the argument.  If the argument has the
9872 @code{POINTER} attribute, the number of bytes of the storage area pointed
9873 to is returned.  If the argument is of a derived type with @code{POINTER}
9874 or @code{ALLOCATABLE} components, the return value doesn't account for
9875 the sizes of the data pointed to by these components.
9876
9877 @item @emph{Example}:
9878 @smallexample
9879    integer :: i
9880    real :: r, s(5)
9881    print *, (sizeof(s)/sizeof(r) == 5)
9882    end
9883 @end smallexample
9884 The example will print @code{.TRUE.} unless you are using a platform
9885 where default @code{REAL} variables are unusually padded.
9886
9887 @item @emph{See also}:
9888 @ref{C_SIZEOF}
9889 @end table
9890
9891
9892 @node SLEEP
9893 @section @code{SLEEP} --- Sleep for the specified number of seconds
9894 @fnindex SLEEP
9895 @cindex delayed execution
9896
9897 @table @asis
9898 @item @emph{Description}:
9899 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9900
9901 @item @emph{Standard}:
9902 GNU extension
9903
9904 @item @emph{Class}:
9905 Subroutine
9906
9907 @item @emph{Syntax}:
9908 @code{CALL SLEEP(SECONDS)}
9909
9910 @item @emph{Arguments}:
9911 @multitable @columnfractions .15 .70
9912 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9913 @end multitable
9914
9915 @item @emph{Example}:
9916 @smallexample
9917 program test_sleep
9918   call sleep(5)
9919 end
9920 @end smallexample
9921 @end table
9922
9923
9924
9925 @node SNGL
9926 @section @code{SNGL} --- Convert double precision real to default real
9927 @fnindex SNGL
9928 @cindex conversion, to real
9929
9930 @table @asis
9931 @item @emph{Description}:
9932 @code{SNGL(A)} converts the double precision real @var{A}
9933 to a default real value. This is an archaic form of @code{REAL}
9934 that is specific to one type for @var{A}.
9935
9936 @item @emph{Standard}:
9937 Fortran 77 and later
9938
9939 @item @emph{Class}:
9940 Elemental function
9941
9942 @item @emph{Syntax}:
9943 @code{RESULT = SNGL(A)}
9944
9945 @item @emph{Arguments}:
9946 @multitable @columnfractions .15 .70
9947 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9948 @end multitable
9949
9950 @item @emph{Return value}:
9951 The return value is of type default @code{REAL}.
9952
9953 @item @emph{See also}:
9954 @ref{DBLE}
9955 @end table
9956
9957
9958
9959 @node SPACING
9960 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9961 @fnindex SPACING
9962 @cindex real number, relative spacing
9963 @cindex floating point, relative spacing
9964
9965 @table @asis
9966 @item @emph{Description}:
9967 Determines the distance between the argument @var{X} and the nearest
9968 adjacent number of the same type.
9969
9970 @item @emph{Standard}:
9971 Fortran 95 and later
9972
9973 @item @emph{Class}:
9974 Elemental function
9975
9976 @item @emph{Syntax}:
9977 @code{RESULT = SPACING(X)}
9978
9979 @item @emph{Arguments}:
9980 @multitable @columnfractions .15 .70
9981 @item @var{X} @tab Shall be of type @code{REAL}.
9982 @end multitable
9983
9984 @item @emph{Return value}:
9985 The result is of the same type as the input argument @var{X}.
9986
9987 @item @emph{Example}:
9988 @smallexample
9989 PROGRAM test_spacing
9990   INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9991   INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9992
9993   WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
9994   WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
9995 END PROGRAM
9996 @end smallexample
9997
9998 @item @emph{See also}:
9999 @ref{RRSPACING}
10000 @end table
10001
10002
10003
10004 @node SPREAD
10005 @section @code{SPREAD} --- Add a dimension to an array
10006 @fnindex SPREAD
10007 @cindex array, increase dimension
10008 @cindex array, duplicate elements
10009 @cindex array, duplicate dimensions
10010
10011 @table @asis
10012 @item @emph{Description}:
10013 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10014 dimension @var{DIM}.
10015
10016 @item @emph{Standard}:
10017 Fortran 95 and later
10018
10019 @item @emph{Class}:
10020 Transformational function
10021
10022 @item @emph{Syntax}:
10023 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10024
10025 @item @emph{Arguments}:
10026 @multitable @columnfractions .15 .70
10027 @item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
10028 a rank less than seven.
10029 @item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
10030 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10031 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10032 @end multitable
10033
10034 @item @emph{Return value}:
10035 The result is an array of the same type as @var{SOURCE} and has rank n+1
10036 where n equals the rank of @var{SOURCE}.
10037
10038 @item @emph{Example}:
10039 @smallexample
10040 PROGRAM test_spread
10041   INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10042   WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
10043   WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
10044 END PROGRAM
10045 @end smallexample
10046
10047 @item @emph{See also}:
10048 @ref{UNPACK}
10049 @end table
10050
10051
10052
10053 @node SQRT
10054 @section @code{SQRT} --- Square-root function
10055 @fnindex SQRT
10056 @fnindex DSQRT
10057 @fnindex CSQRT
10058 @fnindex ZSQRT
10059 @fnindex CDSQRT
10060 @cindex root
10061 @cindex square-root
10062
10063 @table @asis
10064 @item @emph{Description}:
10065 @code{SQRT(X)} computes the square root of @var{X}.
10066
10067 @item @emph{Standard}:
10068 Fortran 77 and later
10069
10070 @item @emph{Class}:
10071 Elemental function
10072
10073 @item @emph{Syntax}:
10074 @code{RESULT = SQRT(X)}
10075
10076 @item @emph{Arguments}:
10077 @multitable @columnfractions .15 .70
10078 @item @var{X} @tab The type shall be @code{REAL} or
10079 @code{COMPLEX}.
10080 @end multitable
10081
10082 @item @emph{Return value}:
10083 The return value is of type @code{REAL} or @code{COMPLEX}.
10084 The kind type parameter is the same as @var{X}.
10085
10086 @item @emph{Example}:
10087 @smallexample
10088 program test_sqrt
10089   real(8) :: x = 2.0_8
10090   complex :: z = (1.0, 2.0)
10091   x = sqrt(x)
10092   z = sqrt(z)
10093 end program test_sqrt
10094 @end smallexample
10095
10096 @item @emph{Specific names}:
10097 @multitable @columnfractions .20 .20 .20 .25
10098 @item Name             @tab Argument             @tab Return type          @tab Standard
10099 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 95 and later
10100 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 95 and later
10101 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
10102 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
10103 @end multitable
10104 @end table
10105
10106
10107
10108 @node SRAND
10109 @section @code{SRAND} --- Reinitialize the random number generator
10110 @fnindex SRAND
10111 @cindex random number generation, seeding
10112 @cindex seeding a random number generator
10113
10114 @table @asis
10115 @item @emph{Description}:
10116 @code{SRAND} reinitializes the pseudo-random number generator
10117 called by @code{RAND} and @code{IRAND}. The new seed used by the
10118 generator is specified by the required argument @var{SEED}.
10119
10120 @item @emph{Standard}:
10121 GNU extension
10122
10123 @item @emph{Class}:
10124 Subroutine
10125
10126 @item @emph{Syntax}:
10127 @code{CALL SRAND(SEED)}
10128
10129 @item @emph{Arguments}:
10130 @multitable @columnfractions .15 .70
10131 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10132 @end multitable
10133
10134 @item @emph{Return value}:
10135 Does not return.
10136
10137 @item @emph{Example}:
10138 See @code{RAND} and @code{IRAND} for examples.
10139
10140 @item @emph{Notes}:
10141 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10142 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10143 to generate pseudo-random numbers. Please note that in
10144 GNU Fortran, these two sets of intrinsics (@code{RAND},
10145 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10146 @code{RANDOM_SEED} on the other hand) access two independent
10147 pseudo-random number generators.
10148
10149 @item @emph{See also}:
10150 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10151
10152 @end table
10153
10154
10155
10156 @node STAT
10157 @section @code{STAT} --- Get file status
10158 @fnindex STAT
10159 @cindex file system, file status
10160
10161 @table @asis
10162 @item @emph{Description}:
10163 This function returns information about a file. No permissions are required on
10164 the file itself, but execute (search) permission is required on all of the
10165 directories in path that lead to the file.
10166
10167 The elements that are obtained and stored in the array @code{BUFF}:
10168 @multitable @columnfractions .15 .70
10169 @item @code{buff(1)}   @tab  Device ID
10170 @item @code{buff(2)}   @tab  Inode number
10171 @item @code{buff(3)}   @tab  File mode
10172 @item @code{buff(4)}   @tab  Number of links
10173 @item @code{buff(5)}   @tab  Owner's uid
10174 @item @code{buff(6)}   @tab  Owner's gid
10175 @item @code{buff(7)}   @tab  ID of device containing directory entry for file (0 if not available)
10176 @item @code{buff(8)}   @tab  File size (bytes)
10177 @item @code{buff(9)}   @tab  Last access time
10178 @item @code{buff(10)}  @tab  Last modification time
10179 @item @code{buff(11)}  @tab  Last file status change time
10180 @item @code{buff(12)}  @tab  Preferred I/O block size (-1 if not available)
10181 @item @code{buff(13)}  @tab  Number of blocks allocated (-1 if not available)
10182 @end multitable
10183
10184 Not all these elements are relevant on all systems.
10185 If an element is not relevant, it is returned as 0.
10186
10187 This intrinsic is provided in both subroutine and function forms; however,
10188 only one form can be used in any given program unit.
10189
10190 @item @emph{Standard}:
10191 GNU extension
10192
10193 @item @emph{Class}:
10194 Subroutine, function
10195
10196 @item @emph{Syntax}:
10197 @code{CALL STAT(FILE,BUFF[,STATUS])}
10198
10199 @item @emph{Arguments}:
10200 @multitable @columnfractions .15 .70
10201 @item @var{FILE}   @tab The type shall be @code{CHARACTER}, of the
10202 default kind and a valid path within the file system.
10203 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10204 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10205 on success and a system specific error code otherwise.
10206 @end multitable
10207
10208 @item @emph{Example}:
10209 @smallexample
10210 PROGRAM test_stat
10211   INTEGER, DIMENSION(13) :: buff
10212   INTEGER :: status
10213
10214   CALL STAT("/etc/passwd", buff, status)
10215
10216   IF (status == 0) THEN
10217     WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
10218     WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
10219     WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
10220     WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
10221     WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
10222     WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
10223     WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
10224     WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
10225     WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
10226     WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
10227     WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10228     WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
10229     WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10230   END IF
10231 END PROGRAM
10232 @end smallexample
10233
10234 @item @emph{See also}:
10235 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10236 @end table
10237
10238
10239
10240 @node SUM
10241 @section @code{SUM} --- Sum of array elements
10242 @fnindex SUM
10243 @cindex array, sum
10244 @cindex array, add elements
10245 @cindex array, conditionally add elements
10246 @cindex sum array elements
10247
10248 @table @asis
10249 @item @emph{Description}:
10250 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10251 the corresponding element in @var{MASK} is @code{TRUE}.
10252
10253 @item @emph{Standard}:
10254 Fortran 95 and later
10255
10256 @item @emph{Class}:
10257 Transformational function
10258
10259 @item @emph{Syntax}:
10260 @code{RESULT = SUM(ARRAY[, MASK])}
10261 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10262
10263 @item @emph{Arguments}:
10264 @multitable @columnfractions .15 .70
10265 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10266 @code{REAL} or @code{COMPLEX}.
10267 @item @var{DIM}   @tab (Optional) shall be a scalar of type
10268 @code{INTEGER} with a value in the range from 1 to n, where n
10269 equals the rank of @var{ARRAY}.
10270 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
10271 and either be a scalar or an array of the same shape as @var{ARRAY}.
10272 @end multitable
10273
10274 @item @emph{Return value}:
10275 The result is of the same type as @var{ARRAY}.
10276
10277 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10278 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10279 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10280 dropped is returned.
10281
10282 @item @emph{Example}:
10283 @smallexample
10284 PROGRAM test_sum
10285   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10286   print *, SUM(x)                        ! all elements, sum = 15
10287   print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
10288 END PROGRAM
10289 @end smallexample
10290
10291 @item @emph{See also}:
10292 @ref{PRODUCT}
10293 @end table
10294
10295
10296
10297 @node SYMLNK
10298 @section @code{SYMLNK} --- Create a symbolic link
10299 @fnindex SYMLNK
10300 @cindex file system, create link
10301 @cindex file system, soft link
10302
10303 @table @asis
10304 @item @emph{Description}:
10305 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10306 character (@code{CHAR(0)}) can be used to mark the end of the names in
10307 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10308 names are ignored.  If the @var{STATUS} argument is supplied, it
10309 contains 0 on success or a nonzero error code upon return; see
10310 @code{symlink(2)}.  If the system does not supply @code{symlink(2)},
10311 @code{ENOSYS} is returned.
10312
10313 This intrinsic is provided in both subroutine and function forms;
10314 however, only one form can be used in any given program unit.
10315
10316 @item @emph{Standard}:
10317 GNU extension
10318
10319 @item @emph{Class}:
10320 Subroutine, function
10321
10322 @item @emph{Syntax}:
10323 @multitable @columnfractions .80
10324 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10325 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10326 @end multitable
10327
10328 @item @emph{Arguments}:
10329 @multitable @columnfractions .15 .70
10330 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10331 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10332 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10333 @end multitable
10334
10335 @item @emph{See also}:
10336 @ref{LINK}, @ref{UNLINK}
10337
10338 @end table
10339
10340
10341
10342 @node SYSTEM
10343 @section @code{SYSTEM} --- Execute a shell command
10344 @fnindex SYSTEM
10345 @cindex system, system call
10346
10347 @table @asis
10348 @item @emph{Description}:
10349 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10350 argument @var{STATUS} is present, it contains the value returned by
10351 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10352 Note that which shell is used to invoke the command is system-dependent
10353 and environment-dependent.
10354
10355 This intrinsic is provided in both subroutine and function forms;
10356 however, only one form can be used in any given program unit.
10357
10358 @item @emph{Standard}:
10359 GNU extension
10360
10361 @item @emph{Class}:
10362 Subroutine, function
10363
10364 @item @emph{Syntax}:
10365 @multitable @columnfractions .80
10366 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10367 @item @code{STATUS = SYSTEM(COMMAND)}
10368 @end multitable
10369
10370 @item @emph{Arguments}:
10371 @multitable @columnfractions .15 .70
10372 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10373 @item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
10374 @end multitable
10375
10376 @item @emph{See also}:
10377 @end table
10378
10379
10380
10381 @node SYSTEM_CLOCK
10382 @section @code{SYSTEM_CLOCK} --- Time function
10383 @fnindex SYSTEM_CLOCK
10384 @cindex time, clock ticks
10385 @cindex clock ticks
10386
10387 @table @asis
10388 @item @emph{Description}:
10389 Determines the @var{COUNT} of milliseconds of wall clock time since
10390 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10391 @var{COUNT_RATE} determines the number of clock ticks per second.
10392 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10393 @command{gfortran}.
10394
10395 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10396 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10397
10398 @item @emph{Standard}:
10399 Fortran 95 and later
10400
10401 @item @emph{Class}:
10402 Subroutine
10403
10404 @item @emph{Syntax}:
10405 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10406
10407 @item @emph{Arguments}:
10408 @item @emph{Arguments}:
10409 @multitable @columnfractions .15 .70
10410 @item @var{COUNT}      @tab (Optional) shall be a scalar of type default
10411 @code{INTEGER} with @code{INTENT(OUT)}.
10412 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10413 @code{INTEGER} with @code{INTENT(OUT)}.
10414 @item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type default
10415 @code{INTEGER} with @code{INTENT(OUT)}.
10416 @end multitable
10417
10418 @item @emph{Example}:
10419 @smallexample
10420 PROGRAM test_system_clock
10421   INTEGER :: count, count_rate, count_max
10422   CALL SYSTEM_CLOCK(count, count_rate, count_max)
10423   WRITE(*,*) count, count_rate, count_max
10424 END PROGRAM
10425 @end smallexample
10426
10427 @item @emph{See also}:
10428 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10429 @end table
10430
10431
10432
10433 @node TAN
10434 @section @code{TAN} --- Tangent function
10435 @fnindex TAN
10436 @fnindex DTAN
10437 @cindex trigonometric function, tangent
10438 @cindex tangent
10439
10440 @table @asis
10441 @item @emph{Description}:
10442 @code{TAN(X)} computes the tangent of @var{X}.
10443
10444 @item @emph{Standard}:
10445 Fortran 77 and later
10446
10447 @item @emph{Class}:
10448 Elemental function
10449
10450 @item @emph{Syntax}:
10451 @code{RESULT = TAN(X)}
10452
10453 @item @emph{Arguments}:
10454 @multitable @columnfractions .15 .70
10455 @item @var{X} @tab The type shall be @code{REAL}.
10456 @end multitable
10457
10458 @item @emph{Return value}:
10459 The return value is of type @code{REAL}.  The kind type parameter is
10460 the same as @var{X}.
10461
10462 @item @emph{Example}:
10463 @smallexample
10464 program test_tan
10465   real(8) :: x = 0.165_8
10466   x = tan(x)
10467 end program test_tan
10468 @end smallexample
10469
10470 @item @emph{Specific names}:
10471 @multitable @columnfractions .20 .20 .20 .25
10472 @item Name            @tab Argument          @tab Return type       @tab Standard
10473 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
10474 @end multitable
10475
10476 @item @emph{See also}:
10477 @ref{ATAN}
10478 @end table
10479
10480
10481
10482 @node TANH
10483 @section @code{TANH} --- Hyperbolic tangent function
10484 @fnindex TANH
10485 @fnindex DTANH
10486 @cindex hyperbolic tangent
10487 @cindex hyperbolic function, tangent
10488 @cindex tangent, hyperbolic
10489
10490 @table @asis
10491 @item @emph{Description}:
10492 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10493
10494 @item @emph{Standard}:
10495 Fortran 77 and later
10496
10497 @item @emph{Class}:
10498 Elemental function
10499
10500 @item @emph{Syntax}:
10501 @code{X = TANH(X)}
10502
10503 @item @emph{Arguments}:
10504 @multitable @columnfractions .15 .70
10505 @item @var{X} @tab The type shall be @code{REAL}.
10506 @end multitable
10507
10508 @item @emph{Return value}:
10509 The return value is of type @code{REAL} and lies in the range
10510 @math{ - 1 \leq tanh(x) \leq 1 }.
10511
10512 @item @emph{Example}:
10513 @smallexample
10514 program test_tanh
10515   real(8) :: x = 2.1_8
10516   x = tanh(x)
10517 end program test_tanh
10518 @end smallexample
10519
10520 @item @emph{Specific names}:
10521 @multitable @columnfractions .20 .20 .20 .25
10522 @item Name            @tab Argument          @tab Return type       @tab Standard
10523 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
10524 @end multitable
10525
10526 @item @emph{See also}:
10527 @ref{ATANH}
10528 @end table
10529
10530
10531
10532 @node TIME
10533 @section @code{TIME} --- Time function
10534 @fnindex TIME
10535 @cindex time, current
10536 @cindex current time
10537
10538 @table @asis
10539 @item @emph{Description}:
10540 Returns the current time encoded as an integer (in the manner of the
10541 UNIX function @code{time(3)}). This value is suitable for passing to
10542 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10543
10544 This intrinsic is not fully portable, such as to systems with 32-bit
10545 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10546 the values returned by this intrinsic might be, or become, negative, or
10547 numerically less than previous values, during a single run of the
10548 compiled program.
10549
10550 See @ref{TIME8}, for information on a similar intrinsic that might be
10551 portable to more GNU Fortran implementations, though to fewer Fortran
10552 compilers.
10553
10554 @item @emph{Standard}:
10555 GNU extension
10556
10557 @item @emph{Class}:
10558 Function
10559
10560 @item @emph{Syntax}:
10561 @code{RESULT = TIME()}
10562
10563 @item @emph{Return value}:
10564 The return value is a scalar of type @code{INTEGER(4)}.
10565
10566 @item @emph{See also}:
10567 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10568
10569 @end table
10570
10571
10572
10573 @node TIME8
10574 @section @code{TIME8} --- Time function (64-bit)
10575 @fnindex TIME8
10576 @cindex time, current
10577 @cindex current time
10578
10579 @table @asis
10580 @item @emph{Description}:
10581 Returns the current time encoded as an integer (in the manner of the
10582 UNIX function @code{time(3)}). This value is suitable for passing to
10583 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10584
10585 @emph{Warning:} this intrinsic does not increase the range of the timing
10586 values over that returned by @code{time(3)}. On a system with a 32-bit
10587 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10588 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10589 overflows of the 32-bit value can still occur. Therefore, the values
10590 returned by this intrinsic might be or become negative or numerically
10591 less than previous values during a single run of the compiled program.
10592
10593 @item @emph{Standard}:
10594 GNU extension
10595
10596 @item @emph{Class}:
10597 Function
10598
10599 @item @emph{Syntax}:
10600 @code{RESULT = TIME8()}
10601
10602 @item @emph{Return value}:
10603 The return value is a scalar of type @code{INTEGER(8)}.
10604
10605 @item @emph{See also}:
10606 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10607
10608 @end table
10609
10610
10611
10612 @node TINY
10613 @section @code{TINY} --- Smallest positive number of a real kind
10614 @fnindex TINY
10615 @cindex limits, smallest number
10616 @cindex model representation, smallest number
10617
10618 @table @asis
10619 @item @emph{Description}:
10620 @code{TINY(X)} returns the smallest positive (non zero) number
10621 in the model of the type of @code{X}.
10622
10623 @item @emph{Standard}:
10624 Fortran 95 and later
10625
10626 @item @emph{Class}:
10627 Inquiry function
10628
10629 @item @emph{Syntax}:
10630 @code{RESULT = TINY(X)}
10631
10632 @item @emph{Arguments}:
10633 @multitable @columnfractions .15 .70
10634 @item @var{X} @tab Shall be of type @code{REAL}.
10635 @end multitable
10636
10637 @item @emph{Return value}:
10638 The return value is of the same type and kind as @var{X}
10639
10640 @item @emph{Example}:
10641 See @code{HUGE} for an example.
10642 @end table
10643
10644
10645
10646 @node TRANSFER
10647 @section @code{TRANSFER} --- Transfer bit patterns
10648 @fnindex TRANSFER
10649 @cindex bits, move
10650 @cindex type cast
10651
10652 @table @asis
10653 @item @emph{Description}:
10654 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10655 is the representation of a variable or array of the same type and type
10656 parameters as @var{MOLD}.
10657
10658 This is approximately equivalent to the C concept of @emph{casting} one
10659 type to another.
10660
10661 @item @emph{Standard}:
10662 Fortran 95 and later
10663
10664 @item @emph{Class}:
10665 Transformational function
10666
10667 @item @emph{Syntax}:
10668 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10669
10670 @item @emph{Arguments}:
10671 @multitable @columnfractions .15 .70
10672 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10673 @item @var{MOLD}   @tab Shall be a scalar or an array of any type.
10674 @item @var{SIZE}   @tab (Optional) shall be a scalar of type
10675 @code{INTEGER}.
10676 @end multitable
10677
10678 @item @emph{Return value}:
10679 The result has the same type as @var{MOLD}, with the bit level
10680 representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
10681 a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
10682 but @var{MOLD} is an array (of any size or shape), the result is a one-
10683 dimensional array of the minimum length needed to contain the entirety
10684 of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
10685 and @var{MOLD} is a scalar, the result is a scalar.
10686
10687 If the bitwise representation of the result is longer than that of
10688 @var{SOURCE}, then the leading bits of the result correspond to those of
10689 @var{SOURCE} and any trailing bits are filled arbitrarily.
10690
10691 When the resulting bit representation does not correspond to a valid
10692 representation of a variable of the same type as @var{MOLD}, the results
10693 are undefined, and subsequent operations on the result cannot be
10694 guaranteed to produce sensible behavior.  For example, it is possible to
10695 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10696 @code{.NOT.@var{VAR}} both appear to be true.
10697
10698 @item @emph{Example}:
10699 @smallexample
10700 PROGRAM test_transfer
10701   integer :: x = 2143289344
10702   print *, transfer(x, 1.0)    ! prints "NaN" on i686
10703 END PROGRAM
10704 @end smallexample
10705 @end table
10706
10707
10708
10709 @node TRANSPOSE
10710 @section @code{TRANSPOSE} --- Transpose an array of rank two
10711 @fnindex TRANSPOSE
10712 @cindex array, transpose
10713 @cindex matrix, transpose
10714 @cindex transpose
10715
10716 @table @asis
10717 @item @emph{Description}:
10718 Transpose an array of rank two. Element (i, j) of the result has the value
10719 @code{MATRIX(j, i)}, for all i, j.
10720
10721 @item @emph{Standard}:
10722 Fortran 95 and later
10723
10724 @item @emph{Class}:
10725 Transformational function
10726
10727 @item @emph{Syntax}:
10728 @code{RESULT = TRANSPOSE(MATRIX)}
10729
10730 @item @emph{Arguments}:
10731 @multitable @columnfractions .15 .70
10732 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10733 @end multitable
10734
10735 @item @emph{Return value}:
10736 The result has the same type as @var{MATRIX}, and has shape
10737 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10738 @end table
10739
10740
10741
10742 @node TRIM
10743 @section @code{TRIM} --- Remove trailing blank characters of a string
10744 @fnindex TRIM
10745 @cindex string, remove trailing whitespace
10746
10747 @table @asis
10748 @item @emph{Description}:
10749 Removes trailing blank characters of a string.
10750
10751 @item @emph{Standard}:
10752 Fortran 95 and later
10753
10754 @item @emph{Class}:
10755 Transformational function
10756
10757 @item @emph{Syntax}:
10758 @code{RESULT = TRIM(STRING)}
10759
10760 @item @emph{Arguments}:
10761 @multitable @columnfractions .15 .70
10762 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
10763 @end multitable
10764
10765 @item @emph{Return value}:
10766 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
10767 less the number of trailing blanks.
10768
10769 @item @emph{Example}:
10770 @smallexample
10771 PROGRAM test_trim
10772   CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
10773   WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
10774 END PROGRAM
10775 @end smallexample
10776
10777 @item @emph{See also}:
10778 @ref{ADJUSTL}, @ref{ADJUSTR}
10779 @end table
10780
10781
10782
10783 @node TTYNAM
10784 @section @code{TTYNAM} --- Get the name of a terminal device.
10785 @fnindex TTYNAM
10786 @cindex system, terminal
10787
10788 @table @asis
10789 @item @emph{Description}:
10790 Get the name of a terminal device. For more information,
10791 see @code{ttyname(3)}.
10792
10793 This intrinsic is provided in both subroutine and function forms;
10794 however, only one form can be used in any given program unit.
10795
10796 @item @emph{Standard}:
10797 GNU extension
10798
10799 @item @emph{Class}:
10800 Subroutine, function
10801
10802 @item @emph{Syntax}:
10803 @multitable @columnfractions .80
10804 @item @code{CALL TTYNAM(UNIT, NAME)}
10805 @item @code{NAME = TTYNAM(UNIT)}
10806 @end multitable
10807
10808 @item @emph{Arguments}:
10809 @multitable @columnfractions .15 .70
10810 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
10811 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
10812 @end multitable
10813
10814 @item @emph{Example}:
10815 @smallexample
10816 PROGRAM test_ttynam
10817   INTEGER :: unit
10818   DO unit = 1, 10
10819     IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10820   END DO
10821 END PROGRAM
10822 @end smallexample
10823
10824 @item @emph{See also}:
10825 @ref{ISATTY}
10826 @end table
10827
10828
10829
10830 @node UBOUND
10831 @section @code{UBOUND} --- Upper dimension bounds of an array
10832 @fnindex UBOUND
10833 @cindex array, upper bound
10834
10835 @table @asis
10836 @item @emph{Description}:
10837 Returns the upper bounds of an array, or a single upper bound
10838 along the @var{DIM} dimension.
10839 @item @emph{Standard}:
10840 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10841
10842 @item @emph{Class}:
10843 Inquiry function
10844
10845 @item @emph{Syntax}:
10846 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10847
10848 @item @emph{Arguments}:
10849 @multitable @columnfractions .15 .70
10850 @item @var{ARRAY} @tab Shall be an array, of any type.
10851 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
10852 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10853 expression indicating the kind parameter of the result.
10854 @end multitable
10855
10856 @item @emph{Return value}:
10857 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10858 @var{KIND} is absent, the return value is of default integer kind.
10859 If @var{DIM} is absent, the result is an array of the upper bounds of
10860 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
10861 corresponding to the upper bound of the array along that dimension.  If
10862 @var{ARRAY} is an expression rather than a whole array or array
10863 structure component, or if it has a zero extent along the relevant
10864 dimension, the upper bound is taken to be the number of elements along
10865 the relevant dimension.
10866
10867 @item @emph{See also}:
10868 @ref{LBOUND}
10869 @end table
10870
10871
10872
10873 @node UMASK
10874 @section @code{UMASK} --- Set the file creation mask
10875 @fnindex UMASK
10876 @cindex file system, file creation mask
10877
10878 @table @asis
10879 @item @emph{Description}:
10880 Sets the file creation mask to @var{MASK} and returns the old value in
10881 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10882
10883 @item @emph{Standard}:
10884 GNU extension
10885
10886 @item @emph{Class}:
10887 Subroutine
10888
10889 @item @emph{Syntax}:
10890 @code{CALL UMASK(MASK [, OLD])}
10891
10892 @item @emph{Arguments}:
10893 @multitable @columnfractions .15 .70
10894 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
10895 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10896 @code{INTEGER}.
10897 @end multitable
10898
10899 @end table
10900
10901
10902
10903 @node UNLINK
10904 @section @code{UNLINK} --- Remove a file from the file system
10905 @fnindex UNLINK
10906 @cindex file system, remove file
10907
10908 @table @asis
10909 @item @emph{Description}:
10910 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10911 used to mark the end of the name in @var{PATH}; otherwise, trailing
10912 blanks in the file name are ignored.  If the @var{STATUS} argument is
10913 supplied, it contains 0 on success or a nonzero error code upon return;
10914 see @code{unlink(2)}.
10915
10916 This intrinsic is provided in both subroutine and function forms;
10917 however, only one form can be used in any given program unit.
10918
10919 @item @emph{Standard}:
10920 GNU extension
10921
10922 @item @emph{Class}:
10923 Subroutine, function
10924
10925 @item @emph{Syntax}:
10926 @multitable @columnfractions .80
10927 @item @code{CALL UNLINK(PATH [, STATUS])}
10928 @item @code{STATUS = UNLINK(PATH)}
10929 @end multitable
10930
10931 @item @emph{Arguments}:
10932 @multitable @columnfractions .15 .70
10933 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10934 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10935 @end multitable
10936
10937 @item @emph{See also}:
10938 @ref{LINK}, @ref{SYMLNK}
10939 @end table
10940
10941
10942
10943 @node UNPACK
10944 @section @code{UNPACK} --- Unpack an array of rank one into an array
10945 @fnindex UNPACK
10946 @cindex array, unpacking
10947 @cindex array, increase dimension
10948 @cindex array, scatter elements
10949
10950 @table @asis
10951 @item @emph{Description}:
10952 Store the elements of @var{VECTOR} in an array of higher rank.
10953
10954 @item @emph{Standard}:
10955 Fortran 95 and later
10956
10957 @item @emph{Class}:
10958 Transformational function
10959
10960 @item @emph{Syntax}:
10961 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10962
10963 @item @emph{Arguments}:
10964 @multitable @columnfractions .15 .70
10965 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10966 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10967 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
10968 @item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
10969 the same shape as @var{MASK}.
10970 @end multitable
10971
10972 @item @emph{Return value}:
10973 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10974 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10975
10976 @item @emph{Example}:
10977 @smallexample
10978 PROGRAM test_unpack
10979   integer :: vector(2)  = (/1,1/)
10980   logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10981   integer :: field(2,2) = 0, unity(2,2)
10982
10983   ! result: unity matrix
10984   unity = unpack(vector, reshape(mask, (/2,2/)), field)
10985 END PROGRAM
10986 @end smallexample
10987
10988 @item @emph{See also}:
10989 @ref{PACK}, @ref{SPREAD}
10990 @end table
10991
10992
10993
10994 @node VERIFY
10995 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10996 @fnindex VERIFY
10997 @cindex string, find missing set
10998
10999 @table @asis
11000 @item @emph{Description}:
11001 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11002
11003 If @var{BACK} is either absent or equals @code{FALSE}, this function
11004 returns the position of the leftmost character of @var{STRING} that is
11005 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11006 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11007 result is zero.
11008
11009 @item @emph{Standard}:
11010 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11011
11012 @item @emph{Class}:
11013 Elemental function
11014
11015 @item @emph{Syntax}:
11016 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11017
11018 @item @emph{Arguments}:
11019 @multitable @columnfractions .15 .70
11020 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11021 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
11022 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
11023 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
11024 expression indicating the kind parameter of the result.
11025 @end multitable
11026
11027 @item @emph{Return value}:
11028 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11029 @var{KIND} is absent, the return value is of default integer kind.
11030
11031 @item @emph{Example}:
11032 @smallexample
11033 PROGRAM test_verify
11034   WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
11035   WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
11036   WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
11037   WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
11038   WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
11039 END PROGRAM
11040 @end smallexample
11041
11042 @item @emph{See also}:
11043 @ref{SCAN}, @ref{INDEX intrinsic}
11044 @end table
11045
11046
11047
11048 @node XOR
11049 @section @code{XOR} --- Bitwise logical exclusive OR
11050 @fnindex XOR
11051 @cindex bitwise logical exclusive or
11052 @cindex logical exclusive or, bitwise
11053
11054 @table @asis
11055 @item @emph{Description}:
11056 Bitwise logical exclusive or.
11057
11058 This intrinsic routine is provided for backwards compatibility with
11059 GNU Fortran 77.  For integer arguments, programmers should consider
11060 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
11061
11062 @item @emph{Standard}:
11063 GNU extension
11064
11065 @item @emph{Class}:
11066 Function
11067
11068 @item @emph{Syntax}:
11069 @code{RESULT = XOR(X, Y)}
11070
11071 @item @emph{Arguments}:
11072 @multitable @columnfractions .15 .70
11073 @item @var{X} @tab The type shall be either  a scalar @code{INTEGER}
11074 type or a scalar @code{LOGICAL} type.
11075 @item @var{Y} @tab The type shall be the same as the type of @var{I}.
11076 @end multitable
11077
11078 @item @emph{Return value}:
11079 The return type is either a scalar @code{INTEGER} or a scalar
11080 @code{LOGICAL}.  If the kind type parameters differ, then the
11081 smaller kind type is implicitly converted to larger kind, and the
11082 return has the larger kind.
11083
11084 @item @emph{Example}:
11085 @smallexample
11086 PROGRAM test_xor
11087   LOGICAL :: T = .TRUE., F = .FALSE.
11088   INTEGER :: a, b
11089   DATA a / Z'F' /, b / Z'3' /
11090
11091   WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11092   WRITE (*,*) XOR(a, b)
11093 END PROGRAM
11094 @end smallexample
11095
11096 @item @emph{See also}:
11097 Fortran 95 elemental function: @ref{IEOR}
11098 @end table
11099
11100
11101
11102 @node Intrinsic Modules
11103 @chapter Intrinsic Modules
11104 @cindex intrinsic Modules
11105
11106 @c @node ISO_FORTRAN_ENV
11107 @section @code{ISO_FORTRAN_ENV}
11108 @table @asis
11109 @item @emph{Standard}:
11110 Fortran 2003 and later
11111 @end table
11112
11113 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11114 named constants:
11115
11116 @table @asis
11117 @item @code{CHARACTER_STORAGE_SIZE}:
11118 Size in bits of the character storage unit.
11119
11120 @item @code{ERROR_UNIT}:
11121 Identifies the preconnected unit used for error reporting.
11122
11123 @item @code{FILE_STORAGE_SIZE}:
11124 Size in bits of the file-storage unit.
11125
11126 @item @code{INPUT_UNIT}:
11127 Identifies the preconnected unit identified by the asterisk
11128 (@code{*}) in @code{READ} statement.
11129
11130 @item @code{IOSTAT_END}:
11131 The value assigned to the variable passed to the IOSTAT= specifier of
11132 an input/output statement if an end-of-file condition occurred.
11133
11134 @item @code{IOSTAT_EOR}:
11135 The value assigned to the variable passed to the IOSTAT= specifier of
11136 an input/output statement if an end-of-record condition occurred.
11137
11138 @item @code{NUMERIC_STORAGE_SIZE}:
11139 The size in bits of the numeric storage unit.
11140
11141 @item @code{OUTPUT_UNIT}:
11142 Identifies the preconnected unit identified by the asterisk
11143 (@code{*}) in @code{WRITE} statement.
11144 @end table
11145
11146 @c @node ISO_C_BINDING
11147 @section @code{ISO_C_BINDING}
11148 @table @asis
11149 @item @emph{Standard}:
11150 Fortran 2003 and later, GNU extensions
11151 @end table
11152
11153 The following intrinsic procedures are provided by the module; their
11154 definition can be found in the section Intrinsic Procedures of this
11155 manual.
11156
11157 @table @asis
11158 @item @code{C_ASSOCIATED}
11159 @item @code{C_F_POINTER}
11160 @item @code{C_F_PROCPOINTER}
11161 @item @code{C_FUNLOC}
11162 @item @code{C_LOC}
11163 @end table
11164
11165 The @code{ISO_C_BINDING} module provides the following named constants of the
11166 type integer, which can be used as KIND type parameter. Note that GNU
11167 Fortran currently does not support the @code{C_INT_FAST...} KIND type
11168 parameters (marked by an asterisk (@code{*}) in the list below).
11169 The @code{C_INT_FAST...} parameters have therefore the value @math{-2}
11170 and cannot be used as KIND type parameter of the @code{INTEGER} type.
11171
11172 In addition to the integer named constants required by the Fortran 2003
11173 standard, GNU Fortran provides as an extension named constants for the
11174 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11175 C_INT_LEAST128_T, C_INT_FAST128_T}.
11176
11177 @multitable @columnfractions .15 .35 .35 .35
11178 @item Fortran Type  @tab Named constant         @tab C type                                @tab Extension
11179 @item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
11180 @item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
11181 @item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
11182 @item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
11183 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
11184 @item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
11185 @item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
11186 @item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
11187 @item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
11188 @item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
11189 @item @code{INTEGER}@tab @code{C_INT128_T}       @tab @code{int128_t}                      @tab Ext.
11190 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
11191 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11192 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11193 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11194 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T} @tab @code{int_least128_t}                @tab Ext.
11195 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}*  @tab @code{int_fast8_t}
11196 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}* @tab @code{int_fast16_t}
11197 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}* @tab @code{int_fast32_t}
11198 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}* @tab @code{int_fast64_t}
11199 @item @code{INTEGER}@tab @code{C_INT_FAST128_T}* @tab @code{int_fast128_t}                 @tab Ext.
11200 @item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
11201 @item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
11202 @item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
11203 @item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
11204 @item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
11205 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11206 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11207 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11208 @item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
11209 @item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
11210 @end multitable
11211
11212 Additionally, the following @code{(CHARACTER(KIND=C_CHAR)} are
11213 defined.
11214
11215 @multitable @columnfractions .20 .45 .15
11216 @item Name                     @tab C definition    @tab Value
11217 @item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
11218 @item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
11219 @item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
11220 @item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
11221 @item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
11222 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11223 @item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
11224 @item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
11225 @end multitable
11226
11227 @c @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11228 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11229 @table @asis
11230 @item @emph{Standard}:
11231 OpenMP Application Program Interface v2.5
11232 @end table
11233
11234
11235 The OpenMP Fortran runtime library routines are provided both in
11236 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11237 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11238 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11239 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11240 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11241 below.
11242
11243 For details refer to the actual
11244 @uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
11245 OpenMP Application Program Interface v2.5}.
11246
11247 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11248 named constants:
11249
11250 @table @asis
11251 @item @code{omp_integer_kind}
11252 @item @code{omp_logical_kind}
11253 @item @code{omp_lock_kind}
11254 @item @code{omp_nest_lock_kind}
11255 @end table