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