gcc/fortran/intrinsic.texi

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