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 @table @asis
3970 @item @emph{Description}:
3971 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
3972 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
3973 if set to 1, @var{OFFSET} is taken to be relative to the current position
3974 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
3975 On error, @var{STATUS} is set to a non-zero value. If @var{STATUS} the seek
3976 fails silently.
3977
3978 This intrinsic routine is not fully backwards compatible with @command{g77}.
3979 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
3980 @var{STATUS} variable. If FSEEK is used in old code, change
3981 @smallexample
3982   CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
3983 @end smallexample
3984 to
3985 @smallexample
3986   INTEGER :: status
3987   CALL FSEEK(UNIT, OFFSET, WHENCE, status)
3988   IF (status /= 0) GOTO label
3989 @end smallexample
3990
3991 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
3992 Programmers should consider the use of new stream IO feature in new code
3993 for future portability. See also @ref{Fortran 2003 status}.
3994
3995 @item @emph{Standard}:
3996 GNU extension
3997
3998 @item @emph{Class}:
3999 Subroutine
4000
4001 @item @emph{Syntax}:
4002 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4003
4004 @item @emph{Arguments}:
4005 @multitable @columnfractions .15 .70
4006 @item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
4007 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4008 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4009 Its value shall be either 0, 1 or 2.
4010 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4011 @code{INTEGER(4)}.
4012 @end multitable
4013
4014 @item @emph{Example}:
4015 @smallexample
4016 PROGRAM test_fseek
4017   INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4018   INTEGER :: fd, offset, ierr
4019
4020   ierr   = 0
4021   offset = 5
4022   fd     = 10
4023
4024   OPEN(UNIT=fd, FILE="fseek.test")
4025   CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
4026   print *, FTELL(fd), ierr
4027
4028   CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
4029   print *, FTELL(fd), ierr
4030
4031   CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
4032   print *, FTELL(fd), ierr
4033
4034   CLOSE(UNIT=fd)
4035 END PROGRAM
4036 @end smallexample
4037
4038 @item @emph{See also}:
4039 @ref{FTELL}
4040 @end table
4041
4042
4043
4044 @node FSTAT
4045 @section @code{FSTAT} --- Get file status
4046 @fnindex FSTAT
4047 @cindex file system, file status
4048
4049 @table @asis
4050 @item @emph{Description}:
4051 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4052 already opened file is obtained.
4053
4054 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4055
4056 @item @emph{Standard}:
4057 GNU extension
4058
4059 @item @emph{Class}:
4060 Non-elemental subroutine
4061
4062 @item @emph{Syntax}:
4063 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4064
4065 @item @emph{Arguments}:
4066 @multitable @columnfractions .15 .70
4067 @item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
4068 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4069 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4070                         on success and a system specific error code otherwise.
4071 @end multitable
4072
4073 @item @emph{Example}:
4074 See @ref{STAT} for an example.
4075
4076 @item @emph{See also}:
4077 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4078 @end table
4079
4080
4081
4082 @node FTELL
4083 @section @code{FTELL} --- Current stream position
4084 @fnindex FTELL
4085 @cindex file operation, position
4086
4087 @table @asis
4088 @item @emph{Description}:
4089 Retrieves the current position within an open file.
4090
4091 This intrinsic is provided in both subroutine and function forms; however,
4092 only one form can be used in any given program unit.
4093
4094 @item @emph{Standard}:
4095 GNU extension
4096
4097 @item @emph{Class}:
4098 Subroutine, function
4099
4100 @item @emph{Syntax}:
4101 @multitable @columnfractions .80
4102 @item @code{CALL FTELL(UNIT, OFFSET)}
4103 @item @code{OFFSET = FTELL(UNIT)}
4104 @end multitable
4105
4106 @item @emph{Arguments}:
4107 @multitable @columnfractions .15 .70
4108 @item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
4109 @item @var{UNIT}    @tab Shall of type @code{INTEGER}.
4110 @end multitable
4111
4112 @item @emph{Return value}:
4113 In either syntax, @var{OFFSET} is set to the current offset of unit
4114 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4115
4116 @item @emph{Example}:
4117 @smallexample
4118 PROGRAM test_ftell
4119   INTEGER :: i
4120   OPEN(10, FILE="temp.dat")
4121   CALL ftell(10,i)
4122   WRITE(*,*) i
4123 END PROGRAM
4124 @end smallexample
4125
4126 @item @emph{See also}:
4127 @ref{FSEEK}
4128 @end table
4129
4130
4131
4132 @node GERROR
4133 @section @code{GERROR} --- Get last system error message
4134 @fnindex GERROR
4135 @cindex system, error handling
4136
4137 @table @asis
4138 @item @emph{Description}:
4139 Returns the system error message corresponding to the last system error.
4140 This resembles the functionality of @code{strerror(3)} in C.
4141
4142 @item @emph{Standard}:
4143 GNU extension
4144
4145 @item @emph{Class}:
4146 Subroutine
4147
4148 @item @emph{Syntax}:
4149 @code{CALL GERROR(RESULT)}
4150
4151 @item @emph{Arguments}:
4152 @multitable @columnfractions .15 .70
4153 @item @var{RESULT}  @tab Shall of type @code{CHARACTER(*)}.
4154 @end multitable
4155
4156 @item @emph{Example}:
4157 @smallexample
4158 PROGRAM test_gerror
4159   CHARACTER(len=100) :: msg
4160   CALL gerror(msg)
4161   WRITE(*,*) msg
4162 END PROGRAM
4163 @end smallexample
4164
4165 @item @emph{See also}:
4166 @ref{IERRNO}, @ref{PERROR}
4167 @end table
4168
4169
4170
4171 @node GETARG
4172 @section @code{GETARG} --- Get command line arguments
4173 @fnindex GETARG
4174 @cindex command-line arguments
4175 @cindex arguments, to program
4176
4177 @table @asis
4178 @item @emph{Description}:
4179 Retrieve the @var{N}th argument that was passed on the
4180 command line when the containing program was invoked.
4181
4182 This intrinsic routine is provided for backwards compatibility with
4183 GNU Fortran 77.  In new code, programmers should consider the use of
4184 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4185 standard.
4186
4187 @item @emph{Standard}:
4188 GNU extension
4189
4190 @item @emph{Class}:
4191 Subroutine
4192
4193 @item @emph{Syntax}:
4194 @code{CALL GETARG(N, ARG)}
4195
4196 @item @emph{Arguments}:
4197 @multitable @columnfractions .15 .70
4198 @item @var{N}   @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4199 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4200 @end multitable
4201
4202 @item @emph{Return value}:
4203 After @code{GETARG} returns, the @var{ARG} argument holds the @var{N}th
4204 command line argument. If @var{ARG} can not hold the argument, it is
4205 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4206 arguments specified at the command line, @var{ARG} will be filled with blanks.
4207 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4208 that support this feature).
4209
4210 @item @emph{Example}:
4211 @smallexample
4212 PROGRAM test_getarg
4213   INTEGER :: i
4214   CHARACTER(len=32) :: arg
4215
4216   DO i = 1, iargc()
4217     CALL getarg(i, arg)
4218     WRITE (*,*) arg
4219   END DO
4220 END PROGRAM
4221 @end smallexample
4222
4223 @item @emph{See also}:
4224 GNU Fortran 77 compatibility function: @ref{IARGC}
4225
4226 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4227 @ref{COMMAND_ARGUMENT_COUNT}
4228 @end table
4229
4230
4231
4232 @node GET_COMMAND
4233 @section @code{GET_COMMAND} --- Get the entire command line
4234 @fnindex GET_COMMAND
4235 @cindex command-line arguments
4236 @cindex arguments, to program
4237
4238 @table @asis
4239 @item @emph{Description}:
4240 Retrieve the entire command line that was used to invoke the program.
4241
4242 @item @emph{Standard}:
4243 F2003
4244
4245 @item @emph{Class}:
4246 Subroutine
4247
4248 @item @emph{Syntax}:
4249 @code{CALL GET_COMMAND(CMD)}
4250
4251 @item @emph{Arguments}:
4252 @multitable @columnfractions .15 .70
4253 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}.
4254 @end multitable
4255
4256 @item @emph{Return value}:
4257 Stores the entire command line that was used to invoke the program in @var{ARG}.
4258 If @var{ARG} is not large enough, the command will be truncated.
4259
4260 @item @emph{Example}:
4261 @smallexample
4262 PROGRAM test_get_command
4263   CHARACTER(len=255) :: cmd
4264   CALL get_command(cmd)
4265   WRITE (*,*) TRIM(cmd)
4266 END PROGRAM
4267 @end smallexample
4268
4269 @item @emph{See also}:
4270 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4271 @end table
4272
4273
4274
4275 @node GET_COMMAND_ARGUMENT
4276 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4277 @fnindex GET_COMMAND_ARGUMENT
4278 @cindex command-line arguments
4279 @cindex arguments, to program
4280
4281 @table @asis
4282 @item @emph{Description}:
4283 Retrieve the @var{N}th argument that was passed on the
4284 command line when the containing program was invoked.
4285
4286 @item @emph{Standard}:
4287 F2003
4288
4289 @item @emph{Class}:
4290 Subroutine
4291
4292 @item @emph{Syntax}:
4293 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4294
4295 @item @emph{Arguments}:
4296 @multitable @columnfractions .15 .70
4297 @item @var{N}   @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4298 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4299 @end multitable
4300
4301 @item @emph{Return value}:
4302 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the
4303 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is
4304 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4305 arguments specified at the command line, @var{ARG} will be filled with blanks.
4306 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4307 that support this feature).
4308
4309 @item @emph{Example}:
4310 @smallexample
4311 PROGRAM test_get_command_argument
4312   INTEGER :: i
4313   CHARACTER(len=32) :: arg
4314
4315   i = 0
4316   DO
4317     CALL get_command_argument(i, arg)
4318     IF (LEN_TRIM(arg) == 0) EXIT
4319
4320     WRITE (*,*) TRIM(arg)
4321     i = i+1
4322   END DO
4323 END PROGRAM
4324 @end smallexample
4325
4326 @item @emph{See also}:
4327 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4328 @end table
4329
4330
4331
4332 @node GETCWD
4333 @section @code{GETCWD} --- Get current working directory
4334 @fnindex GETCWD
4335 @cindex system, working directory
4336
4337 @table @asis
4338 @item @emph{Description}:
4339 Get current working directory.
4340
4341 @item @emph{Standard}:
4342 GNU extension
4343
4344 @item @emph{Class}:
4345 Non-elemental subroutine.
4346
4347 @item @emph{Syntax}:
4348 @code{CALL GETCWD(CWD [, STATUS])}
4349
4350 @item @emph{Arguments}:
4351 @multitable @columnfractions .15 .70
4352 @item @var{CWD}    @tab The type shall be @code{CHARACTER(*)}.
4353 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4354                         a system specific and non-zero error code otherwise.
4355 @end multitable
4356
4357 @item @emph{Example}:
4358 @smallexample
4359 PROGRAM test_getcwd
4360   CHARACTER(len=255) :: cwd
4361   CALL getcwd(cwd)
4362   WRITE(*,*) TRIM(cwd)
4363 END PROGRAM
4364 @end smallexample
4365
4366 @item @emph{See also}:
4367 @ref{CHDIR}
4368 @end table
4369
4370
4371
4372 @node GETENV
4373 @section @code{GETENV} --- Get an environmental variable
4374 @fnindex GETENV
4375 @cindex environment variable
4376
4377 @table @asis
4378 @item @emph{Description}:
4379 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4380
4381 This intrinsic routine is provided for backwards compatibility with
4382 GNU Fortran 77.  In new code, programmers should consider the use of
4383 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4384 2003 standard.
4385
4386 @item @emph{Standard}:
4387 GNU extension
4388
4389 @item @emph{Class}:
4390 Subroutine
4391
4392 @item @emph{Syntax}:
4393 @code{CALL GETENV(ENVVAR, VALUE)}
4394
4395 @item @emph{Arguments}:
4396 @multitable @columnfractions .15 .70
4397 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4398 @item @var{VALUE}  @tab Shall be of type @code{CHARACTER(*)}.
4399 @end multitable
4400
4401 @item @emph{Return value}:
4402 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4403 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4404 is not set, @var{VALUE} will be filled with blanks.
4405
4406 @item @emph{Example}:
4407 @smallexample
4408 PROGRAM test_getenv
4409   CHARACTER(len=255) :: homedir
4410   CALL getenv("HOME", homedir)
4411   WRITE (*,*) TRIM(homedir)
4412 END PROGRAM
4413 @end smallexample
4414
4415 @item @emph{See also}:
4416 @ref{GET_ENVIRONMENT_VARIABLE}
4417 @end table
4418
4419
4420
4421 @node GET_ENVIRONMENT_VARIABLE
4422 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4423 @fnindex GET_ENVIRONMENT_VARIABLE
4424 @cindex environment variable
4425
4426 @table @asis
4427 @item @emph{Description}:
4428 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4429
4430 @item @emph{Standard}:
4431 F2003
4432
4433 @item @emph{Class}:
4434 Subroutine
4435
4436 @item @emph{Syntax}:
4437 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4438
4439 @item @emph{Arguments}:
4440 @multitable @columnfractions .15 .70
4441 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4442 @item @var{VALUE}  @tab Shall be of type @code{CHARACTER(*)}.
4443 @end multitable
4444
4445 @item @emph{Return value}:
4446 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4447 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4448 is not set, @var{VALUE} will be filled with blanks.
4449
4450 @item @emph{Example}:
4451 @smallexample
4452 PROGRAM test_getenv
4453   CHARACTER(len=255) :: homedir
4454   CALL get_environment_variable("HOME", homedir)
4455   WRITE (*,*) TRIM(homedir)
4456 END PROGRAM
4457 @end smallexample
4458 @end table
4459
4460
4461
4462 @node GETGID
4463 @section @code{GETGID} --- Group ID function
4464 @fnindex GETGID
4465 @cindex system, group id
4466
4467 @table @asis
4468 @item @emph{Description}:
4469 Returns the numerical group ID of the current process.
4470
4471 @item @emph{Standard}:
4472 GNU extension
4473
4474 @item @emph{Class}:
4475 function
4476
4477 @item @emph{Syntax}:
4478 @code{RESULT = GETGID()}
4479
4480 @item @emph{Return value}:
4481 The return value of @code{GETGID} is an @code{INTEGER} of the default
4482 kind.
4483
4484
4485 @item @emph{Example}:
4486 See @code{GETPID} for an example.
4487
4488 @item @emph{See also}:
4489 @ref{GETPID}, @ref{GETUID}
4490 @end table
4491
4492
4493
4494 @node GETLOG
4495 @section @code{GETLOG} --- Get login name
4496 @fnindex GETLOG
4497 @cindex system, login name
4498 @cindex login name
4499
4500 @table @asis
4501 @item @emph{Description}:
4502 Gets the username under which the program is running.
4503
4504 @item @emph{Standard}:
4505 GNU extension
4506
4507 @item @emph{Class}:
4508 Subroutine
4509
4510 @item @emph{Syntax}:
4511 @code{CALL GETLOG(LOGIN)}
4512
4513 @item @emph{Arguments}:
4514 @multitable @columnfractions .15 .70
4515 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
4516 @end multitable
4517
4518 @item @emph{Return value}:
4519 Stores the current user name in @var{LOGIN}.  (On systems where POSIX
4520 functions @code{geteuid} and @code{getpwuid} are not available, and
4521 the @code{getlogin} function is not implemented either, this will
4522 return a blank string.)
4523
4524 @item @emph{Example}:
4525 @smallexample
4526 PROGRAM TEST_GETLOG
4527   CHARACTER(32) :: login
4528   CALL GETLOG(login)
4529   WRITE(*,*) login
4530 END PROGRAM
4531 @end smallexample
4532
4533 @item @emph{See also}:
4534 @ref{GETUID}
4535 @end table
4536
4537
4538
4539 @node GETPID
4540 @section @code{GETPID} --- Process ID function
4541 @fnindex GETPID
4542 @cindex system, process id
4543 @cindex process id
4544
4545 @table @asis
4546 @item @emph{Description}:
4547 Returns the numerical process identifier of the current process.
4548
4549 @item @emph{Standard}:
4550 GNU extension
4551
4552 @item @emph{Class}:
4553 function
4554
4555 @item @emph{Syntax}:
4556 @code{RESULT = GETPID()}
4557
4558 @item @emph{Return value}:
4559 The return value of @code{GETPID} is an @code{INTEGER} of the default
4560 kind.
4561
4562
4563 @item @emph{Example}:
4564 @smallexample
4565 program info
4566   print *, "The current process ID is ", getpid()
4567   print *, "Your numerical user ID is ", getuid()
4568   print *, "Your numerical group ID is ", getgid()
4569 end program info
4570 @end smallexample
4571
4572 @item @emph{See also}:
4573 @ref{GETGID}, @ref{GETUID}
4574 @end table
4575
4576
4577
4578 @node GETUID
4579 @section @code{GETUID} --- User ID function
4580 @fnindex GETUID
4581 @cindex system, user id
4582 @cindex user id
4583
4584 @table @asis
4585 @item @emph{Description}:
4586 Returns the numerical user ID of the current process.
4587
4588 @item @emph{Standard}:
4589 GNU extension
4590
4591 @item @emph{Class}:
4592 function
4593
4594 @item @emph{Syntax}:
4595 @code{RESULT = GETUID()}
4596
4597 @item @emph{Return value}:
4598 The return value of @code{GETUID} is an @code{INTEGER} of the default
4599 kind.
4600
4601
4602 @item @emph{Example}:
4603 See @code{GETPID} for an example.
4604
4605 @item @emph{See also}:
4606 @ref{GETPID}, @ref{GETLOG}
4607 @end table
4608
4609
4610
4611 @node GMTIME
4612 @section @code{GMTIME} --- Convert time to GMT info
4613 @fnindex GMTIME
4614 @cindex time, conversion to GMT info
4615
4616 @table @asis
4617 @item @emph{Description}:
4618 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
4619 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
4620 to the UTC time zone (Universal Coordinated Time, also known in some
4621 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
4622
4623 @item @emph{Standard}:
4624 GNU extension
4625
4626 @item @emph{Class}:
4627 Subroutine
4628
4629 @item @emph{Syntax}:
4630 @code{CALL GMTIME(STIME, TARRAY)}
4631
4632 @item @emph{Arguments}:
4633 @multitable @columnfractions .15 .70
4634 @item @var{STIME}  @tab An @code{INTEGER(*)} scalar expression
4635                         corresponding to a system time, with
4636                         @code{INTENT(IN)}.
4637 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
4638                         with @code{INTENT(OUT)}.
4639 @end multitable
4640
4641 @item @emph{Return value}:
4642 The elements of @var{TARRAY} are assigned as follows:
4643 @enumerate
4644 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
4645       seconds
4646 @item Minutes after the hour, range 0--59
4647 @item Hours past midnight, range 0--23
4648 @item Day of month, range 0--31
4649 @item Number of months since January, range 0--12
4650 @item Years since 1900
4651 @item Number of days since Sunday, range 0--6
4652 @item Days since January 1
4653 @item Daylight savings indicator: positive if daylight savings is in
4654       effect, zero if not, and negative if the information is not
4655       available.
4656 @end enumerate
4657
4658 @item @emph{See also}:
4659 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4660
4661 @end table
4662
4663
4664
4665 @node HOSTNM
4666 @section @code{HOSTNM} --- Get system host name
4667 @fnindex HOSTNM
4668 @cindex system, host name
4669
4670 @table @asis
4671 @item @emph{Description}:
4672 Retrieves the host name of the system on which the program is running.
4673
4674 This intrinsic is provided in both subroutine and function forms; however,
4675 only one form can be used in any given program unit.
4676
4677 @item @emph{Standard}:
4678 GNU extension
4679
4680 @item @emph{Class}:
4681 Subroutine, function
4682
4683 @item @emph{Syntax}:
4684 @multitable @columnfractions .80
4685 @item @code{CALL HOSTNM(NAME[, STATUS])}
4686 @item @code{STATUS = HOSTNM(NAME)}
4687 @end multitable
4688
4689 @item @emph{Arguments}:
4690 @multitable @columnfractions .15 .70
4691 @item @var{NAME}    @tab Shall of type @code{CHARACTER(*)}.
4692 @item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
4693                          Returns 0 on success, or a system specific error
4694                          code otherwise.
4695 @end multitable
4696
4697 @item @emph{Return value}:
4698 In either syntax, @var{NAME} is set to the current hostname if it can
4699 be obtained, or to a blank string otherwise.
4700
4701 @end table
4702
4703
4704
4705 @node HUGE
4706 @section @code{HUGE} --- Largest number of a kind
4707 @fnindex HUGE
4708 @cindex limits, largest number
4709 @cindex model representation, largest number
4710
4711 @table @asis
4712 @item @emph{Description}:
4713 @code{HUGE(X)} returns the largest number that is not an infinity in
4714 the model of the type of @code{X}.
4715
4716 @item @emph{Standard}:
4717 F95 and later
4718
4719 @item @emph{Class}:
4720 Inquiry function
4721
4722 @item @emph{Syntax}:
4723 @code{RESULT = HUGE(X)}
4724
4725 @item @emph{Arguments}:
4726 @multitable @columnfractions .15 .70
4727 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
4728 @end multitable
4729
4730 @item @emph{Return value}:
4731 The return value is of the same type and kind as @var{X}
4732
4733 @item @emph{Example}:
4734 @smallexample
4735 program test_huge_tiny
4736   print *, huge(0), huge(0.0), huge(0.0d0)
4737   print *, tiny(0.0), tiny(0.0d0)
4738 end program test_huge_tiny
4739 @end smallexample
4740 @end table
4741
4742
4743
4744 @node IACHAR
4745 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
4746 @fnindex IACHAR
4747 @cindex @acronym{ASCII} collating sequence
4748 @cindex collating sequence, @acronym{ASCII}
4749 @cindex conversion, to integer
4750
4751 @table @asis
4752 @item @emph{Description}:
4753 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
4754 in the first character position of @code{C}.
4755
4756 @item @emph{Standard}:
4757 F95 and later
4758
4759 @item @emph{Class}:
4760 Elemental function
4761
4762 @item @emph{Syntax}:
4763 @code{RESULT = IACHAR(C)}
4764
4765 @item @emph{Arguments}:
4766 @multitable @columnfractions .15 .70
4767 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
4768 @end multitable
4769
4770 @item @emph{Return value}:
4771 The return value is of type @code{INTEGER} and of the default integer
4772 kind.
4773
4774 @item @emph{Example}:
4775 @smallexample
4776 program test_iachar
4777   integer i
4778   i = iachar(' ')
4779 end program test_iachar
4780 @end smallexample
4781
4782 @item @emph{Note}:
4783 See @ref{ICHAR} for a discussion of converting between numerical values
4784 and formatted string representations.
4785
4786 @item @emph{See also}:
4787 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
4788
4789 @end table
4790
4791
4792
4793 @node IAND
4794 @section @code{IAND} --- Bitwise logical and
4795 @fnindex IAND
4796 @cindex bitwise logical and
4797 @cindex logical and, bitwise
4798
4799 @table @asis
4800 @item @emph{Description}:
4801 Bitwise logical @code{AND}.
4802
4803 @item @emph{Standard}:
4804 F95 and later
4805
4806 @item @emph{Class}:
4807 Elemental function
4808
4809 @item @emph{Syntax}:
4810 @code{RESULT = IAND(I, J)}
4811
4812 @item @emph{Arguments}:
4813 @multitable @columnfractions .15 .70
4814 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4815 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
4816 kind as @var{I}.  (As a GNU extension, different kinds are also
4817 permitted.)
4818 @end multitable
4819
4820 @item @emph{Return value}:
4821 The return type is @code{INTEGER(*)}, of the same kind as the
4822 arguments.  (If the argument kinds differ, it is of the same kind as
4823 the larger argument.)
4824
4825 @item @emph{Example}:
4826 @smallexample
4827 PROGRAM test_iand
4828   INTEGER :: a, b
4829   DATA a / Z'F' /, b / Z'3' /
4830   WRITE (*,*) IAND(a, b)
4831 END PROGRAM
4832 @end smallexample
4833
4834 @item @emph{See also}:
4835 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
4836
4837 @end table
4838
4839
4840
4841 @node IARGC
4842 @section @code{IARGC} --- Get the number of command line arguments
4843 @fnindex IARGC
4844 @cindex command-line arguments
4845 @cindex command-line arguments, number of
4846 @cindex arguments, to program
4847
4848 @table @asis
4849 @item @emph{Description}:
4850 @code{IARGC()} returns the number of arguments passed on the
4851 command line when the containing program was invoked.
4852
4853 This intrinsic routine is provided for backwards compatibility with
4854 GNU Fortran 77.  In new code, programmers should consider the use of
4855 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
4856 standard.
4857
4858 @item @emph{Standard}:
4859 GNU extension
4860
4861 @item @emph{Class}:
4862 Non-elemental Function
4863
4864 @item @emph{Syntax}:
4865 @code{RESULT = IARGC()}
4866
4867 @item @emph{Arguments}:
4868 None.
4869
4870 @item @emph{Return value}:
4871 The number of command line arguments, type @code{INTEGER(4)}.
4872
4873 @item @emph{Example}:
4874 See @ref{GETARG}
4875
4876 @item @emph{See also}:
4877 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
4878
4879 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4880 @ref{COMMAND_ARGUMENT_COUNT}
4881 @end table
4882
4883
4884
4885 @node IBCLR
4886 @section @code{IBCLR} --- Clear bit
4887 @fnindex IBCLR
4888 @cindex bits, unset
4889 @cindex bits, clear
4890
4891 @table @asis
4892 @item @emph{Description}:
4893 @code{IBCLR} returns the value of @var{I} with the bit at position
4894 @var{POS} set to zero.
4895
4896 @item @emph{Standard}:
4897 F95 and later
4898
4899 @item @emph{Class}:
4900 Elemental function
4901
4902 @item @emph{Syntax}:
4903 @code{RESULT = IBCLR(I, POS)}
4904
4905 @item @emph{Arguments}:
4906 @multitable @columnfractions .15 .70
4907 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4908 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
4909 @end multitable
4910
4911 @item @emph{Return value}:
4912 The return value is of type @code{INTEGER(*)} and of the same kind as
4913 @var{I}.
4914
4915 @item @emph{See also}:
4916 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
4917
4918 @end table
4919
4920
4921
4922 @node IBITS
4923 @section @code{IBITS} --- Bit extraction
4924 @fnindex IBITS
4925 @cindex bits, get
4926 @cindex bits, extract
4927
4928 @table @asis
4929 @item @emph{Description}:
4930 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
4931 starting from bit position @var{POS} and extending left for @var{LEN}
4932 bits.  The result is right-justified and the remaining bits are
4933 zeroed.  The value of @code{POS+LEN} must be less than or equal to the
4934 value @code{BIT_SIZE(I)}.
4935
4936 @item @emph{Standard}:
4937 F95 and later
4938
4939 @item @emph{Class}:
4940 Elemental function
4941
4942 @item @emph{Syntax}:
4943 @code{RESULT = IBITS(I, POS, LEN)}
4944
4945 @item @emph{Arguments}:
4946 @multitable @columnfractions .15 .70
4947 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4948 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
4949 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
4950 @end multitable
4951
4952 @item @emph{Return value}:
4953 The return value is of type @code{INTEGER(*)} and of the same kind as
4954 @var{I}.
4955
4956 @item @emph{See also}:
4957 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
4958 @end table
4959
4960
4961
4962 @node IBSET
4963 @section @code{IBSET} --- Set bit
4964 @fnindex IBSET
4965 @cindex bits, set
4966
4967 @table @asis
4968 @item @emph{Description}:
4969 @code{IBSET} returns the value of @var{I} with the bit at position
4970 @var{POS} set to one.
4971
4972 @item @emph{Standard}:
4973 F95 and later
4974
4975 @item @emph{Class}:
4976 Elemental function
4977
4978 @item @emph{Syntax}:
4979 @code{RESULT = IBSET(I, POS)}
4980
4981 @item @emph{Arguments}:
4982 @multitable @columnfractions .15 .70
4983 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4984 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
4985 @end multitable
4986
4987 @item @emph{Return value}:
4988 The return value is of type @code{INTEGER(*)} and of the same kind as
4989 @var{I}.
4990
4991 @item @emph{See also}:
4992 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
4993
4994 @end table
4995
4996
4997
4998 @node ICHAR
4999 @section @code{ICHAR} --- Character-to-integer conversion function
5000 @fnindex ICHAR
5001 @cindex conversion, to integer
5002
5003 @table @asis
5004 @item @emph{Description}:
5005 @code{ICHAR(C)} returns the code for the character in the first character
5006 position of @code{C} in the system's native character set.
5007 The correspondence between characters and their codes is not necessarily
5008 the same across different GNU Fortran implementations.
5009
5010 @item @emph{Standard}:
5011 F95 and later
5012
5013 @item @emph{Class}:
5014 Elemental function
5015
5016 @item @emph{Syntax}:
5017 @code{RESULT = ICHAR(C)}
5018
5019 @item @emph{Arguments}:
5020 @multitable @columnfractions .15 .70
5021 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5022 @end multitable
5023
5024 @item @emph{Return value}:
5025 The return value is of type @code{INTEGER} and of the default integer
5026 kind.
5027
5028 @item @emph{Example}:
5029 @smallexample
5030 program test_ichar
5031   integer i
5032   i = ichar(' ')
5033 end program test_ichar
5034 @end smallexample
5035
5036 @item @emph{Note}:
5037 No intrinsic exists to convert between a numeric value and a formatted
5038 character string representation -- for instance, given the
5039 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5040 @code{REAL} value with the value 154, or vice versa. Instead, this
5041 functionality is provided by internal-file I/O, as in the following
5042 example:
5043 @smallexample
5044 program read_val
5045   integer value
5046   character(len=10) string, string2
5047   string = '154'
5048
5049   ! Convert a string to a numeric value
5050   read (string,'(I10)') value
5051   print *, value
5052
5053   ! Convert a value to a formatted string
5054   write (string2,'(I10)') value
5055   print *, string2
5056 end program read_val
5057 @end smallexample
5058
5059 @item @emph{See also}:
5060 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5061
5062 @end table
5063
5064
5065
5066 @node IDATE
5067 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5068 @fnindex IDATE
5069 @cindex date, current
5070 @cindex current date
5071
5072 @table @asis
5073 @item @emph{Description}:
5074 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5075 current local time. The day (in the range 1-31), month (in the range 1-12),
5076 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5077 The year has four significant digits.
5078
5079 @item @emph{Standard}:
5080 GNU extension
5081
5082 @item @emph{Class}:
5083 Subroutine
5084
5085 @item @emph{Syntax}:
5086 @code{CALL IDATE(TARRAY)}
5087
5088 @item @emph{Arguments}:
5089 @multitable @columnfractions .15 .70
5090 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5091 the kind shall be the default integer kind.
5092 @end multitable
5093
5094 @item @emph{Return value}:
5095 Does not return.
5096
5097 @item @emph{Example}:
5098 @smallexample
5099 program test_idate
5100   integer, dimension(3) :: tarray
5101   call idate(tarray)
5102   print *, tarray(1)
5103   print *, tarray(2)
5104   print *, tarray(3)
5105 end program test_idate
5106 @end smallexample
5107 @end table
5108
5109
5110
5111 @node IEOR
5112 @section @code{IEOR} --- Bitwise logical exclusive or
5113 @fnindex IEOR
5114 @cindex bitwise logical exclusive or
5115 @cindex logical exclusive or, bitwise
5116
5117 @table @asis
5118 @item @emph{Description}:
5119 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5120 @var{J}.
5121
5122 @item @emph{Standard}:
5123 F95 and later
5124
5125 @item @emph{Class}:
5126 Elemental function
5127
5128 @item @emph{Syntax}:
5129 @code{RESULT = IEOR(I, J)}
5130
5131 @item @emph{Arguments}:
5132 @multitable @columnfractions .15 .70
5133 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5134 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5135 kind as @var{I}.  (As a GNU extension, different kinds are also
5136 permitted.)
5137 @end multitable
5138
5139 @item @emph{Return value}:
5140 The return type is @code{INTEGER(*)}, of the same kind as the
5141 arguments.  (If the argument kinds differ, it is of the same kind as
5142 the larger argument.)
5143
5144 @item @emph{See also}:
5145 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5146 @end table
5147
5148
5149
5150 @node IERRNO
5151 @section @code{IERRNO} --- Get the last system error number
5152 @fnindex IERRNO
5153 @cindex system, error handling
5154
5155 @table @asis
5156 @item @emph{Description}:
5157 Returns the last system error number, as given by the C @code{errno()}
5158 function.
5159
5160 @item @emph{Standard}:
5161 GNU extension
5162
5163 @item @emph{Class}:
5164 Non-elemental function
5165
5166 @item @emph{Syntax}:
5167 @code{RESULT = IERRNO()}
5168
5169 @item @emph{Arguments}:
5170 None.
5171
5172 @item @emph{Return value}:
5173 The return value is of type @code{INTEGER} and of the default integer
5174 kind.
5175
5176 @item @emph{See also}:
5177 @ref{PERROR}
5178 @end table
5179
5180
5181
5182 @node INDEX
5183 @section @code{INDEX} --- Position of a substring within a string
5184 @fnindex INDEX
5185 @cindex substring position
5186 @cindex string, find substring
5187
5188 @table @asis
5189 @item @emph{Description}:
5190 Returns the position of the start of the first occurrence of string
5191 @var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
5192 @var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
5193 the @var{BACK} argument is present and true, the return value is the
5194 start of the last occurrence rather than the first.
5195
5196 @item @emph{Standard}:
5197 F77 and later
5198
5199 @item @emph{Class}:
5200 Elemental function
5201
5202 @item @emph{Syntax}:
5203 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK])}
5204
5205 @item @emph{Arguments}:
5206 @multitable @columnfractions .15 .70
5207 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5208 @code{INTENT(IN)}
5209 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5210 @code{INTENT(IN)}
5211 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5212 @code{INTENT(IN)}
5213 @end multitable
5214
5215 @item @emph{Return value}:
5216 The return value is of type @code{INTEGER} and of the default integer
5217 kind.
5218
5219 @item @emph{See also}:
5220 @ref{SCAN}, @ref{VERIFY}
5221 @end table
5222
5223
5224
5225 @node INT
5226 @section @code{INT} --- Convert to integer type
5227 @fnindex INT
5228 @fnindex IFIX
5229 @fnindex IDINT
5230 @cindex conversion, to integer
5231
5232 @table @asis
5233 @item @emph{Description}:
5234 Convert to integer type
5235
5236 @item @emph{Standard}:
5237 F77 and later
5238
5239 @item @emph{Class}:
5240 Elemental function
5241
5242 @item @emph{Syntax}:
5243 @code{RESULT = INT(A [, KIND))}
5244
5245 @item @emph{Arguments}:
5246 @multitable @columnfractions .15 .70
5247 @item @var{A}    @tab Shall be of type @code{INTEGER(*)},
5248                       @code{REAL(*)}, or @code{COMPLEX(*)}.
5249 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5250                       expression indicating the kind parameter of
5251                       the result.
5252 @end multitable
5253
5254 @item @emph{Return value}:
5255 These functions return a @code{INTEGER(*)} variable or array under
5256 the following rules:
5257
5258 @table @asis
5259 @item (A)
5260 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
5261 @item (B)
5262 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5263 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5264 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5265 @item (C)
5266 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5267 @end table
5268
5269 @item @emph{Example}:
5270 @smallexample
5271 program test_int
5272   integer :: i = 42
5273   complex :: z = (-3.7, 1.0)
5274   print *, int(i)
5275   print *, int(z), int(z,8)
5276 end program
5277 @end smallexample
5278
5279 @item @emph{Specific names}:
5280 @multitable @columnfractions .20 .20 .20 .25
5281 @item Name             @tab Argument            @tab Return type       @tab Standard
5282 @item @code{IFIX(A)}   @tab @code{REAL(4) A}    @tab @code{INTEGER}    @tab F77 and later
5283 @item @code{IDINT(A)}  @tab @code{REAL(8) A}    @tab @code{INTEGER}    @tab F77 and later
5284 @end multitable
5285
5286 @end table
5287
5288
5289
5290 @node INT2
5291 @section @code{INT2} --- Convert to 16-bit integer type
5292 @fnindex INT2
5293 @fnindex SHORT
5294 @cindex conversion, to integer
5295
5296 @table @asis
5297 @item @emph{Description}:
5298 Convert to a @code{KIND=2} integer type. This is equivalent to the
5299 standard @code{INT} intrinsic with an optional argument of
5300 @code{KIND=2}, and is only included for backwards compatibility.
5301
5302 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5303
5304 @item @emph{Standard}:
5305 GNU extension.
5306
5307 @item @emph{Class}:
5308 Elemental function
5309
5310 @item @emph{Syntax}:
5311 @code{RESULT = INT2(A)}
5312
5313 @item @emph{Arguments}:
5314 @multitable @columnfractions .15 .70
5315 @item @var{A}    @tab Shall be of type @code{INTEGER(*)},
5316                       @code{REAL(*)}, or @code{COMPLEX(*)}.
5317 @end multitable
5318
5319 @item @emph{Return value}:
5320 The return value is a @code{INTEGER(2)} variable.
5321
5322 @item @emph{See also}:
5323 @ref{INT}, @ref{INT8}, @ref{LONG}
5324 @end table
5325
5326
5327
5328 @node INT8
5329 @section @code{INT8} --- Convert to 64-bit integer type
5330 @fnindex INT8
5331 @cindex conversion, to integer
5332
5333 @table @asis
5334 @item @emph{Description}:
5335 Convert to a @code{KIND=8} integer type. This is equivalent to the
5336 standard @code{INT} intrinsic with an optional argument of
5337 @code{KIND=8}, and is only included for backwards compatibility.
5338
5339 @item @emph{Standard}:
5340 GNU extension.
5341
5342 @item @emph{Class}:
5343 Elemental function
5344
5345 @item @emph{Syntax}:
5346 @code{RESULT = INT8(A)}
5347
5348 @item @emph{Arguments}:
5349 @multitable @columnfractions .15 .70
5350 @item @var{A}    @tab Shall be of type @code{INTEGER(*)},
5351                       @code{REAL(*)}, or @code{COMPLEX(*)}.
5352 @end multitable
5353
5354 @item @emph{Return value}:
5355 The return value is a @code{INTEGER(8)} variable.
5356
5357 @item @emph{See also}:
5358 @ref{INT}, @ref{INT2}, @ref{LONG}
5359 @end table
5360
5361
5362
5363 @node IOR
5364 @section @code{IOR} --- Bitwise logical or
5365 @fnindex IOR
5366 @cindex bitwise logical or
5367 @cindex logical or, bitwise
5368
5369 @table @asis
5370 @item @emph{Description}:
5371 @code{IEOR} returns the bitwise boolean OR of @var{I} and
5372 @var{J}.
5373
5374 @item @emph{Standard}:
5375 F95 and later
5376
5377 @item @emph{Class}:
5378 Elemental function
5379
5380 @item @emph{Syntax}:
5381 @code{RESULT = IEOR(I, J)}
5382
5383 @item @emph{Arguments}:
5384 @multitable @columnfractions .15 .70
5385 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5386 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5387 kind as @var{I}.  (As a GNU extension, different kinds are also
5388 permitted.)
5389 @end multitable
5390
5391 @item @emph{Return value}:
5392 The return type is @code{INTEGER(*)}, of the same kind as the
5393 arguments.  (If the argument kinds differ, it is of the same kind as
5394 the larger argument.)
5395
5396 @item @emph{See also}:
5397 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5398 @end table
5399
5400
5401
5402 @node IRAND
5403 @section @code{IRAND} --- Integer pseudo-random number
5404 @fnindex IRAND
5405 @cindex random number generation
5406
5407 @table @asis
5408 @item @emph{Description}:
5409 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5410 distribution between 0 and a system-dependent limit (which is in most
5411 cases 2147483647). If @var{FLAG} is 0, the next number
5412 in the current sequence is returned; if @var{FLAG} is 1, the generator
5413 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5414 it is used as a new seed with @code{SRAND}.
5415
5416 @item @emph{Standard}:
5417 GNU extension
5418
5419 @item @emph{Class}:
5420 Non-elemental function
5421
5422 @item @emph{Syntax}:
5423 @code{RESULT = IRAND(FLAG)}
5424
5425 @item @emph{Arguments}:
5426 @multitable @columnfractions .15 .70
5427 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5428 @end multitable
5429
5430 @item @emph{Return value}:
5431 The return value is of @code{INTEGER(kind=4)} type.
5432
5433 @item @emph{Example}:
5434 @smallexample
5435 program test_irand
5436   integer,parameter :: seed = 86456
5437
5438   call srand(seed)
5439   print *, irand(), irand(), irand(), irand()
5440   print *, irand(seed), irand(), irand(), irand()
5441 end program test_irand
5442 @end smallexample
5443
5444 @end table
5445
5446
5447
5448 @node ISATTY
5449 @section @code{ISATTY} --- Whether a unit is a terminal device.
5450 @fnindex ISATTY
5451 @cindex system, terminal
5452
5453 @table @asis
5454 @item @emph{Description}:
5455 Determine whether a unit is connected to a terminal device.
5456
5457 @item @emph{Standard}:
5458 GNU extension.
5459
5460 @item @emph{Class}:
5461 Non-elemental function.
5462
5463 @item @emph{Syntax}:
5464 @code{RESULT = ISATTY(UNIT)}
5465
5466 @item @emph{Arguments}:
5467 @multitable @columnfractions .15 .70
5468 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
5469 @end multitable
5470
5471 @item @emph{Return value}:
5472 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
5473 device, @code{.FALSE.} otherwise.
5474
5475 @item @emph{Example}:
5476 @smallexample
5477 PROGRAM test_isatty
5478   INTEGER(kind=1) :: unit
5479   DO unit = 1, 10
5480     write(*,*) isatty(unit=unit)
5481   END DO
5482 END PROGRAM
5483 @end smallexample
5484 @item @emph{See also}:
5485 @ref{TTYNAM}
5486 @end table
5487
5488
5489
5490 @node ISHFT
5491 @section @code{ISHFT} --- Shift bits
5492 @fnindex ISHFT
5493 @cindex bits, shift
5494
5495 @table @asis
5496 @item @emph{Description}:
5497 @code{ISHFT} returns a value corresponding to @var{I} with all of the
5498 bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
5499 zero corresponds to a left shift, a value of zero corresponds to no
5500 shift, and a value less than zero corresponds to a right shift.  If the
5501 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
5502 value is undefined.  Bits shifted out from the left end or right end are
5503 lost; zeros are shifted in from the opposite end.
5504
5505 @item @emph{Standard}:
5506 F95 and later
5507
5508 @item @emph{Class}:
5509 Elemental function
5510
5511 @item @emph{Syntax}:
5512 @code{RESULT = ISHFT(I, SHIFT)}
5513
5514 @item @emph{Arguments}:
5515 @multitable @columnfractions .15 .70
5516 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5517 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5518 @end multitable
5519
5520 @item @emph{Return value}:
5521 The return value is of type @code{INTEGER(*)} and of the same kind as
5522 @var{I}.
5523
5524 @item @emph{See also}:
5525 @ref{ISHFTC}
5526 @end table
5527
5528
5529
5530 @node ISHFTC
5531 @section @code{ISHFTC} --- Shift bits circularly
5532 @fnindex ISHFTC
5533 @cindex bits, shift circular
5534
5535 @table @asis
5536 @item @emph{Description}:
5537 @code{ISHFTC} returns a value corresponding to @var{I} with the
5538 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
5539 is, bits shifted out one end are shifted into the opposite end.  A value
5540 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
5541 zero corresponds to no shift, and a value less than zero corresponds to
5542 a right shift.  The absolute value of @var{SHIFT} must be less than
5543 @var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
5544 equivalent to @code{BIT_SIZE(I)}.
5545
5546 @item @emph{Standard}:
5547 F95 and later
5548
5549 @item @emph{Class}:
5550 Elemental function
5551
5552 @item @emph{Syntax}:
5553 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
5554
5555 @item @emph{Arguments}:
5556 @multitable @columnfractions .15 .70
5557 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5558 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5559 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
5560 the value must be greater than zero and less than or equal to
5561 @code{BIT_SIZE(I)}.
5562 @end multitable
5563
5564 @item @emph{Return value}:
5565 The return value is of type @code{INTEGER(*)} and of the same kind as
5566 @var{I}.
5567
5568 @item @emph{See also}:
5569 @ref{ISHFT}
5570 @end table
5571
5572
5573
5574 @node ITIME
5575 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
5576 @fnindex ITIME
5577 @cindex time, current
5578 @cindex current time
5579
5580 @table @asis
5581 @item @emph{Description}:
5582 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5583 current local time. The hour (in the range 1-24), minute (in the range 1-60),
5584 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY},
5585 respectively.
5586
5587 @item @emph{Standard}:
5588 GNU extension
5589
5590 @item @emph{Class}:
5591 Subroutine
5592
5593 @item @emph{Syntax}:
5594 @code{CALL ITIME(TARRAY)}
5595
5596 @item @emph{Arguments}:
5597 @multitable @columnfractions .15 .70
5598 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
5599 and the kind shall be the default integer kind.
5600 @end multitable
5601
5602 @item @emph{Return value}:
5603 Does not return.
5604
5605
5606 @item @emph{Example}:
5607 @smallexample
5608 program test_itime
5609   integer, dimension(3) :: tarray
5610   call itime(tarray)
5611   print *, tarray(1)
5612   print *, tarray(2)
5613   print *, tarray(3)
5614 end program test_itime
5615 @end smallexample
5616 @end table
5617
5618
5619
5620 @node KILL
5621 @section @code{KILL} --- Send a signal to a process
5622 @fnindex KILL
5623
5624 @table @asis
5625 @item @emph{Description}:
5626 @item @emph{Standard}:
5627 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
5628 See @code{kill(2)}.
5629
5630 @item @emph{Class}:
5631 Subroutine
5632
5633 @item @emph{Syntax}:
5634 @code{CALL KILL(PID, SIGNAL [, STATUS])}
5635
5636 @item @emph{Arguments}:
5637 @multitable @columnfractions .15 .70
5638 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
5639 @code{INTENT(IN)}
5640 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
5641 @code{INTENT(IN)}
5642 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
5643                         @code{INTEGER(8)}. Returns 0 on success, or a
5644                         system-specific error code otherwise.
5645 @end multitable
5646
5647 @item @emph{See also}:
5648 @ref{ABORT}, @ref{EXIT}
5649 @end table
5650
5651
5652
5653 @node KIND
5654 @section @code{KIND} --- Kind of an entity
5655 @fnindex KIND
5656 @cindex kind
5657
5658 @table @asis
5659 @item @emph{Description}:
5660 @code{KIND(X)} returns the kind value of the entity @var{X}.
5661
5662 @item @emph{Standard}:
5663 F95 and later
5664
5665 @item @emph{Class}:
5666 Inquiry function
5667
5668 @item @emph{Syntax}:
5669 @code{K = KIND(X)}
5670
5671 @item @emph{Arguments}:
5672 @multitable @columnfractions .15 .70
5673 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
5674 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
5675 @end multitable
5676
5677 @item @emph{Return value}:
5678 The return value is a scalar of type @code{INTEGER} and of the default
5679 integer kind.
5680
5681 @item @emph{Example}:
5682 @smallexample
5683 program test_kind
5684   integer,parameter :: kc = kind(' ')
5685   integer,parameter :: kl = kind(.true.)
5686
5687   print *, "The default character kind is ", kc
5688   print *, "The default logical kind is ", kl
5689 end program test_kind
5690 @end smallexample
5691
5692 @end table
5693
5694
5695
5696 @node LBOUND
5697 @section @code{LBOUND} --- Lower dimension bounds of an array
5698 @fnindex LBOUND
5699 @cindex array, lower bound
5700
5701 @table @asis
5702 @item @emph{Description}:
5703 Returns the lower bounds of an array, or a single lower bound
5704 along the @var{DIM} dimension.
5705 @item @emph{Standard}:
5706 F95 and later
5707
5708 @item @emph{Class}:
5709 Inquiry function
5710
5711 @item @emph{Syntax}:
5712 @code{RESULT = LBOUND(ARRAY [, DIM])}
5713
5714 @item @emph{Arguments}:
5715 @multitable @columnfractions .15 .70
5716 @item @var{ARRAY} @tab Shall be an array, of any type.
5717 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
5718 @end multitable
5719
5720 @item @emph{Return value}:
5721 If @var{DIM} is absent, the result is an array of the lower bounds of
5722 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
5723 corresponding to the lower bound of the array along that dimension.  If
5724 @var{ARRAY} is an expression rather than a whole array or array
5725 structure component, or if it has a zero extent along the relevant
5726 dimension, the lower bound is taken to be 1.
5727
5728 @item @emph{See also}:
5729 @ref{UBOUND}
5730 @end table
5731
5732
5733
5734 @node LEN
5735 @section @code{LEN} --- Length of a character entity
5736 @fnindex LEN
5737 @cindex string, length
5738
5739 @table @asis
5740 @item @emph{Description}:
5741 Returns the length of a character string.  If @var{STRING} is an array,
5742 the length of an element of @var{STRING} is returned.  Note that
5743 @var{STRING} need not be defined when this intrinsic is invoked, since
5744 only the length, not the content, of @var{STRING} is needed.
5745
5746 @item @emph{Standard}:
5747 F77 and later
5748
5749 @item @emph{Class}:
5750 Inquiry function
5751
5752 @item @emph{Syntax}:
5753 @code{L = LEN(STRING)}
5754
5755 @item @emph{Arguments}:
5756 @multitable @columnfractions .15 .70
5757 @item @var{STRING} @tab Shall be a scalar or array of type
5758 @code{CHARACTER(*)}, with @code{INTENT(IN)}
5759 @end multitable
5760
5761 @item @emph{Return value}:
5762 The return value is an @code{INTEGER} of the default kind.
5763
5764 @item @emph{See also}:
5765 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
5766 @end table
5767
5768
5769
5770 @node LEN_TRIM
5771 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
5772 @fnindex LEN_TRIM
5773 @cindex string, length, without trailing whitespace
5774
5775 @table @asis
5776 @item @emph{Description}:
5777 Returns the length of a character string, ignoring any trailing blanks.
5778
5779 @item @emph{Standard}:
5780 F95 and later
5781
5782 @item @emph{Class}:
5783 Elemental function
5784
5785 @item @emph{Syntax}:
5786 @code{RESULT = LEN_TRIM(STRING)}
5787
5788 @item @emph{Arguments}:
5789 @multitable @columnfractions .15 .70
5790 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
5791 with @code{INTENT(IN)}
5792 @end multitable
5793
5794 @item @emph{Return value}:
5795 The return value is an @code{INTEGER} of the default kind.
5796
5797 @item @emph{See also}:
5798 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
5799 @end table
5800
5801
5802
5803 @node LGE
5804 @section @code{LGE} --- Lexical greater than or equal
5805 @fnindex LGE
5806 @cindex lexical comparison of strings
5807 @cindex string, comparison
5808
5809 @table @asis
5810 @item @emph{Description}:
5811 Determines whether one string is lexically greater than or equal to
5812 another string, where the two strings are interpreted as containing
5813 ASCII character codes.  If the String A and String B are not the same
5814 length, the shorter is compared as if spaces were appended to it to form
5815 a value that has the same length as the longer.
5816
5817 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5818 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5819 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5820 that the latter use the processor's character ordering (which is not
5821 ASCII on some targets), whereas the former always use the ASCII
5822 ordering.
5823
5824 @item @emph{Standard}:
5825 F77 and later
5826
5827 @item @emph{Class}:
5828 Elemental function
5829
5830 @item @emph{Syntax}:
5831 @code{RESULT = LGE(STRING_A, STRING_B)}
5832
5833 @item @emph{Arguments}:
5834 @multitable @columnfractions .15 .70
5835 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5836 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5837 @end multitable
5838
5839 @item @emph{Return value}:
5840 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
5841 otherwise, based on the ASCII ordering.
5842
5843 @item @emph{See also}:
5844 @ref{LGT}, @ref{LLE}, @ref{LLT}
5845 @end table
5846
5847
5848
5849 @node LGT
5850 @section @code{LGT} --- Lexical greater than
5851 @fnindex LGT
5852 @cindex lexical comparison of strings
5853 @cindex string, comparison
5854
5855 @table @asis
5856 @item @emph{Description}:
5857 Determines whether one string is lexically greater than another string,
5858 where the two strings are interpreted as containing ASCII character
5859 codes.  If the String A and String B are not the same length, the
5860 shorter is compared as if spaces were appended to it to form a value
5861 that has the same length as the longer.
5862
5863 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5864 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5865 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5866 that the latter use the processor's character ordering (which is not
5867 ASCII on some targets), whereas the former always use the ASCII
5868 ordering.
5869
5870 @item @emph{Standard}:
5871 F77 and later
5872
5873 @item @emph{Class}:
5874 Elemental function
5875
5876 @item @emph{Syntax}:
5877 @code{RESULT = LGT(STRING_A, STRING_B)}
5878
5879 @item @emph{Arguments}:
5880 @multitable @columnfractions .15 .70
5881 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5882 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5883 @end multitable
5884
5885 @item @emph{Return value}:
5886 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
5887 otherwise, based on the ASCII ordering.
5888
5889 @item @emph{See also}:
5890 @ref{LGE}, @ref{LLE}, @ref{LLT}
5891 @end table
5892
5893
5894
5895 @node LINK
5896 @section @code{LINK} --- Create a hard link
5897 @fnindex LINK
5898 @cindex file system, create link
5899 @cindex file system, hard link
5900
5901 @table @asis
5902 @item @emph{Description}:
5903 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
5904 character (@code{CHAR(0)}) can be used to mark the end of the names in
5905 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
5906 names are ignored.  If the @var{STATUS} argument is supplied, it
5907 contains 0 on success or a nonzero error code upon return; see
5908 @code{link(2)}.
5909
5910 This intrinsic is provided in both subroutine and function forms;
5911 however, only one form can be used in any given program unit.
5912
5913 @item @emph{Standard}:
5914 GNU extension
5915
5916 @item @emph{Class}:
5917 Subroutine, non-elemental function
5918
5919 @item @emph{Syntax}:
5920 @multitable @columnfractions .80
5921 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
5922 @item @code{STATUS = LINK(PATH1, PATH2)}
5923 @end multitable
5924
5925 @item @emph{Arguments}:
5926 @multitable @columnfractions .15 .70
5927 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
5928 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
5929 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
5930 @end multitable
5931
5932 @item @emph{See also}:
5933 @ref{SYMLNK}, @ref{UNLINK}
5934 @end table
5935
5936
5937
5938 @node LLE
5939 @section @code{LLE} --- Lexical less than or equal
5940 @fnindex LLE
5941 @cindex lexical comparison of strings
5942 @cindex string, comparison
5943
5944 @table @asis
5945 @item @emph{Description}:
5946 Determines whether one string is lexically less than or equal to another
5947 string, where the two strings are interpreted as containing ASCII
5948 character codes.  If the String A and String B are not the same length,
5949 the shorter is compared as if spaces were appended to it to form a value
5950 that has the same length as the longer.
5951
5952 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5953 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5954 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5955 that the latter use the processor's character ordering (which is not
5956 ASCII on some targets), whereas the former always use the ASCII
5957 ordering.
5958
5959 @item @emph{Standard}:
5960 F77 and later
5961
5962 @item @emph{Class}:
5963 Elemental function
5964
5965 @item @emph{Syntax}:
5966 @code{RESULT = LLE(STRING_A, STRING_B)}
5967
5968 @item @emph{Arguments}:
5969 @multitable @columnfractions .15 .70
5970 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5971 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5972 @end multitable
5973
5974 @item @emph{Return value}:
5975 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
5976 otherwise, based on the ASCII ordering.
5977
5978 @item @emph{See also}:
5979 @ref{LGE}, @ref{LGT}, @ref{LLT}
5980 @end table
5981
5982
5983
5984 @node LLT
5985 @section @code{LLT} --- Lexical less than
5986 @fnindex LLT
5987 @cindex lexical comparison of strings
5988 @cindex string, comparison
5989
5990 @table @asis
5991 @item @emph{Description}:
5992 Determines whether one string is lexically less than another string,
5993 where the two strings are interpreted as containing ASCII character
5994 codes.  If the String A and String B are not the same length, the
5995 shorter is compared as if spaces were appended to it to form a value
5996 that has the same length as the longer.
5997
5998 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5999 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6000 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6001 that the latter use the processor's character ordering (which is not
6002 ASCII on some targets), whereas the former always use the ASCII
6003 ordering.
6004
6005 @item @emph{Standard}:
6006 F77 and later
6007
6008 @item @emph{Class}:
6009 Elemental function
6010
6011 @item @emph{Syntax}:
6012 @code{RESULT = LLT(STRING_A, STRING_B)}
6013
6014 @item @emph{Arguments}:
6015 @multitable @columnfractions .15 .70
6016 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6017 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6018 @end multitable
6019
6020 @item @emph{Return value}:
6021 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6022 otherwise, based on the ASCII ordering.
6023
6024 @item @emph{See also}:
6025 @ref{LGE}, @ref{LGT}, @ref{LLE}
6026 @end table
6027
6028
6029
6030 @node LNBLNK
6031 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6032 @fnindex LNBLNK
6033 @cindex string, find non-blank character
6034
6035 @table @asis
6036 @item @emph{Description}:
6037 Returns the length of a character string, ignoring any trailing blanks.
6038 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6039 included for backwards compatibility.
6040
6041 @item @emph{Standard}:
6042 GNU extension
6043
6044 @item @emph{Class}:
6045 Elemental function
6046
6047 @item @emph{Syntax}:
6048 @code{RESULT = LNBLNK(STRING)}
6049
6050 @item @emph{Arguments}:
6051 @multitable @columnfractions .15 .70
6052 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6053 with @code{INTENT(IN)}
6054 @end multitable
6055
6056 @item @emph{Return value}:
6057 The return value is of @code{INTEGER(kind=4)} type.
6058
6059 @item @emph{See also}:
6060 @ref{INDEX}, @ref{LEN_TRIM}
6061 @end table
6062
6063
6064
6065 @node LOC
6066 @section @code{LOC} --- Returns the address of a variable
6067 @fnindex LOC
6068 @cindex location of a variable in memory
6069
6070 @table @asis
6071 @item @emph{Description}:
6072 @code{LOC(X)} returns the address of @var{X} as an integer.
6073
6074 @item @emph{Standard}:
6075 GNU extension
6076
6077 @item @emph{Class}:
6078 Inquiry function
6079
6080 @item @emph{Syntax}:
6081 @code{RESULT = LOC(X)}
6082
6083 @item @emph{Arguments}:
6084 @multitable @columnfractions .15 .70
6085 @item @var{X} @tab Variable of any type.
6086 @end multitable
6087
6088 @item @emph{Return value}:
6089 The return value is of type @code{INTEGER}, with a @code{KIND}
6090 corresponding to the size (in bytes) of a memory address on the target
6091 machine.
6092
6093 @item @emph{Example}:
6094 @smallexample
6095 program test_loc
6096   integer :: i
6097   real :: r
6098   i = loc(r)
6099   print *, i
6100 end program test_loc
6101 @end smallexample
6102 @end table
6103
6104
6105
6106 @node LOG
6107 @section @code{LOG} --- Logarithm function
6108 @fnindex LOG
6109 @fnindex ALOG
6110 @fnindex DLOG
6111 @fnindex CLOG
6112 @fnindex ZLOG
6113 @fnindex CDLOG
6114 @cindex exponential function, inverse
6115 @cindex logarithmic function
6116
6117 @table @asis
6118 @item @emph{Description}:
6119 @code{LOG(X)} computes the logarithm of @var{X}.
6120
6121 @item @emph{Standard}:
6122 F77 and later
6123
6124 @item @emph{Class}:
6125 Elemental function
6126
6127 @item @emph{Syntax}:
6128 @code{RESULT = LOG(X)}
6129
6130 @item @emph{Arguments}:
6131 @multitable @columnfractions .15 .70
6132 @item @var{X} @tab The type shall be @code{REAL(*)} or
6133 @code{COMPLEX(*)}.
6134 @end multitable
6135
6136 @item @emph{Return value}:
6137 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6138 The kind type parameter is the same as @var{X}.
6139
6140 @item @emph{Example}:
6141 @smallexample
6142 program test_log
6143   real(8) :: x = 1.0_8
6144   complex :: z = (1.0, 2.0)
6145   x = log(x)
6146   z = log(z)
6147 end program test_log
6148 @end smallexample
6149
6150 @item @emph{Specific names}:
6151 @multitable @columnfractions .20 .20 .20 .25
6152 @item Name            @tab Argument          @tab Return type       @tab Standard
6153 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
6154 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
6155 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
6156 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
6157 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
6158 @end multitable
6159 @end table
6160
6161
6162
6163 @node LOG10
6164 @section @code{LOG10} --- Base 10 logarithm function
6165 @fnindex LOG10
6166 @fnindex ALOG10
6167 @fnindex DLOG10
6168 @cindex exponential function, inverse
6169 @cindex logarithmic function
6170
6171 @table @asis
6172 @item @emph{Description}:
6173 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6174
6175 @item @emph{Standard}:
6176 F77 and later
6177
6178 @item @emph{Class}:
6179 Elemental function
6180
6181 @item @emph{Syntax}:
6182 @code{RESULT = LOG10(X)}
6183
6184 @item @emph{Arguments}:
6185 @multitable @columnfractions .15 .70
6186 @item @var{X} @tab The type shall be @code{REAL(*)}.
6187 @end multitable
6188
6189 @item @emph{Return value}:
6190 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6191 The kind type parameter is the same as @var{X}.
6192
6193 @item @emph{Example}:
6194 @smallexample
6195 program test_log10
6196   real(8) :: x = 10.0_8
6197   x = log10(x)
6198 end program test_log10
6199 @end smallexample
6200
6201 @item @emph{Specific names}:
6202 @multitable @columnfractions .20 .20 .20 .25
6203 @item Name            @tab Argument          @tab Return type       @tab Standard
6204 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab F95 and later
6205 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F95 and later
6206 @end multitable
6207 @end table
6208
6209
6210
6211 @node LOGICAL
6212 @section @code{LOGICAL} --- Convert to logical type
6213 @fnindex LOGICAL
6214 @cindex conversion, to logical
6215
6216 @table @asis
6217 @item @emph{Description}:
6218 Converts one kind of @code{LOGICAL} variable to another.
6219
6220 @item @emph{Standard}:
6221 F95 and later
6222
6223 @item @emph{Class}:
6224 Elemental function
6225
6226 @item @emph{Syntax}:
6227 @code{RESULT = LOGICAL(L [, KIND])}
6228
6229 @item @emph{Arguments}:
6230 @multitable @columnfractions .15 .70
6231 @item @var{L}    @tab The type shall be @code{LOGICAL(*)}.
6232 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6233                       expression indicating the kind parameter of
6234                       the result.
6235 @end multitable
6236
6237 @item @emph{Return value}:
6238 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6239 kind corresponding to @var{KIND}, or of the default logical kind if
6240 @var{KIND} is not given.
6241
6242 @item @emph{See also}:
6243 @ref{INT}, @ref{REAL}, @ref{CMPLX}
6244 @end table
6245
6246
6247
6248 @node LONG
6249 @section @code{LONG} --- Convert to integer type
6250 @fnindex LONG
6251 @cindex conversion, to integer
6252
6253 @table @asis
6254 @item @emph{Description}:
6255 Convert to a @code{KIND=4} integer type, which is the same size as a C
6256 @code{long} integer.  This is equivalent to the standard @code{INT}
6257 intrinsic with an optional argument of @code{KIND=4}, and is only
6258 included for backwards compatibility.
6259
6260 @item @emph{Standard}:
6261 GNU extension.
6262
6263 @item @emph{Class}:
6264 Elemental function
6265
6266 @item @emph{Syntax}:
6267 @code{RESULT = LONG(A)}
6268
6269 @item @emph{Arguments}:
6270 @multitable @columnfractions .15 .70
6271 @item @var{A}    @tab Shall be of type @code{INTEGER(*)},
6272                       @code{REAL(*)}, or @code{COMPLEX(*)}.
6273 @end multitable
6274
6275 @item @emph{Return value}:
6276 The return value is a @code{INTEGER(4)} variable.
6277
6278 @item @emph{See also}:
6279 @ref{INT}, @ref{INT2}, @ref{INT8}
6280 @end table
6281
6282
6283
6284 @node LSHIFT
6285 @section @code{LSHIFT} --- Left shift bits
6286 @fnindex LSHIFT
6287 @cindex bits, shift left
6288
6289 @table @asis
6290 @item @emph{Description}:
6291 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
6292 bits shifted left by @var{SHIFT} places.  If the absolute value of
6293 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
6294 Bits shifted out from the left end are lost; zeros are shifted in from
6295 the opposite end.
6296
6297 This function has been superseded by the @code{ISHFT} intrinsic, which
6298 is standard in Fortran 95 and later.
6299
6300 @item @emph{Standard}:
6301 GNU extension
6302
6303 @item @emph{Class}:
6304 Elemental function
6305
6306 @item @emph{Syntax}:
6307 @code{RESULT = LSHIFT(I, SHIFT)}
6308
6309 @item @emph{Arguments}:
6310 @multitable @columnfractions .15 .70
6311 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6312 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6313 @end multitable
6314
6315 @item @emph{Return value}:
6316 The return value is of type @code{INTEGER(*)} and of the same kind as
6317 @var{I}.
6318
6319 @item @emph{See also}:
6320 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
6321
6322 @end table
6323
6324
6325
6326 @node LSTAT
6327 @section @code{LSTAT} --- Get file status
6328 @fnindex LSTAT
6329 @cindex file system, file status
6330
6331 @table @asis
6332 @item @emph{Description}:
6333 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
6334 then the link itself is statted, not the file that it refers to.
6335
6336 The elements in @code{BUFF} are the same as described by @ref{STAT}.
6337
6338 @item @emph{Standard}:
6339 GNU extension
6340
6341 @item @emph{Class}:
6342 Non-elemental subroutine
6343
6344 @item @emph{Syntax}:
6345 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
6346
6347 @item @emph{Arguments}:
6348 @multitable @columnfractions .15 .70
6349 @item @var{FILE}   @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
6350 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6351 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6352                         on success and a system specific error code otherwise.
6353 @end multitable
6354
6355 @item @emph{Example}:
6356 See @ref{STAT} for an example.
6357
6358 @item @emph{See also}:
6359 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
6360 @end table
6361
6362
6363
6364 @node LTIME
6365 @section @code{LTIME} --- Convert time to local time info
6366 @fnindex LTIME
6367 @cindex time, converstion to local time info
6368
6369 @table @asis
6370 @item @emph{Description}:
6371 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
6372 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
6373 to the local time zone using @code{localtime(3)}.
6374
6375 @item @emph{Standard}:
6376 GNU extension
6377
6378 @item @emph{Class}:
6379 Subroutine
6380
6381 @item @emph{Syntax}:
6382 @code{CALL LTIME(STIME, TARRAY)}
6383
6384 @item @emph{Arguments}:
6385 @multitable @columnfractions .15 .70
6386 @item @var{STIME}  @tab An @code{INTEGER(*)} scalar expression
6387                         corresponding to a system time, with
6388                         @code{INTENT(IN)}.
6389 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
6390                         with @code{INTENT(OUT)}.
6391 @end multitable
6392
6393 @item @emph{Return value}:
6394 The elements of @var{TARRAY} are assigned as follows:
6395 @enumerate
6396 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6397       seconds
6398 @item Minutes after the hour, range 0--59
6399 @item Hours past midnight, range 0--23
6400 @item Day of month, range 0--31
6401 @item Number of months since January, range 0--12
6402 @item Years since 1900
6403 @item Number of days since Sunday, range 0--6
6404 @item Days since January 1
6405 @item Daylight savings indicator: positive if daylight savings is in
6406       effect, zero if not, and negative if the information is not
6407       available.
6408 @end enumerate
6409
6410 @item @emph{See also}:
6411 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
6412
6413 @end table
6414
6415
6416
6417 @node MALLOC
6418 @section @code{MALLOC} --- Allocate dynamic memory
6419 @fnindex MALLOC
6420 @cindex pointer, cray
6421
6422 @table @asis
6423 @item @emph{Description}:
6424 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
6425 returns the address of the allocated memory. The @code{MALLOC} intrinsic
6426 is an extension intended to be used with Cray pointers, and is provided
6427 in GNU Fortran to allow the user to compile legacy code. For new code
6428 using Fortran 95 pointers, the memory allocation intrinsic is
6429 @code{ALLOCATE}.
6430
6431 @item @emph{Standard}:
6432 GNU extension
6433
6434 @item @emph{Class}:
6435 Non-elemental function
6436
6437 @item @emph{Syntax}:
6438 @code{PTR = MALLOC(SIZE)}
6439
6440 @item @emph{Arguments}:
6441 @multitable @columnfractions .15 .70
6442 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
6443 @end multitable
6444
6445 @item @emph{Return value}:
6446 The return value is of type @code{INTEGER(K)}, with @var{K} such that
6447 variables of type @code{INTEGER(K)} have the same size as
6448 C pointers (@code{sizeof(void *)}).
6449
6450 @item @emph{Example}:
6451 The following example demonstrates the use of @code{MALLOC} and
6452 @code{FREE} with Cray pointers. This example is intended to run on
6453 32-bit systems, where the default integer kind is suitable to store
6454 pointers; on 64-bit systems, ptr_x would need to be declared as
6455 @code{integer(kind=8)}.
6456
6457 @smallexample
6458 program test_malloc
6459   integer i
6460   integer ptr_x
6461   real*8 x(*), z
6462   pointer(ptr_x,x)
6463
6464   ptr_x = malloc(20*8)
6465   do i = 1, 20
6466     x(i) = sqrt(1.0d0 / i)
6467   end do
6468   z = 0
6469   do i = 1, 20
6470     z = z + x(i)
6471     print *, z
6472   end do
6473   call free(ptr_x)
6474 end program test_malloc
6475 @end smallexample
6476
6477 @item @emph{See also}:
6478 @ref{FREE}
6479 @end table
6480
6481
6482
6483 @node MATMUL
6484 @section @code{MATMUL} --- matrix multiplication
6485 @fnindex MATMUL
6486 @cindex matrix multiplication
6487 @cindex product, matrix
6488
6489 @table @asis
6490 @item @emph{Description}:
6491 Performs a matrix multiplication on numeric or logical arguments.
6492
6493 @item @emph{Standard}:
6494 F95 and later
6495
6496 @item @emph{Class}:
6497 Transformational function
6498
6499 @item @emph{Syntax}:
6500 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
6501
6502 @item @emph{Arguments}:
6503 @multitable @columnfractions .15 .70
6504 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
6505                           @code{REAL(*)}, @code{COMPLEX(*)}, or
6506                           @code{LOGICAL(*)} type, with a rank of
6507                           one or two.
6508 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
6509                           @code{REAL(*)}, or @code{COMPLEX(*)} type if
6510                           @var{MATRIX_A} is of a numeric type;
6511                           otherwise, an array of @code{LOGICAL(*)}
6512                           type. The rank shall be one or two, and the
6513                           first (or only) dimension of @var{MATRIX_B}
6514                           shall be equal to the last (or only)
6515                           dimension of @var{MATRIX_A}.
6516 @end multitable
6517
6518 @item @emph{Return value}:
6519 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
6520 kind of the result follow the usual type and kind promotion rules, as
6521 for the @code{*} or @code{.AND.} operators.
6522
6523 @item @emph{See also}:
6524 @end table
6525
6526
6527
6528 @node MAX
6529 @section @code{MAX} --- Maximum value of an argument list
6530 @fnindex MAX
6531 @fnindex MAX0
6532 @fnindex AMAX0
6533 @fnindex MAX1
6534 @fnindex AMAX1
6535 @fnindex DMAX1
6536 @cindex maximum value
6537
6538 @table @asis
6539 @item @emph{Description}:
6540 Returns the argument with the largest (most positive) value.
6541
6542 @item @emph{Standard}:
6543 F77 and later
6544
6545 @item @emph{Class}:
6546 Elemental function
6547
6548 @item @emph{Syntax}:
6549 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
6550
6551 @item @emph{Arguments}:
6552 @multitable @columnfractions .15 .70
6553 @item @var{A1}          @tab The type shall be @code{INTEGER(*)} or
6554                              @code{REAL(*)}.
6555 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
6556                              as @var{A1}.  (As a GNU extension,
6557                              arguments of different kinds are
6558                              permitted.)
6559 @end multitable
6560
6561 @item @emph{Return value}:
6562 The return value corresponds to the maximum value among the arguments,
6563 and has the same type and kind as the first argument.
6564
6565 @item @emph{Specific names}:
6566 @multitable @columnfractions .20 .20 .20 .25
6567 @item Name             @tab Argument            @tab Return type         @tab Standard
6568 @item @code{MAX0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab F77 and later
6569 @item @code{AMAX0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
6570 @item @code{MAX1(X)}   @tab @code{REAL(*) X}    @tab @code{INT(MAX(X))}  @tab F77 and later
6571 @item @code{AMAX1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab F77 and later
6572 @item @code{DMAX1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab F77 and later
6573 @end multitable
6574
6575 @item @emph{See also}:
6576 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
6577
6578 @end table
6579
6580
6581
6582 @node MAXEXPONENT
6583 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
6584 @fnindex MAXEXPONENT
6585 @cindex model representation, maximum exponent
6586
6587 @table @asis
6588 @item @emph{Description}:
6589 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
6590 type of @code{X}.
6591
6592 @item @emph{Standard}:
6593 F95 and later
6594
6595 @item @emph{Class}:
6596 Inquiry function
6597
6598 @item @emph{Syntax}:
6599 @code{RESULT = MAXEXPONENT(X)}
6600
6601 @item @emph{Arguments}:
6602 @multitable @columnfractions .15 .70
6603 @item @var{X} @tab Shall be of type @code{REAL}.
6604 @end multitable
6605
6606 @item @emph{Return value}:
6607 The return value is of type @code{INTEGER} and of the default integer
6608 kind.
6609
6610 @item @emph{Example}:
6611 @smallexample
6612 program exponents
6613   real(kind=4) :: x
6614   real(kind=8) :: y
6615
6616   print *, minexponent(x), maxexponent(x)
6617   print *, minexponent(y), maxexponent(y)
6618 end program exponents
6619 @end smallexample
6620 @end table
6621
6622
6623
6624 @node MAXLOC
6625 @section @code{MAXLOC} --- Location of the maximum value within an array
6626 @fnindex MAXLOC
6627 @cindex array, location of maximum element
6628
6629 @table @asis
6630 @item @emph{Description}:
6631 Determines the location of the element in the array with the maximum
6632 value, or, if the @var{DIM} argument is supplied, determines the
6633 locations of the maximum element along each row of the array in the
6634 @var{DIM} direction.  If @var{MASK} is present, only the elements for
6635 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
6636 element in the array has the maximum value, the location returned is
6637 that of the first such element in array element order.  If the array has
6638 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
6639 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
6640 and all of the elements of @var{MASK} along a given row are zero, the
6641 result value for that row is zero.
6642
6643 @item @emph{Standard}:
6644 F95 and later
6645
6646 @item @emph{Class}:
6647 Transformational function
6648
6649 @item @emph{Syntax}:
6650 @multitable @columnfractions .80
6651 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
6652 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
6653 @end multitable
6654
6655 @item @emph{Arguments}:
6656 @multitable @columnfractions .15 .70
6657 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6658                        @code{REAL(*)}, or @code{CHARACTER(*)}.
6659 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
6660                        @code{INTEGER(*)}, with a value between one
6661                        and the rank of @var{ARRAY}, inclusive.  It
6662                        may not be an optional dummy argument.
6663 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
6664                        and conformable with @var{ARRAY}.
6665 @end multitable
6666
6667 @item @emph{Return value}:
6668 If @var{DIM} is absent, the result is a rank-one array with a length
6669 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
6670 is an array with a rank one less than the rank of @var{ARRAY}, and a
6671 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6672 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
6673 of one, the result is a scalar.  In all cases, the result is of default
6674 @code{INTEGER} type.
6675
6676 @item @emph{See also}:
6677 @ref{MAX}, @ref{MAXVAL}
6678
6679 @end table
6680
6681
6682
6683 @node MAXVAL
6684 @section @code{MAXVAL} --- Maximum value of an array
6685 @fnindex MAXVAL
6686 @cindex array, maximum value
6687 @cindex maximum value
6688
6689 @table @asis
6690 @item @emph{Description}:
6691 Determines the maximum value of the elements in an array value, or, if
6692 the @var{DIM} argument is supplied, determines the maximum value along
6693 each row of the array in the @var{DIM} direction.  If @var{MASK} is
6694 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6695 considered.  If the array has zero size, or all of the elements of
6696 @var{MASK} are @code{.FALSE.}, then the result is the most negative
6697 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
6698 a string of nulls if @var{ARRAY} is of character type.
6699
6700 @item @emph{Standard}:
6701 F95 and later
6702
6703 @item @emph{Class}:
6704 Transformational function
6705
6706 @item @emph{Syntax}:
6707 @multitable @columnfractions .80
6708 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
6709 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
6710 @end multitable
6711
6712 @item @emph{Arguments}:
6713 @multitable @columnfractions .15 .70
6714 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6715                        @code{REAL(*)}, or @code{CHARACTER(*)}.
6716 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
6717                        @code{INTEGER(*)}, with a value between one
6718                        and the rank of @var{ARRAY}, inclusive.  It
6719                        may not be an optional dummy argument.
6720 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
6721                        and conformable with @var{ARRAY}.
6722 @end multitable
6723
6724 @item @emph{Return value}:
6725 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
6726 is a scalar.  If @var{DIM} is present, the result is an array with a
6727 rank one less than the rank of @var{ARRAY}, and a size corresponding to
6728 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
6729 cases, the result is of the same type and kind as @var{ARRAY}.
6730
6731 @item @emph{See also}:
6732 @ref{MAX}, @ref{MAXLOC}
6733 @end table
6734
6735
6736
6737 @node MCLOCK
6738 @section @code{MCLOCK} --- Time function
6739 @fnindex MCLOCK
6740 @cindex time, clock ticks
6741 @cindex clock ticks
6742
6743 @table @asis
6744 @item @emph{Description}:
6745 Returns the number of clock ticks since the start of the process, based
6746 on the UNIX function @code{clock(3)}.
6747
6748 This intrinsic is not fully portable, such as to systems with 32-bit
6749 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
6750 the values returned by this intrinsic might be, or become, negative, or
6751 numerically less than previous values, during a single run of the
6752 compiled program.
6753
6754 @item @emph{Standard}:
6755 GNU extension
6756
6757 @item @emph{Class}:
6758 Non-elemental function
6759
6760 @item @emph{Syntax}:
6761 @code{RESULT = MCLOCK()}
6762
6763 @item @emph{Return value}:
6764 The return value is a scalar of type @code{INTEGER(4)}, equal to the
6765 number of clock ticks since the start of the process, or @code{-1} if
6766 the system does not support @code{clock(3)}.
6767
6768 @item @emph{See also}:
6769 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
6770
6771 @end table
6772
6773
6774
6775 @node MCLOCK8
6776 @section @code{MCLOCK8} --- Time function (64-bit)
6777 @fnindex MCLOCK8
6778 @cindex time, clock ticks
6779 @cindex clock ticks
6780
6781 @table @asis
6782 @item @emph{Description}:
6783 Returns the number of clock ticks since the start of the process, based
6784 on the UNIX function @code{clock(3)}.
6785
6786 @emph{Warning:} this intrinsic does not increase the range of the timing
6787 values over that returned by @code{clock(3)}. On a system with a 32-bit
6788 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
6789 it is converted to a 64-bit @code{INTEGER(8)} value. That means
6790 overflows of the 32-bit value can still occur. Therefore, the values
6791 returned by this intrinsic might be or become negative or numerically
6792 less than previous values during a single run of the compiled program.
6793
6794 @item @emph{Standard}:
6795 GNU extension
6796
6797 @item @emph{Class}:
6798 Non-elemental function
6799
6800 @item @emph{Syntax}:
6801 @code{RESULT = MCLOCK8()}
6802
6803 @item @emph{Return value}:
6804 The return value is a scalar of type @code{INTEGER(8)}, equal to the
6805 number of clock ticks since the start of the process, or @code{-1} if
6806 the system does not support @code{clock(3)}.
6807
6808 @item @emph{See also}:
6809 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
6810
6811 @end table
6812
6813
6814
6815 @node MERGE
6816 @section @code{MERGE} --- Merge variables
6817 @fnindex MERGE
6818 @cindex array, merge arrays
6819 @cindex array, combine arrays
6820
6821 @table @asis
6822 @item @emph{Description}:
6823 Select values from two arrays according to a logical mask.  The result
6824 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
6825 @var{FSOURCE} if it is @code{.FALSE.}.
6826
6827 @item @emph{Standard}:
6828 F95 and later
6829
6830 @item @emph{Class}:
6831 Elemental function
6832
6833 @item @emph{Syntax}:
6834 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
6835
6836 @item @emph{Arguments}:
6837 @multitable @columnfractions .15 .70
6838 @item @var{TSOURCE} @tab May be of any type.
6839 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
6840                          as @var{TSOURCE}.
6841 @item @var{MASK}    @tab Shall be of type @code{LOGICAL(*)}.
6842 @end multitable
6843
6844 @item @emph{Return value}:
6845 The result is of the same type and type parameters as @var{TSOURCE}.
6846
6847 @end table
6848
6849
6850
6851 @node MIN
6852 @section @code{MIN} --- Minimum value of an argument list
6853 @fnindex MIN
6854 @fnindex MIN0
6855 @fnindex AMIN0
6856 @fnindex MIN1
6857 @fnindex AMIN1
6858 @fnindex DMIN1
6859 @cindex minimum value
6860
6861 @table @asis
6862 @item @emph{Description}:
6863 Returns the argument with the smallest (most negative) value.
6864
6865 @item @emph{Standard}:
6866 F77 and later
6867
6868 @item @emph{Class}:
6869 Elemental function
6870
6871 @item @emph{Syntax}:
6872 @code{RESULT = MIN(A1, A2 [, A3, ...])}
6873
6874 @item @emph{Arguments}:
6875 @multitable @columnfractions .15 .70
6876 @item @var{A1}          @tab The type shall be @code{INTEGER(*)} or
6877                              @code{REAL(*)}.
6878 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
6879                              as @var{A1}.  (As a GNU extension,
6880                              arguments of different kinds are
6881                              permitted.)
6882 @end multitable
6883
6884 @item @emph{Return value}:
6885 The return value corresponds to the maximum value among the arguments,
6886 and has the same type and kind as the first argument.
6887
6888 @item @emph{Specific names}:
6889 @multitable @columnfractions .20 .20 .20 .25
6890 @item Name             @tab Argument            @tab Return type         @tab Standard
6891 @item @code{MIN0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab F77 and later
6892 @item @code{AMIN0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
6893 @item @code{MIN1(X)}   @tab @code{REAL(*) X}    @tab @code{INT(MIN(X))}  @tab F77 and later
6894 @item @code{AMIN1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab F77 and later
6895 @item @code{DMIN1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab F77 and later
6896 @end multitable
6897
6898 @item @emph{See also}:
6899 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
6900 @end table
6901
6902
6903
6904 @node MINEXPONENT
6905 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
6906 @fnindex MINEXPONENT
6907 @cindex model representation, minimum exponent
6908
6909 @table @asis
6910 @item @emph{Description}:
6911 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
6912 type of @code{X}.
6913
6914 @item @emph{Standard}:
6915 F95 and later
6916
6917 @item @emph{Class}:
6918 Inquiry function
6919
6920 @item @emph{Syntax}:
6921 @code{RESULT = MINEXPONENT(X)}
6922
6923 @item @emph{Arguments}:
6924 @multitable @columnfractions .15 .70
6925 @item @var{X} @tab Shall be of type @code{REAL}.
6926 @end multitable
6927
6928 @item @emph{Return value}:
6929 The return value is of type @code{INTEGER} and of the default integer
6930 kind.
6931
6932 @item @emph{Example}:
6933 See @code{MAXEXPONENT} for an example.
6934 @end table
6935
6936
6937
6938 @node MINLOC
6939 @section @code{MINLOC} --- Location of the minimum value within an array
6940 @fnindex MINLOC
6941 @cindex array, location of minimum element
6942
6943 @table @asis
6944 @item @emph{Description}:
6945 Determines the location of the element in the array with the minimum
6946 value, or, if the @var{DIM} argument is supplied, determines the
6947 locations of the minimum element along each row of the array in the
6948 @var{DIM} direction.  If @var{MASK} is present, only the elements for
6949 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
6950 element in the array has the minimum value, the location returned is
6951 that of the first such element in array element order.  If the array has
6952 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
6953 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
6954 and all of the elements of @var{MASK} along a given row are zero, the
6955 result value for that row is zero.
6956
6957 @item @emph{Standard}:
6958 F95 and later
6959
6960 @item @emph{Class}:
6961 Transformational function
6962
6963 @item @emph{Syntax}:
6964 @multitable @columnfractions .80
6965 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
6966 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
6967 @end multitable
6968
6969 @item @emph{Arguments}:
6970 @multitable @columnfractions .15 .70
6971 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6972                        @code{REAL(*)}, or @code{CHARACTER(*)}.
6973 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
6974                        @code{INTEGER(*)}, with a value between one
6975                        and the rank of @var{ARRAY}, inclusive.  It
6976                        may not be an optional dummy argument.
6977 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
6978                        and conformable with @var{ARRAY}.
6979 @end multitable
6980
6981 @item @emph{Return value}:
6982 If @var{DIM} is absent, the result is a rank-one array with a length
6983 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
6984 is an array with a rank one less than the rank of @var{ARRAY}, and a
6985 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6986 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
6987 of one, the result is a scalar.  In all cases, the result is of default
6988 @code{INTEGER} type.
6989
6990 @item @emph{See also}:
6991 @ref{MIN}, @ref{MINVAL}
6992
6993 @end table
6994
6995
6996
6997 @node MINVAL
6998 @section @code{MINVAL} --- Minimum value of an array
6999 @fnindex MINVAL
7000 @cindex array, minmum value
7001 @cindex minimum value
7002
7003 @table @asis
7004 @item @emph{Description}:
7005 Determines the minimum value of the elements in an array value, or, if
7006 the @var{DIM} argument is supplied, determines the minimum value along
7007 each row of the array in the @var{DIM} direction.  If @var{MASK} is
7008 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7009 considered.  If the array has zero size, or all of the elements of
7010 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7011 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7012 @var{ARRAY} is of character type.
7013
7014 @item @emph{Standard}:
7015 F95 and later
7016
7017 @item @emph{Class}:
7018 Transformational function
7019
7020 @item @emph{Syntax}:
7021 @multitable @columnfractions .80
7022 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7023 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7024 @end multitable
7025
7026 @item @emph{Arguments}:
7027 @multitable @columnfractions .15 .70
7028 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7029                        @code{REAL(*)}, or @code{CHARACTER(*)}.
7030 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7031                        @code{INTEGER(*)}, with a value between one
7032                        and the rank of @var{ARRAY}, inclusive.  It
7033                        may not be an optional dummy argument.
7034 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
7035                        and conformable with @var{ARRAY}.
7036 @end multitable
7037
7038 @item @emph{Return value}:
7039 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7040 is a scalar.  If @var{DIM} is present, the result is an array with a
7041 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7042 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
7043 cases, the result is of the same type and kind as @var{ARRAY}.
7044
7045 @item @emph{See also}:
7046 @ref{MIN}, @ref{MINLOC}
7047
7048 @end table
7049
7050
7051
7052 @node MOD
7053 @section @code{MOD} --- Remainder function
7054 @fnindex MOD
7055 @fnindex AMOD
7056 @fnindex DMOD
7057 @cindex remainder
7058 @cindex division, remainder
7059
7060 @table @asis
7061 @item @emph{Description}:
7062 @code{MOD(A,P)} computes the remainder of the division of A by P. It is
7063 calculated as @code{A - (INT(A/P) * P)}.
7064
7065 @item @emph{Standard}:
7066 F77 and later
7067
7068 @item @emph{Class}:
7069 Elemental function
7070
7071 @item @emph{Syntax}:
7072 @code{RESULT = MOD(A, P)}
7073
7074 @item @emph{Arguments}:
7075 @multitable @columnfractions .15 .70
7076 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7077 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7078 equal to zero
7079 @end multitable
7080
7081 @item @emph{Return value}:
7082 The kind of the return value is the result of cross-promoting
7083 the kinds of the arguments.
7084
7085 @item @emph{Example}:
7086 @smallexample
7087 program test_mod
7088   print *, mod(17,3)
7089   print *, mod(17.5,5.5)
7090   print *, mod(17.5d0,5.5)
7091   print *, mod(17.5,5.5d0)
7092
7093   print *, mod(-17,3)
7094   print *, mod(-17.5,5.5)
7095   print *, mod(-17.5d0,5.5)
7096   print *, mod(-17.5,5.5d0)
7097
7098   print *, mod(17,-3)
7099   print *, mod(17.5,-5.5)
7100   print *, mod(17.5d0,-5.5)
7101   print *, mod(17.5,-5.5d0)
7102 end program test_mod
7103 @end smallexample
7104
7105 @item @emph{Specific names}:
7106 @multitable @columnfractions .20 .20 .20 .25
7107 @item Name             @tab Arguments      @tab Return type    @tab Standard
7108 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
7109 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
7110 @end multitable
7111 @end table
7112
7113
7114
7115 @node MODULO
7116 @section @code{MODULO} --- Modulo function
7117 @fnindex MODULO
7118 @cindex modulo
7119 @cindex division, modulo
7120
7121 @table @asis
7122 @item @emph{Description}:
7123 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7124
7125 @item @emph{Standard}:
7126 F95 and later
7127
7128 @item @emph{Class}:
7129 Elemental function
7130
7131 @item @emph{Syntax}:
7132 @code{RESULT = MODULO(A, P)}
7133
7134 @item @emph{Arguments}:
7135 @multitable @columnfractions .15 .70
7136 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7137 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7138 @end multitable
7139
7140 @item @emph{Return value}:
7141 The type and kind of the result are those of the arguments.
7142 @table @asis
7143 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7144 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7145 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7146 (exclusive).
7147 @item If @var{A} and @var{P} are of type @code{REAL}:
7148 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7149 @end table
7150 In all cases, if @var{P} is zero the result is processor-dependent.
7151
7152 @item @emph{Example}:
7153 @smallexample
7154 program test_modulo
7155   print *, modulo(17,3)
7156   print *, modulo(17.5,5.5)
7157
7158   print *, modulo(-17,3)
7159   print *, modulo(-17.5,5.5)
7160
7161   print *, modulo(17,-3)
7162   print *, modulo(17.5,-5.5)
7163 end program
7164 @end smallexample
7165
7166 @end table
7167
7168
7169
7170 @node MOVE_ALLOC
7171 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7172 @fnindex MOVE_ALLOC
7173 @cindex moving allocation
7174 @cindex allocation, moving
7175
7176 @table @asis
7177 @item @emph{Description}:
7178 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7179 @var{DEST}.  @var{SRC} will become deallocated in the process.
7180
7181 @item @emph{Standard}:
7182 F2003 and later
7183
7184 @item @emph{Class}:
7185 Subroutine
7186
7187 @item @emph{Syntax}:
7188 @code{CALL MOVE_ALLOC(SRC, DEST)}
7189
7190 @item @emph{Arguments}:
7191 @multitable @columnfractions .15 .70
7192 @item @var{SRC}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7193                       of any type and kind.
7194 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7195                       of the same type, kind and rank as @var{SRC}
7196 @end multitable
7197
7198 @item @emph{Return value}:
7199 None
7200
7201 @item @emph{Example}:
7202 @smallexample
7203 program test_move_alloc
7204     integer, allocatable :: a(:), b(:)
7205
7206     allocate(a(3))
7207     a = [ 1, 2, 3 ]
7208     call move_alloc(a, b)
7209     print *, allocated(a), allocated(b)
7210     print *, b
7211 end program test_move_alloc
7212 @end smallexample
7213 @end table
7214
7215
7216
7217 @node MVBITS
7218 @section @code{MVBITS} --- Move bits from one integer to another
7219 @fnindex MVBITS
7220 @cindex bits, move
7221
7222 @table @asis
7223 @item @emph{Description}:
7224 Moves @var{LEN} bits from positions @var{FROMPOS} through
7225 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7226 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7227 affected by the movement of bits is unchanged. The values of
7228 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7229 @code{BIT_SIZE(FROM)}.
7230
7231 @item @emph{Standard}:
7232 F95 and later
7233
7234 @item @emph{Class}:
7235 Elemental subroutine
7236
7237 @item @emph{Syntax}:
7238 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7239
7240 @item @emph{Arguments}:
7241 @multitable @columnfractions .15 .70
7242 @item @var{FROM}    @tab The type shall be @code{INTEGER(*)}.
7243 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
7244 @item @var{LEN}     @tab The type shall be @code{INTEGER(*)}.
7245 @item @var{TO}      @tab The type shall be @code{INTEGER(*)}, of the
7246                          same kind as @var{FROM}.
7247 @item @var{TOPOS}   @tab The type shall be @code{INTEGER(*)}.
7248 @end multitable
7249
7250 @item @emph{See also}:
7251 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7252 @end table
7253
7254
7255
7256 @node NEAREST
7257 @section @code{NEAREST} --- Nearest representable number
7258 @fnindex NEAREST
7259 @cindex real number, nearest different
7260 @cindex floating point, nearest different
7261
7262 @table @asis
7263 @item @emph{Description}:
7264 @code{NEAREST(X, S)} returns the processor-representable number nearest
7265 to @code{X} in the direction indicated by the sign of @code{S}.
7266
7267 @item @emph{Standard}:
7268 F95 and later
7269
7270 @item @emph{Class}:
7271 Elemental function
7272
7273 @item @emph{Syntax}:
7274 @code{RESULT = NEAREST(X, S)}
7275
7276 @item @emph{Arguments}:
7277 @multitable @columnfractions .15 .70
7278 @item @var{X} @tab Shall be of type @code{REAL}.
7279 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
7280 not equal to zero.
7281 @end multitable
7282
7283 @item @emph{Return value}:
7284 The return value is of the same type as @code{X}. If @code{S} is
7285 positive, @code{NEAREST} returns the processor-representable number
7286 greater than @code{X} and nearest to it. If @code{S} is negative,
7287 @code{NEAREST} returns the processor-representable number smaller than
7288 @code{X} and nearest to it.
7289
7290 @item @emph{Example}:
7291 @smallexample
7292 program test_nearest
7293   real :: x, y
7294   x = nearest(42.0, 1.0)
7295   y = nearest(42.0, -1.0)
7296   write (*,"(3(G20.15))") x, y, x - y
7297 end program test_nearest
7298 @end smallexample
7299 @end table
7300
7301
7302
7303 @node NEW_LINE
7304 @section @code{NEW_LINE} --- New line character
7305 @fnindex NEW_LINE
7306 @cindex newline
7307 @cindex output, newline
7308
7309 @table @asis
7310 @item @emph{Description}:
7311 @code{NEW_LINE(C)} returns the new-line character.
7312
7313 @item @emph{Standard}:
7314 F2003 and later
7315
7316 @item @emph{Class}:
7317 Inquiry function
7318
7319 @item @emph{Syntax}:
7320 @code{RESULT = NEW_LINE(C)}
7321
7322 @item @emph{Arguments}:
7323 @multitable @columnfractions .15 .70
7324 @item @var{C}    @tab The argument shall be a scalar or array of the
7325                       type @code{CHARACTER}.
7326 @end multitable
7327
7328 @item @emph{Return value}:
7329 Returns a @var{CHARACTER} scalar of length one with the new-line character of
7330 the same kind as parameter @var{C}.
7331
7332 @item @emph{Example}:
7333 @smallexample
7334 program newline
7335   implicit none
7336   write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
7337 end program newline
7338 @end smallexample
7339 @end table
7340
7341
7342
7343 @node NINT
7344 @section @code{NINT} --- Nearest whole number
7345 @fnindex NINT
7346 @fnindex IDNINT
7347 @cindex rounding, nearest whole number
7348
7349 @table @asis
7350 @item @emph{Description}:
7351 @code{NINT(X)} rounds its argument to the nearest whole number.
7352
7353 @item @emph{Standard}:
7354 F77 and later
7355
7356 @item @emph{Class}:
7357 Elemental function
7358
7359 @item @emph{Syntax}:
7360 @code{RESULT = NINT(X)}
7361
7362 @item @emph{Arguments}:
7363 @multitable @columnfractions .15 .70
7364 @item @var{X}    @tab The type of the argument shall be @code{REAL}.
7365 @end multitable
7366
7367 @item @emph{Return value}:
7368 Returns @var{A} with the fractional portion of its magnitude eliminated by
7369 rounding to the nearest whole number and with its sign preserved,
7370 converted to an @code{INTEGER} of the default kind.
7371
7372 @item @emph{Example}:
7373 @smallexample
7374 program test_nint
7375   real(4) x4
7376   real(8) x8
7377   x4 = 1.234E0_4
7378   x8 = 4.321_8
7379   print *, nint(x4), idnint(x8)
7380 end program test_nint
7381 @end smallexample
7382
7383 @item @emph{Specific names}:
7384 @multitable @columnfractions .25 .25 .25
7385 @item Name             @tab Argument         @tab Standard
7386 @item @code{IDNINT(X)} @tab @code{REAL(8)}   @tab F95 and later
7387 @end multitable
7388
7389 @item @emph{See also}:
7390 @ref{CEILING}, @ref{FLOOR}
7391
7392 @end table
7393
7394
7395
7396 @node NOT
7397 @section @code{NOT} --- Logical negation
7398 @fnindex NOT
7399 @cindex bits, negate
7400 @cindex bitwise logical not
7401 @cindex logical not, bitwise
7402
7403 @table @asis
7404 @item @emph{Description}:
7405 @code{NOT} returns the bitwise boolean inverse of @var{I}.
7406
7407 @item @emph{Standard}:
7408 F95 and later
7409
7410 @item @emph{Class}:
7411 Elemental function
7412
7413 @item @emph{Syntax}:
7414 @code{RESULT = NOT(I)}
7415
7416 @item @emph{Arguments}:
7417 @multitable @columnfractions .15 .70
7418 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7419 @end multitable
7420
7421 @item @emph{Return value}:
7422 The return type is @code{INTEGER(*)}, of the same kind as the
7423 argument.
7424
7425 @item @emph{See also}:
7426 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
7427
7428 @end table
7429
7430
7431
7432 @node NULL
7433 @section @code{NULL} --- Function that returns an disassociated pointer
7434 @fnindex NULL
7435 @cindex pointer, status
7436 @cindex pointer, disassociated
7437
7438 @table @asis
7439 @item @emph{Description}:
7440 Returns a disassociated pointer.
7441
7442 If @var{MOLD} is present, a dissassociated pointer of the same type is
7443 returned, otherwise the type is determined by context.
7444
7445 In Fortran 95, @var{MOLD} is optional. Please note that F2003 includes
7446 cases where it is required.
7447
7448 @item @emph{Standard}:
7449 F95 and later
7450
7451 @item @emph{Class}:
7452 Transformational function
7453
7454 @item @emph{Syntax}:
7455 @code{PTR => NULL([MOLD])}
7456
7457 @item @emph{Arguments}:
7458 @multitable @columnfractions .15 .70
7459 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
7460 status and of any type.
7461 @end multitable
7462
7463 @item @emph{Return value}:
7464 A disassociated pointer.
7465
7466 @item @emph{Example}:
7467 @smallexample
7468 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
7469 @end smallexample
7470
7471 @item @emph{See also}:
7472 @ref{ASSOCIATED}
7473 @end table
7474
7475
7476
7477 @node OR
7478 @section @code{OR} --- Bitwise logical OR
7479 @fnindex OR
7480 @cindex bitwise logical or
7481 @cindex logical or, bitwise
7482
7483 @table @asis
7484 @item @emph{Description}:
7485 Bitwise logical @code{OR}.
7486
7487 This intrinsic routine is provided for backwards compatibility with
7488 GNU Fortran 77.  For integer arguments, programmers should consider
7489 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
7490
7491 @item @emph{Standard}:
7492 GNU extension
7493
7494 @item @emph{Class}:
7495 Non-elemental function
7496
7497 @item @emph{Syntax}:
7498 @code{RESULT = OR(X, Y)}
7499
7500 @item @emph{Arguments}:
7501 @multitable @columnfractions .15 .70
7502 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7503 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7504 @end multitable
7505
7506 @item @emph{Return value}:
7507 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
7508 after cross-promotion of the arguments.
7509
7510 @item @emph{Example}:
7511 @smallexample
7512 PROGRAM test_or
7513   LOGICAL :: T = .TRUE., F = .FALSE.
7514   INTEGER :: a, b
7515   DATA a / Z'F' /, b / Z'3' /
7516
7517   WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
7518   WRITE (*,*) OR(a, b)
7519 END PROGRAM
7520 @end smallexample
7521
7522 @item @emph{See also}:
7523 F95 elemental function: @ref{IOR}
7524 @end table
7525
7526
7527
7528 @node PACK
7529 @section @code{PACK} --- Pack an array into an array of rank one
7530 @fnindex PACK
7531 @cindex array, packing
7532 @cindex array, reduce dimension
7533 @cindex array, gather elements
7534
7535 @table @asis
7536 @item @emph{Description}:
7537 Stores the elements of @var{ARRAY} in an array of rank one.
7538
7539 The beginning of the resulting array is made up of elements whose @var{MASK}
7540 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
7541 @var{VECTOR}.
7542
7543 @item @emph{Standard}:
7544 F95 and later
7545
7546 @item @emph{Class}:
7547 Transformational function
7548
7549 @item @emph{Syntax}:
7550 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
7551
7552 @item @emph{Arguments}:
7553 @multitable @columnfractions .15 .70
7554 @item @var{ARRAY}  @tab Shall be an array of any type.
7555 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
7556 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
7557 scalar.
7558 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
7559 as @var{ARRAY} and of rank one. If present, the number of elements in
7560 @var{VECTOR} shall be equal to or greater than the number of true elements
7561 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
7562 @var{VECTOR} shall be equal to or greater than the number of elements in
7563 @var{ARRAY}.
7564 @end multitable
7565
7566 @item @emph{Return value}:
7567 The result is an array of rank one and the same type as that of @var{ARRAY}.
7568 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
7569 number of @code{TRUE} values in @var{MASK} otherwise.
7570
7571 @item @emph{Example}:
7572 Gathering non-zero elements from an array:
7573 @smallexample
7574 PROGRAM test_pack_1
7575   INTEGER :: m(6)
7576   m = (/ 1, 0, 0, 0, 5, 0 /)
7577   WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
7578 END PROGRAM
7579 @end smallexample
7580
7581 Gathering non-zero elements from an array and appending elements from @var{VECTOR}:
7582 @smallexample
7583 PROGRAM test_pack_2
7584   INTEGER :: m(4)
7585   m = (/ 1, 0, 0, 2 /)
7586   WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
7587 END PROGRAM
7588 @end smallexample
7589
7590 @item @emph{See also}:
7591 @ref{UNPACK}
7592 @end table
7593
7594
7595
7596 @node PERROR
7597 @section @code{PERROR} --- Print system error message
7598 @fnindex PERROR
7599 @cindex system, error handling
7600
7601 @table @asis
7602 @item @emph{Description}:
7603 Prints (on the C @code{stderr} stream) a newline-terminated error
7604 message corresponding to the last system error. This is prefixed by
7605 @var{STRING}, a colon and a space. See @code{perror(3)}.
7606
7607 @item @emph{Standard}:
7608 GNU extension
7609
7610 @item @emph{Class}:
7611 Subroutine
7612
7613 @item @emph{Syntax}:
7614 @code{CALL PERROR(STRING)}
7615
7616 @item @emph{Arguments}:
7617 @multitable @columnfractions .15 .70
7618 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
7619 @end multitable
7620
7621 @item @emph{See also}:
7622 @ref{IERRNO}
7623 @end table
7624
7625
7626
7627 @node PRECISION
7628 @section @code{PRECISION} --- Decimal precision of a real kind
7629 @fnindex PRECISION
7630 @cindex model representation, precision
7631
7632 @table @asis
7633 @item @emph{Description}:
7634 @code{PRECISION(X)} returns the decimal precision in the model of the
7635 type of @code{X}.
7636
7637 @item @emph{Standard}:
7638 F95 and later
7639
7640 @item @emph{Class}:
7641 Inquiry function
7642
7643 @item @emph{Syntax}:
7644 @code{RESULT = PRECISION(X)}
7645
7646 @item @emph{Arguments}:
7647 @multitable @columnfractions .15 .70
7648 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
7649 @end multitable
7650
7651 @item @emph{Return value}:
7652 The return value is of type @code{INTEGER} and of the default integer
7653 kind.
7654
7655 @item @emph{Example}:
7656 @smallexample
7657 program prec_and_range
7658   real(kind=4) :: x(2)
7659   complex(kind=8) :: y
7660
7661   print *, precision(x), range(x)
7662   print *, precision(y), range(y)
7663 end program prec_and_range
7664 @end smallexample
7665 @end table
7666
7667
7668
7669 @node PRESENT
7670 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
7671 @fnindex PRESENT
7672
7673 @table @asis
7674 @item @emph{Description}:
7675 Determines whether an optional dummy argument is present.
7676
7677 @item @emph{Standard}:
7678 F95 and later
7679
7680 @item @emph{Class}:
7681 Inquiry function
7682
7683 @item @emph{Syntax}:
7684 @code{RESULT = PRESENT(A)}
7685
7686 @item @emph{Arguments}:
7687 @multitable @columnfractions .15 .70
7688 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
7689 value, or a dummy procedure. It shall be the name of an optional dummy argument
7690 accessible within the current subroutine or function.
7691 @end multitable
7692
7693 @item @emph{Return value}:
7694 Returns either @code{TRUE} if the optional argument @var{A} is present, or
7695 @code{FALSE} otherwise.
7696
7697 @item @emph{Example}:
7698 @smallexample
7699 PROGRAM test_present
7700   WRITE(*,*) f(), f(42)      ! "F T"
7701 CONTAINS
7702   LOGICAL FUNCTION f(x)
7703     INTEGER, INTENT(IN), OPTIONAL :: x
7704     f = PRESENT(x)
7705   END FUNCTION
7706 END PROGRAM
7707 @end smallexample
7708 @end table
7709
7710
7711
7712 @node PRODUCT
7713 @section @code{PRODUCT} --- Product of array elements
7714 @fnindex PRODUCT
7715 @cindex array, product
7716 @cindex array, multiply elements
7717 @cindex array, conditionally multiply elements
7718 @cindex multiply array elements
7719
7720 @table @asis
7721 @item @emph{Description}:
7722 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
7723 the corresponding element in @var{MASK} is @code{TRUE}.
7724
7725 @item @emph{Standard}:
7726 F95 and later
7727
7728 @item @emph{Class}:
7729 Transformational function
7730
7731 @item @emph{Syntax}:
7732 @code{RESULT = PRODUCT(ARRAY[, MASK])}
7733 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
7734
7735 @item @emph{Arguments}:
7736 @multitable @columnfractions .15 .70
7737 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7738 @code{REAL(*)} or @code{COMPLEX(*)}.
7739 @item @var{DIM}   @tab (Optional) shall be a scalar of type
7740 @code{INTEGER} with a value in the range from 1 to n, where n
7741 equals the rank of @var{ARRAY}.
7742 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
7743 and either be a scalar or an array of the same shape as @var{ARRAY}.
7744 @end multitable
7745
7746 @item @emph{Return value}:
7747 The result is of the same type as @var{ARRAY}.
7748
7749 If @var{DIM} is absent, a scalar with the product of all elements in
7750 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7751 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7752 dimension @var{DIM} dropped is returned.
7753
7754
7755 @item @emph{Example}:
7756 @smallexample
7757 PROGRAM test_product
7758   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
7759   print *, PRODUCT(x)                    ! all elements, product = 120
7760   print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
7761 END PROGRAM
7762 @end smallexample
7763
7764 @item @emph{See also}:
7765 @ref{SUM}
7766 @end table
7767
7768
7769
7770 @node RADIX
7771 @section @code{RADIX} --- Base of a model number
7772 @fnindex RADIX
7773 @cindex model representation, base
7774 @cindex model representation, radix
7775
7776 @table @asis
7777 @item @emph{Description}:
7778 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
7779
7780 @item @emph{Standard}:
7781 F95 and later
7782
7783 @item @emph{Class}:
7784 Inquiry function
7785
7786 @item @emph{Syntax}:
7787 @code{RESULT = RADIX(X)}
7788
7789 @item @emph{Arguments}:
7790 @multitable @columnfractions .15 .70
7791 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
7792 @end multitable
7793
7794 @item @emph{Return value}:
7795 The return value is a scalar of type @code{INTEGER} and of the default
7796 integer kind.
7797
7798 @item @emph{Example}:
7799 @smallexample
7800 program test_radix
7801   print *, "The radix for the default integer kind is", radix(0)
7802   print *, "The radix for the default real kind is", radix(0.0)
7803 end program test_radix
7804 @end smallexample
7805
7806 @end table
7807
7808
7809
7810 @node RAN
7811 @section @code{RAN} --- Real pseudo-random number
7812 @fnindex RAN
7813 @cindex random number generation
7814
7815 @table @asis
7816 @item @emph{Description}:
7817 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
7818 provided as an alias for @code{RAND}.  See @ref{RAND} for complete
7819 documentation.
7820
7821 @item @emph{Standard}:
7822 GNU extension
7823
7824 @item @emph{Class}:
7825 Non-elemental function
7826
7827 @item @emph{See also}:
7828 @ref{RAND}, @ref{RANDOM_NUMBER}
7829 @end table
7830
7831
7832
7833 @node RAND
7834 @section @code{RAND} --- Real pseudo-random number
7835 @fnindex RAND
7836 @cindex random number generation
7837
7838 @table @asis
7839 @item @emph{Description}:
7840 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
7841 distribution between 0 and 1. If @var{FLAG} is 0, the next number
7842 in the current sequence is returned; if @var{FLAG} is 1, the generator
7843 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
7844 it is used as a new seed with @code{SRAND}.
7845
7846 @item @emph{Standard}:
7847 GNU extension
7848
7849 @item @emph{Class}:
7850 Non-elemental function
7851
7852 @item @emph{Syntax}:
7853 @code{RESULT = RAND(FLAG)}
7854
7855 @item @emph{Arguments}:
7856 @multitable @columnfractions .15 .70
7857 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
7858 @end multitable
7859
7860 @item @emph{Return value}:
7861 The return value is of @code{REAL} type and the default kind.
7862
7863 @item @emph{Example}:
7864 @smallexample
7865 program test_rand
7866   integer,parameter :: seed = 86456
7867
7868   call srand(seed)
7869   print *, rand(), rand(), rand(), rand()
7870   print *, rand(seed), rand(), rand(), rand()
7871 end program test_rand
7872 @end smallexample
7873
7874 @item @emph{See also}:
7875 @ref{SRAND}, @ref{RANDOM_NUMBER}
7876
7877 @end table
7878
7879
7880
7881 @node RANDOM_NUMBER
7882 @section @code{RANDOM_NUMBER} --- Pseudo-random number
7883 @fnindex RANDOM_NUMBER
7884 @cindex random number generation
7885
7886 @table @asis
7887 @item @emph{Description}:
7888 Returns a single pseudorandom number or an array of pseudorandom numbers
7889 from the uniform distribution over the range @math{ 0 \leq x < 1}.
7890
7891 @item @emph{Standard}:
7892 F95 and later
7893
7894 @item @emph{Class}:
7895 Subroutine
7896
7897 @item @emph{Syntax}:
7898 @code{RANDOM_NUMBER(HARVEST)}
7899
7900 @item @emph{Arguments}:
7901 @multitable @columnfractions .15 .70
7902 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
7903 @end multitable
7904
7905 @item @emph{Example}:
7906 @smallexample
7907 program test_random_number
7908   REAL :: r(5,5)
7909   CALL init_random_seed()         ! see example of RANDOM_SEED
7910   CALL RANDOM_NUMBER(r)
7911 end program
7912 @end smallexample
7913
7914 @item @emph{Note}:
7915 The implemented random number generator is thread safe if used within
7916 OpenMP directives, i. e. its state will be consistent while called from
7917 multiple threads. Please note that the currently implemented KISS generator
7918 does not create random numbers in parallel from multiple sources, but in
7919 sequence from a single source. If your OpenMP-enabled application heavily
7920 relies on random numbers, you should consider employing a dedicated parallel
7921 random number generator instead.
7922
7923 @item @emph{See also}:
7924 @ref{RANDOM_SEED}
7925 @end table
7926
7927
7928
7929 @node RANDOM_SEED
7930 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
7931 @fnindex RANDOM_SEED
7932 @cindex random number generation, seeding
7933 @cindex seeding a random number generator
7934
7935 @table @asis
7936 @item @emph{Description}:
7937 Restarts or queries the state of the pseudorandom number generator used by
7938 @code{RANDOM_NUMBER}.
7939
7940 If @code{RANDOM_SEED} is called without arguments, it is initialized to
7941 a default state. The example below shows how to initialize the random
7942 seed based on the system's time.
7943
7944 @item @emph{Standard}:
7945 F95 and later
7946
7947 @item @emph{Class}:
7948 Subroutine
7949
7950 @item @emph{Syntax}:
7951 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
7952
7953 @item @emph{Arguments}:
7954 @multitable @columnfractions .15 .70
7955 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
7956 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
7957 of the arrays used with the @var{PUT} and @var{GET} arguments.
7958 @item @var{PUT}  @tab (Optional) Shall be an array of type default
7959 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
7960 the array must be larger than or equal to the number returned by the
7961 @var{SIZE} argument.
7962 @item @var{GET}  @tab (Optional) Shall be an array of type default
7963 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
7964 of the array must be larger than or equal to the number returned by
7965 the @var{SIZE} argument.
7966 @end multitable
7967
7968 @item @emph{Example}:
7969 @smallexample
7970 SUBROUTINE init_random_seed()
7971   INTEGER :: i, n, clock
7972   INTEGER, DIMENSION(:), ALLOCATABLE :: seed
7973
7974   CALL RANDOM_SEED(size = n)
7975   ALLOCATE(seed(n))
7976
7977   CALL SYSTEM_CLOCK(COUNT=clock)
7978
7979   seed = clock + 37 * (/ (i - 1, i = 1, n) /)
7980   CALL RANDOM_SEED(PUT = seed)
7981
7982   DEALLOCATE(seed)
7983 END SUBROUTINE
7984 @end smallexample
7985
7986 @item @emph{See also}:
7987 @ref{RANDOM_NUMBER}
7988 @end table
7989
7990
7991
7992 @node RANGE
7993 @section @code{RANGE} --- Decimal exponent range of a real kind
7994 @fnindex RANGE
7995 @cindex model representation, range
7996
7997 @table @asis
7998 @item @emph{Description}:
7999 @code{RANGE(X)} returns the decimal exponent range in the model of the
8000 type of @code{X}.
8001
8002 @item @emph{Standard}:
8003 F95 and later
8004
8005 @item @emph{Class}:
8006 Inquiry function
8007
8008 @item @emph{Syntax}:
8009 @code{RESULT = RANGE(X)}
8010
8011 @item @emph{Arguments}:
8012 @multitable @columnfractions .15 .70
8013 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8014 @end multitable
8015
8016 @item @emph{Return value}:
8017 The return value is of type @code{INTEGER} and of the default integer
8018 kind.
8019
8020 @item @emph{Example}:
8021 See @code{PRECISION} for an example.
8022 @end table
8023
8024
8025
8026 @node REAL
8027 @section @code{REAL} --- Convert to real type
8028 @fnindex REAL
8029 @fnindex REALPART
8030 @cindex conversion, to real
8031 @cindex complex numbers, real part
8032
8033 @table @asis
8034 @item @emph{Description}:
8035 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type.  The
8036 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8037 and its use is strongly discouraged.
8038
8039 @item @emph{Standard}:
8040 F77 and later
8041
8042 @item @emph{Class}:
8043 Elemental function
8044
8045 @item @emph{Syntax}:
8046 @multitable @columnfractions .80
8047 @item @code{RESULT = REAL(X [, KIND])}
8048 @item @code{RESULT = REALPART(Z)}
8049 @end multitable
8050
8051 @item @emph{Arguments}:
8052 @multitable @columnfractions .15 .70
8053 @item @var{X}    @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
8054                       @code{COMPLEX(*)}.
8055 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
8056                       expression indicating the kind parameter of
8057                       the result.
8058 @end multitable
8059
8060 @item @emph{Return value}:
8061 These functions return a @code{REAL(*)} variable or array under
8062 the following rules:
8063
8064 @table @asis
8065 @item (A)
8066 @code{REAL(X)} is converted to a default real type if @var{X} is an
8067 integer or real variable.
8068 @item (B)
8069 @code{REAL(X)} is converted to a real type with the kind type parameter
8070 of @var{X} if @var{X} is a complex variable.
8071 @item (C)
8072 @code{REAL(X, KIND)} is converted to a real type with kind type
8073 parameter @var{KIND} if @var{X} is a complex, integer, or real
8074 variable.
8075 @end table
8076
8077 @item @emph{Example}:
8078 @smallexample
8079 program test_real
8080   complex :: x = (1.0, 2.0)
8081   print *, real(x), real(x,8), realpart(x)
8082 end program test_real
8083 @end smallexample
8084
8085 @item @emph{See also}:
8086 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8087
8088 @end table
8089
8090
8091
8092 @node RENAME
8093 @section @code{RENAME} --- Rename a file
8094 @fnindex RENAME
8095 @cindex file system, rename file
8096
8097 @table @asis
8098 @item @emph{Description}:
8099 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8100 character (@code{CHAR(0)}) can be used to mark the end of the names in
8101 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8102 names are ignored.  If the @var{STATUS} argument is supplied, it
8103 contains 0 on success or a nonzero error code upon return; see
8104 @code{rename(2)}.
8105
8106 This intrinsic is provided in both subroutine and function forms;
8107 however, only one form can be used in any given program unit.
8108
8109 @item @emph{Standard}:
8110 GNU extension
8111
8112 @item @emph{Class}:
8113 Subroutine, non-elemental function
8114
8115 @item @emph{Syntax}:
8116 @multitable @columnfractions .80
8117 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8118 @item @code{STATUS = RENAME(PATH1, PATH2)}
8119 @end multitable
8120
8121 @item @emph{Arguments}:
8122 @multitable @columnfractions .15 .70
8123 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8124 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8125 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8126 @end multitable
8127
8128 @item @emph{See also}:
8129 @ref{LINK}
8130
8131 @end table
8132
8133
8134
8135 @node REPEAT
8136 @section @code{REPEAT} --- Repeated string concatenation
8137 @fnindex REPEAT
8138 @cindex string, repeat
8139 @cindex string, concatenate
8140
8141 @table @asis
8142 @item @emph{Description}:
8143 Concatenates @var{NCOPIES} copies of a string.
8144
8145 @item @emph{Standard}:
8146 F95 and later
8147
8148 @item @emph{Class}:
8149 Transformational function
8150
8151 @item @emph{Syntax}:
8152 @code{RESULT = REPEAT(STRING, NCOPIES)}
8153
8154 @item @emph{Arguments}:
8155 @multitable @columnfractions .15 .70
8156 @item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER(*)}.
8157 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
8158 @end multitable
8159
8160 @item @emph{Return value}:
8161 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
8162 of @var{STRING}.
8163
8164 @item @emph{Example}:
8165 @smallexample
8166 program test_repeat
8167   write(*,*) repeat("x", 5)   ! "xxxxx"
8168 end program
8169 @end smallexample
8170 @end table
8171
8172
8173
8174 @node RESHAPE
8175 @section @code{RESHAPE} --- Function to reshape an array
8176 @fnindex RESHAPE
8177 @cindex array, change dimensions
8178 @cindex array, transmogrify
8179
8180 @table @asis
8181 @item @emph{Description}:
8182 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
8183 the new array may be padded with elements from @var{PAD} or permuted
8184 as defined by @var{ORDER}.
8185
8186 @item @emph{Standard}:
8187 F95 and later
8188
8189 @item @emph{Class}:
8190 Transformational function
8191
8192 @item @emph{Syntax}:
8193 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
8194
8195 @item @emph{Arguments}:
8196 @multitable @columnfractions .15 .70
8197 @item @var{SOURCE} @tab Shall be an array of any type.
8198 @item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
8199 array of rank one. Its values must be positive or zero.
8200 @item @var{PAD}    @tab (Optional) shall be an array of the same
8201 type as @var{SOURCE}.
8202 @item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
8203 and an array of the same shape as @var{SHAPE}. Its values shall
8204 be a permutation of the numbers from 1 to n, where n is the size of
8205 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
8206 be assumed.
8207 @end multitable
8208
8209 @item @emph{Return value}:
8210 The result is an array of shape @var{SHAPE} with the same type as
8211 @var{SOURCE}.
8212
8213 @item @emph{Example}:
8214 @smallexample
8215 PROGRAM test_reshape
8216   INTEGER, DIMENSION(4) :: x
8217   WRITE(*,*) SHAPE(x)                       ! prints "4"
8218   WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
8219 END PROGRAM
8220 @end smallexample
8221
8222 @item @emph{See also}:
8223 @ref{SHAPE}
8224 @end table
8225
8226
8227
8228 @node RRSPACING
8229 @section @code{RRSPACING} --- Reciprocal of the relative spacing
8230 @fnindex RRSPACING
8231 @cindex real number, relative spacing
8232 @cindex floating point, relative spacing
8233
8234
8235 @table @asis
8236 @item @emph{Description}:
8237 @code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
8238 model numbers near @var{X}.
8239
8240 @item @emph{Standard}:
8241 F95 and later
8242
8243 @item @emph{Class}:
8244 Elemental function
8245
8246 @item @emph{Syntax}:
8247 @code{RESULT = RRSPACING(X)}
8248
8249 @item @emph{Arguments}:
8250 @multitable @columnfractions .15 .70
8251 @item @var{X} @tab Shall be of type @code{REAL}.
8252 @end multitable
8253
8254 @item @emph{Return value}:
8255 The return value is of the same type and kind as @var{X}.
8256 The value returned is equal to
8257 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
8258
8259 @item @emph{See also}:
8260 @ref{SPACING}
8261 @end table
8262
8263
8264
8265 @node RSHIFT
8266 @section @code{RSHIFT} --- Right shift bits
8267 @fnindex RSHIFT
8268 @cindex bits, shift right
8269
8270 @table @asis
8271 @item @emph{Description}:
8272 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
8273 bits shifted right by @var{SHIFT} places.  If the absolute value of
8274 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8275 Bits shifted out from the left end are lost; zeros are shifted in from
8276 the opposite end.
8277
8278 This function has been superseded by the @code{ISHFT} intrinsic, which
8279 is standard in Fortran 95 and later.
8280
8281 @item @emph{Standard}:
8282 GNU extension
8283
8284 @item @emph{Class}:
8285 Elemental function
8286
8287 @item @emph{Syntax}:
8288 @code{RESULT = RSHIFT(I, SHIFT)}
8289
8290 @item @emph{Arguments}:
8291 @multitable @columnfractions .15 .70
8292 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8293 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
8294 @end multitable
8295
8296 @item @emph{Return value}:
8297 The return value is of type @code{INTEGER(*)} and of the same kind as
8298 @var{I}.
8299
8300 @item @emph{See also}:
8301 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
8302
8303 @end table
8304
8305
8306
8307 @node SCALE
8308 @section @code{SCALE} --- Scale a real value
8309 @fnindex SCALE
8310 @cindex real number, scale
8311 @cindex floating point, scale
8312
8313 @table @asis
8314 @item @emph{Description}:
8315 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
8316
8317 @item @emph{Standard}:
8318 F95 and later
8319
8320 @item @emph{Class}:
8321 Elemental function
8322
8323 @item @emph{Syntax}:
8324 @code{RESULT = SCALE(X, I)}
8325
8326 @item @emph{Arguments}:
8327 @multitable @columnfractions .15 .70
8328 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
8329 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
8330 @end multitable
8331
8332 @item @emph{Return value}:
8333 The return value is of the same type and kind as @var{X}.
8334 Its value is @code{X * RADIX(X)**I}.
8335
8336 @item @emph{Example}:
8337 @smallexample
8338 program test_scale
8339   real :: x = 178.1387e-4
8340   integer :: i = 5
8341   print *, scale(x,i), x*radix(x)**i
8342 end program test_scale
8343 @end smallexample
8344
8345 @end table
8346
8347
8348
8349 @node SCAN
8350 @section @code{SCAN} --- Scan a string for the presence of a set of characters
8351 @fnindex SCAN
8352 @cindex string, find subset
8353
8354 @table @asis
8355 @item @emph{Description}:
8356 Scans a @var{STRING} for any of the characters in a @var{SET}
8357 of characters.
8358
8359 If @var{BACK} is either absent or equals @code{FALSE}, this function
8360 returns the position of the leftmost character of @var{STRING} that is
8361 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
8362 is returned. If no character of @var{SET} is found in @var{STRING}, the
8363 result is zero.
8364
8365 @item @emph{Standard}:
8366 F95 and later
8367
8368 @item @emph{Class}:
8369 Elemental function
8370
8371 @item @emph{Syntax}:
8372 @code{RESULT = SCAN(STRING, SET[, BACK])}
8373
8374 @item @emph{Arguments}:
8375 @multitable @columnfractions .15 .70
8376 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
8377 @item @var{SET}    @tab Shall be of type @code{CHARACTER(*)}.
8378 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
8379 @end multitable
8380
8381 @item @emph{Return value}:
8382 The return value is of type @code{INTEGER} and of the default
8383 integer kind.
8384
8385 @item @emph{Example}:
8386 @smallexample
8387 PROGRAM test_scan
8388   WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
8389   WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
8390   WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
8391 END PROGRAM
8392 @end smallexample
8393
8394 @item @emph{See also}:
8395 @ref{INDEX}, @ref{VERIFY}
8396 @end table
8397
8398
8399
8400 @node SECNDS
8401 @section @code{SECNDS} --- Time function
8402 @fnindex SECNDS
8403 @cindex time, elapsed
8404 @cindex elapsed time
8405
8406 @table @asis
8407 @item @emph{Description}:
8408 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
8409 @var{X} is a reference time, also in seconds. If this is zero, the time in
8410 seconds from midnight is returned. This function is non-standard and its
8411 use is discouraged.
8412
8413 @item @emph{Standard}:
8414 GNU extension
8415
8416 @item @emph{Class}:
8417 Non-elemental function
8418
8419 @item @emph{Syntax}:
8420 @code{RESULT = SECNDS (X)}
8421
8422 @item @emph{Arguments}:
8423 @multitable @columnfractions .15 .70
8424 @item @var{T}     @tab Shall be of type @code{REAL(4)}.
8425 @item @var{X}     @tab Shall be of type @code{REAL(4)}.
8426 @end multitable
8427
8428 @item @emph{Return value}:
8429 None
8430
8431 @item @emph{Example}:
8432 @smallexample
8433 program test_secnds
8434     integer :: i
8435     real(4) :: t1, t2
8436     print *, secnds (0.0)   ! seconds since midnight
8437     t1 = secnds (0.0)       ! reference time
8438     do i = 1, 10000000      ! do something
8439     end do
8440     t2 = secnds (t1)        ! elapsed time
8441     print *, "Something took ", t2, " seconds."
8442 end program test_secnds
8443 @end smallexample
8444 @end table
8445
8446
8447
8448 @node SECOND
8449 @section @code{SECOND} --- CPU time function
8450 @fnindex SECOND
8451 @cindex time, elapsed
8452 @cindex elapsed time
8453
8454 @table @asis
8455 @item @emph{Description}:
8456 Returns a @code{REAL(4)} value representing the elapsed CPU time in
8457 seconds.  This provides the same functionality as the standard
8458 @code{CPU_TIME} intrinsic, and is only included for backwards
8459 compatibility.
8460
8461 This intrinsic is provided in both subroutine and function forms;
8462 however, only one form can be used in any given program unit.
8463
8464 @item @emph{Standard}:
8465 GNU extension
8466
8467 @item @emph{Class}:
8468 Subroutine, non-elemental function
8469
8470 @item @emph{Syntax}:
8471 @multitable @columnfractions .80
8472 @item @code{CALL SECOND(TIME)}
8473 @item @code{TIME = SECOND()}
8474 @end multitable
8475
8476 @item @emph{Arguments}:
8477 @multitable @columnfractions .15 .70
8478 @item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
8479 @end multitable
8480
8481 @item @emph{Return value}:
8482 In either syntax, @var{TIME} is set to the process's current runtime in
8483 seconds.
8484
8485 @item @emph{See also}:
8486 @ref{CPU_TIME}
8487
8488 @end table
8489
8490
8491
8492 @node SELECTED_INT_KIND
8493 @section @code{SELECTED_INT_KIND} --- Choose integer kind
8494 @fnindex SELECTED_INT_KIND
8495 @cindex integer kind
8496 @cindex kind, integer
8497
8498 @table @asis
8499 @item @emph{Description}:
8500 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
8501 type that can represent all values ranging from @math{-10^I} (exclusive)
8502 to @math{10^I} (exclusive). If there is no integer kind that accommodates
8503 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
8504
8505 @item @emph{Standard}:
8506 F95 and later
8507
8508 @item @emph{Class}:
8509 Transformational function
8510
8511 @item @emph{Syntax}:
8512 @code{RESULT = SELECTED_INT_KIND(I)}
8513
8514 @item @emph{Arguments}:
8515 @multitable @columnfractions .15 .70
8516 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
8517 @end multitable
8518
8519 @item @emph{Example}:
8520 @smallexample
8521 program large_integers
8522   integer,parameter :: k5 = selected_int_kind(5)
8523   integer,parameter :: k15 = selected_int_kind(15)
8524   integer(kind=k5) :: i5
8525   integer(kind=k15) :: i15
8526
8527   print *, huge(i5), huge(i15)
8528
8529   ! The following inequalities are always true
8530   print *, huge(i5) >= 10_k5**5-1
8531   print *, huge(i15) >= 10_k15**15-1
8532 end program large_integers
8533 @end smallexample
8534 @end table
8535
8536
8537
8538 @node SELECTED_REAL_KIND
8539 @section @code{SELECTED_REAL_KIND} --- Choose real kind
8540 @fnindex SELECTED_REAL_KIND
8541 @cindex real kind
8542 @cindex kind, real
8543
8544 @table @asis
8545 @item @emph{Description}:
8546 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
8547 with decimal precision greater of at least @code{P} digits and exponent
8548 range greater at least @code{R}.
8549
8550 @item @emph{Standard}:
8551 F95 and later
8552
8553 @item @emph{Class}:
8554 Transformational function
8555
8556 @item @emph{Syntax}:
8557 @code{RESULT = SELECTED_REAL_KIND(P, R)}
8558
8559 @item @emph{Arguments}:
8560 @multitable @columnfractions .15 .70
8561 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
8562 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
8563 @end multitable
8564 At least one argument shall be present.
8565
8566 @item @emph{Return value}:
8567
8568 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
8569 a real data type with decimal precision of at least @code{P} digits and a
8570 decimal exponent range of at least @code{R}. If more than one real data
8571 type meet the criteria, the kind of the data type with the smallest
8572 decimal precision is returned. If no real data type matches the criteria,
8573 the result is
8574 @table @asis
8575 @item -1 if the processor does not support a real data type with a
8576 precision greater than or equal to @code{P}
8577 @item -2 if the processor does not support a real type with an exponent
8578 range greater than or equal to @code{R}
8579 @item -3 if neither is supported.
8580 @end table
8581
8582 @item @emph{Example}:
8583 @smallexample
8584 program real_kinds
8585   integer,parameter :: p6 = selected_real_kind(6)
8586   integer,parameter :: p10r100 = selected_real_kind(10,100)
8587   integer,parameter :: r400 = selected_real_kind(r=400)
8588   real(kind=p6) :: x
8589   real(kind=p10r100) :: y
8590   real(kind=r400) :: z
8591
8592   print *, precision(x), range(x)
8593   print *, precision(y), range(y)
8594   print *, precision(z), range(z)
8595 end program real_kinds
8596 @end smallexample
8597 @end table
8598
8599
8600
8601 @node SET_EXPONENT
8602 @section @code{SET_EXPONENT} --- Set the exponent of the model
8603 @fnindex SET_EXPONENT
8604 @cindex real number, set exponent
8605 @cindex floating point, set exponent
8606
8607 @table @asis
8608 @item @emph{Description}:
8609 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
8610 is that that of @var{X} and whose exponent part is @var{I}.
8611
8612 @item @emph{Standard}:
8613 F95 and later
8614
8615 @item @emph{Class}:
8616 Elemental function
8617
8618 @item @emph{Syntax}:
8619 @code{RESULT = SET_EXPONENT(X, I)}
8620
8621 @item @emph{Arguments}:
8622 @multitable @columnfractions .15 .70
8623 @item @var{X} @tab Shall be of type @code{REAL}.
8624 @item @var{I} @tab Shall be of type @code{INTEGER}.
8625 @end multitable
8626
8627 @item @emph{Return value}:
8628 The return value is of the same type and kind as @var{X}.
8629 The real number whose fractional part
8630 is that that of @var{X} and whose exponent part if @var{I} is returned;
8631 it is @code{FRACTION(X) * RADIX(X)**I}.
8632
8633 @item @emph{Example}:
8634 @smallexample
8635 PROGRAM test_setexp
8636   REAL :: x = 178.1387e-4
8637   INTEGER :: i = 17
8638   PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
8639 END PROGRAM
8640 @end smallexample
8641
8642 @end table
8643
8644
8645
8646 @node SHAPE
8647 @section @code{SHAPE} --- Determine the shape of an array
8648 @fnindex SHAPE
8649 @cindex array, shape
8650
8651 @table @asis
8652 @item @emph{Description}:
8653 Determines the shape of an array.
8654
8655 @item @emph{Standard}:
8656 F95 and later
8657
8658 @item @emph{Class}:
8659 Inquiry function
8660
8661 @item @emph{Syntax}:
8662 @code{RESULT = SHAPE(SOURCE)}
8663
8664 @item @emph{Arguments}:
8665 @multitable @columnfractions .15 .70
8666 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
8667 If @var{SOURCE} is a pointer it must be associated and allocatable
8668 arrays must be allocated.
8669 @end multitable
8670
8671 @item @emph{Return value}:
8672 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
8673 has dimensions. The elements of the resulting array correspond to the extend
8674 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
8675 the result is the rank one array of size zero.
8676
8677 @item @emph{Example}:
8678 @smallexample
8679 PROGRAM test_shape
8680   INTEGER, DIMENSION(-1:1, -1:2) :: A
8681   WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
8682   WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
8683 END PROGRAM
8684 @end smallexample
8685
8686 @item @emph{See also}:
8687 @ref{RESHAPE}, @ref{SIZE}
8688 @end table
8689
8690
8691
8692 @node SIGN
8693 @section @code{SIGN} --- Sign copying function
8694 @fnindex SIGN
8695 @fnindex ISIGN
8696 @fnindex DSIGN
8697 @cindex sign copying
8698
8699 @table @asis
8700 @item @emph{Description}:
8701 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
8702
8703 @item @emph{Standard}:
8704 F77 and later
8705
8706 @item @emph{Class}:
8707 Elemental function
8708
8709 @item @emph{Syntax}:
8710 @code{RESULT = SIGN(A, B)}
8711
8712 @item @emph{Arguments}:
8713 @multitable @columnfractions .15 .70
8714 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
8715 @item @var{B} @tab Shall be of the same type and kind as @var{A}
8716 @end multitable
8717
8718 @item @emph{Return value}:
8719 The kind of the return value is that of @var{A} and @var{B}.
8720 If @math{B\ge 0} then the result is @code{ABS(A)}, else
8721 it is @code{-ABS(A)}.
8722
8723 @item @emph{Example}:
8724 @smallexample
8725 program test_sign
8726   print *, sign(-12,1)
8727   print *, sign(-12,0)
8728   print *, sign(-12,-1)
8729
8730   print *, sign(-12.,1.)
8731   print *, sign(-12.,0.)
8732   print *, sign(-12.,-1.)
8733 end program test_sign
8734 @end smallexample
8735
8736 @item @emph{Specific names}:
8737 @multitable @columnfractions .20 .20 .20 .25
8738 @item Name              @tab Arguments      @tab Return type    @tab Standard
8739 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
8740 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
8741 @end multitable
8742 @end table
8743
8744
8745
8746 @node SIGNAL
8747 @section @code{SIGNAL} --- Signal handling subroutine (or function)
8748 @fnindex SIGNAL
8749 @cindex system, signal handling
8750
8751 @table @asis
8752 @item @emph{Description}:
8753 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
8754 @var{HANDLER} to be executed with a single integer argument when signal
8755 @var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
8756 turn off handling of signal @var{NUMBER} or revert to its default
8757 action.  See @code{signal(2)}.
8758
8759 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
8760 is supplied, it is set to the value returned by @code{signal(2)}.
8761
8762 @item @emph{Standard}:
8763 GNU extension
8764
8765 @item @emph{Class}:
8766 Subroutine, non-elemental function
8767
8768 @item @emph{Syntax}:
8769 @multitable @columnfractions .80
8770 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
8771 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
8772 @end multitable
8773
8774 @item @emph{Arguments}:
8775 @multitable @columnfractions .15 .70
8776 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
8777 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
8778 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
8779 @code{INTEGER}. It is @code{INTENT(IN)}.
8780 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
8781 integer. It has @code{INTENT(OUT)}.
8782 @end multitable
8783
8784 @item @emph{Return value}:
8785 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
8786
8787 @item @emph{Example}:
8788 @smallexample
8789 program test_signal
8790   intrinsic signal
8791   external handler_print
8792
8793   call signal (12, handler_print)
8794   call signal (10, 1)
8795
8796   call sleep (30)
8797 end program test_signal
8798 @end smallexample
8799 @end table
8800
8801
8802
8803 @node SIN
8804 @section @code{SIN} --- Sine function
8805 @fnindex SIN
8806 @fnindex DSIN
8807 @fnindex CSIN
8808 @fnindex ZSIN
8809 @fnindex CDSIN
8810 @cindex trigonometric function, sine
8811 @cindex sine
8812
8813 @table @asis
8814 @item @emph{Description}:
8815 @code{SIN(X)} computes the sine of @var{X}.
8816
8817 @item @emph{Standard}:
8818 F77 and later
8819
8820 @item @emph{Class}:
8821 Elemental function
8822
8823 @item @emph{Syntax}:
8824 @code{RESULT = SIN(X)}
8825
8826 @item @emph{Arguments}:
8827 @multitable @columnfractions .15 .70
8828 @item @var{X} @tab The type shall be @code{REAL(*)} or
8829 @code{COMPLEX(*)}.
8830 @end multitable
8831
8832 @item @emph{Return value}:
8833 The return value has same type and kind as @var{X}.
8834
8835 @item @emph{Example}:
8836 @smallexample
8837 program test_sin
8838   real :: x = 0.0
8839   x = sin(x)
8840 end program test_sin
8841 @end smallexample
8842
8843 @item @emph{Specific names}:
8844 @multitable @columnfractions .20 .20 .20 .25
8845 @item Name            @tab Argument          @tab Return type       @tab Standard
8846 @item @code{DSIN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
8847 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
8848 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
8849 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
8850 @end multitable
8851
8852 @item @emph{See also}:
8853 @ref{ASIN}
8854 @end table
8855
8856
8857
8858 @node SINH
8859 @section @code{SINH} --- Hyperbolic sine function
8860 @fnindex SINH
8861 @fnindex DSINH
8862 @cindex hyperbolic sine
8863 @cindex hyperbolic function, sine
8864 @cindex sine, hyperbolic
8865
8866 @table @asis
8867 @item @emph{Description}:
8868 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
8869
8870 @item @emph{Standard}:
8871 F95 and later
8872
8873 @item @emph{Class}:
8874 Elemental function
8875
8876 @item @emph{Syntax}:
8877 @code{RESULT = SINH(X)}
8878
8879 @item @emph{Arguments}:
8880 @multitable @columnfractions .15 .70
8881 @item @var{X} @tab The type shall be @code{REAL(*)}.
8882 @end multitable
8883
8884 @item @emph{Return value}:
8885 The return value is of type @code{REAL(*)}.
8886
8887 @item @emph{Example}:
8888 @smallexample
8889 program test_sinh
8890   real(8) :: x = - 1.0_8
8891   x = sinh(x)
8892 end program test_sinh
8893 @end smallexample
8894
8895 @item @emph{Specific names}:
8896 @multitable @columnfractions .20 .20 .20 .25
8897 @item Name            @tab Argument          @tab Return type       @tab Standard
8898 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F95 and later
8899 @end multitable
8900
8901 @item @emph{See also}:
8902 @ref{ASINH}
8903 @end table
8904
8905
8906
8907 @node SIZE
8908 @section @code{SIZE} --- Determine the size of an array
8909 @fnindex SIZE
8910 @cindex array, size
8911 @cindex array, number of elements
8912 @cindex array, count elements
8913
8914 @table @asis
8915 @item @emph{Description}:
8916 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
8917 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
8918
8919 @item @emph{Standard}:
8920 F95 and later
8921
8922 @item @emph{Class}:
8923 Inquiry function
8924
8925 @item @emph{Syntax}:
8926 @code{RESULT = SIZE(ARRAY[, DIM])}
8927
8928 @item @emph{Arguments}:
8929 @multitable @columnfractions .15 .70
8930 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
8931 a pointer it must be associated and allocatable arrays must be allocated.
8932 @item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
8933 and its value shall be in the range from 1 to n, where n equals the rank
8934 of @var{ARRAY}.
8935 @end multitable
8936
8937 @item @emph{Return value}:
8938 The return value is of type @code{INTEGER} and of the default
8939 integer kind.
8940
8941 @item @emph{Example}:
8942 @smallexample
8943 PROGRAM test_size
8944   WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
8945 END PROGRAM
8946 @end smallexample
8947
8948 @item @emph{See also}:
8949 @ref{SHAPE}, @ref{RESHAPE}
8950 @end table
8951
8952
8953
8954 @node SLEEP
8955 @section @code{SLEEP} --- Sleep for the specified number of seconds
8956 @fnindex SLEEP
8957 @cindex delayed execution
8958
8959 @table @asis
8960 @item @emph{Description}:
8961 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
8962
8963 @item @emph{Standard}:
8964 GNU extension
8965
8966 @item @emph{Class}:
8967 Subroutine
8968
8969 @item @emph{Syntax}:
8970 @code{CALL SLEEP(SECONDS)}
8971
8972 @item @emph{Arguments}:
8973 @multitable @columnfractions .15 .70
8974 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
8975 @end multitable
8976
8977 @item @emph{Example}:
8978 @smallexample
8979 program test_sleep
8980   call sleep(5)
8981 end
8982 @end smallexample
8983 @end table
8984
8985
8986
8987 @node SNGL
8988 @section @code{SNGL} --- Convert double precision real to default real
8989 @fnindex SNGL
8990 @cindex conversion, to real
8991
8992 @table @asis
8993 @item @emph{Description}:
8994 @code{SNGL(A)} converts the double precision real @var{A}
8995 to a default real value. This is an archaic form of @code{REAL}
8996 that is specific to one type for @var{A}.
8997
8998 @item @emph{Standard}:
8999 GNU extension
9000
9001 @item @emph{Class}:
9002 Elemental function
9003
9004 @item @emph{Syntax}:
9005 @code{RESULT = SNGL(A)}
9006
9007 @item @emph{Arguments}:
9008 @multitable @columnfractions .15 .70
9009 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9010 @end multitable
9011
9012 @item @emph{Return value}:
9013 The return value is of type default @code{REAL}.
9014
9015 @item @emph{See also}:
9016 @ref{DBLE}
9017 @end table
9018
9019
9020
9021 @node SPACING
9022 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9023 @fnindex SPACING
9024 @cindex real number, relative spacing
9025 @cindex floating point, relative spacing
9026
9027 @table @asis
9028 @item @emph{Description}:
9029 Determines the distance between the argument @var{X} and the nearest
9030 adjacent number of the same type.
9031
9032 @item @emph{Standard}:
9033 F95 and later
9034
9035 @item @emph{Class}:
9036 Elemental function
9037
9038 @item @emph{Syntax}:
9039 @code{RESULT = SPACING(X)}
9040
9041 @item @emph{Arguments}:
9042 @multitable @columnfractions .15 .70
9043 @item @var{X} @tab Shall be of type @code{REAL(*)}.
9044 @end multitable
9045
9046 @item @emph{Return value}:
9047 The result is of the same type as the input argument @var{X}.
9048
9049 @item @emph{Example}:
9050 @smallexample
9051 PROGRAM test_spacing
9052   INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9053   INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9054
9055   WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
9056   WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
9057 END PROGRAM
9058 @end smallexample
9059
9060 @item @emph{See also}:
9061 @ref{RRSPACING}
9062 @end table
9063
9064
9065
9066 @node SPREAD
9067 @section @code{SPREAD} --- Add a dimension to an array
9068 @fnindex SPREAD
9069 @cindex array, increase dimension
9070 @cindex array, duplicate elementes
9071 @cindex array, duplicate dimensions
9072
9073 @table @asis
9074 @item @emph{Description}:
9075 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
9076 dimension @var{DIM}.
9077
9078 @item @emph{Standard}:
9079 F95 and later
9080
9081 @item @emph{Class}:
9082 Transformational function
9083
9084 @item @emph{Syntax}:
9085 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
9086
9087 @item @emph{Arguments}:
9088 @multitable @columnfractions .15 .70
9089 @item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
9090 a rank less than seven.
9091 @item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
9092 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
9093 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
9094 @end multitable
9095
9096 @item @emph{Return value}:
9097 The result is an array of the same type as @var{SOURCE} and has rank n+1
9098 where n equals the rank of @var{SOURCE}.
9099
9100 @item @emph{Example}:
9101 @smallexample
9102 PROGRAM test_spread
9103   INTEGER :: a = 1, b(2) = (/ 1, 2 /)
9104   WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
9105   WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
9106 END PROGRAM
9107 @end smallexample
9108
9109 @item @emph{See also}:
9110 @ref{UNPACK}
9111 @end table
9112
9113
9114
9115 @node SQRT
9116 @section @code{SQRT} --- Square-root function
9117 @fnindex SQRT
9118 @fnindex DSQRT
9119 @fnindex CSQRT
9120 @fnindex ZSQRT
9121 @fnindex CDSQRT
9122 @cindex root
9123 @cindex square-root
9124
9125 @table @asis
9126 @item @emph{Description}:
9127 @code{SQRT(X)} computes the square root of @var{X}.
9128
9129 @item @emph{Standard}:
9130 F77 and later
9131
9132 @item @emph{Class}:
9133 Elemental function
9134
9135 @item @emph{Syntax}:
9136 @code{RESULT = SQRT(X)}
9137
9138 @item @emph{Arguments}:
9139 @multitable @columnfractions .15 .70
9140 @item @var{X} @tab The type shall be @code{REAL(*)} or
9141 @code{COMPLEX(*)}.
9142 @end multitable
9143
9144 @item @emph{Return value}:
9145 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
9146 The kind type parameter is the same as @var{X}.
9147
9148 @item @emph{Example}:
9149 @smallexample
9150 program test_sqrt
9151   real(8) :: x = 2.0_8
9152   complex :: z = (1.0, 2.0)
9153   x = sqrt(x)
9154   z = sqrt(z)
9155 end program test_sqrt
9156 @end smallexample
9157
9158 @item @emph{Specific names}:
9159 @multitable @columnfractions .20 .20 .20 .25
9160 @item Name             @tab Argument             @tab Return type          @tab Standard
9161 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab F95 and later
9162 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab F95 and later
9163 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
9164 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
9165 @end multitable
9166 @end table
9167
9168
9169
9170 @node SRAND
9171 @section @code{SRAND} --- Reinitialize the random number generator
9172 @fnindex SRAND
9173 @cindex random number generation, seeding
9174 @cindex seeding a random number generator
9175
9176 @table @asis
9177 @item @emph{Description}:
9178 @code{SRAND} reinitializes the pseudo-random number generator
9179 called by @code{RAND} and @code{IRAND}. The new seed used by the
9180 generator is specified by the required argument @var{SEED}.
9181
9182 @item @emph{Standard}:
9183 GNU extension
9184
9185 @item @emph{Class}:
9186 Non-elemental subroutine
9187
9188 @item @emph{Syntax}:
9189 @code{CALL SRAND(SEED)}
9190
9191 @item @emph{Arguments}:
9192 @multitable @columnfractions .15 .70
9193 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
9194 @end multitable
9195
9196 @item @emph{Return value}:
9197 Does not return.
9198
9199 @item @emph{Example}:
9200 See @code{RAND} and @code{IRAND} for examples.
9201
9202 @item @emph{Notes}:
9203 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
9204 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
9205 to generate pseudo-random numbers. Please note that in
9206 GNU Fortran, these two sets of intrinsics (@code{RAND},
9207 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
9208 @code{RANDOM_SEED} on the other hand) access two independent
9209 pseudo-random number generators.
9210
9211 @item @emph{See also}:
9212 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
9213
9214 @end table
9215
9216
9217
9218 @node STAT
9219 @section @code{STAT} --- Get file status
9220 @fnindex STAT
9221 @cindex file system, file status
9222
9223 @table @asis
9224 @item @emph{Description}:
9225 This function returns information about a file. No permissions are required on
9226 the file itself, but execute (search) permission is required on all of the
9227 directories in path that lead to the file.
9228
9229 The elements that are obtained and stored in the array @code{BUFF}:
9230 @multitable @columnfractions .15 .70
9231 @item @code{buff(1)}   @tab  Device ID
9232 @item @code{buff(2)}   @tab  Inode number
9233 @item @code{buff(3)}   @tab  File mode
9234 @item @code{buff(4)}   @tab  Number of links
9235 @item @code{buff(5)}   @tab  Owner's uid
9236 @item @code{buff(6)}   @tab  Owner's gid
9237 @item @code{buff(7)}   @tab  ID of device containing directory entry for file (0 if not available)
9238 @item @code{buff(8)}   @tab  File size (bytes)
9239 @item @code{buff(9)}   @tab  Last access time
9240 @item @code{buff(10)}  @tab  Last modification time
9241 @item @code{buff(11)}  @tab  Last file status change time
9242 @item @code{buff(12)}  @tab  Preferred I/O block size (-1 if not available)
9243 @item @code{buff(13)}  @tab  Number of blocks allocated (-1 if not available)
9244 @end multitable
9245
9246 Not all these elements are relevant on all systems.
9247 If an element is not relevant, it is returned as 0.
9248
9249
9250 @item @emph{Standard}:
9251 GNU extension
9252
9253 @item @emph{Class}:
9254 Non-elemental subroutine
9255
9256 @item @emph{Syntax}:
9257 @code{CALL STAT(FILE,BUFF[,STATUS])}
9258
9259 @item @emph{Arguments}:
9260 @multitable @columnfractions .15 .70
9261 @item @var{FILE}   @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
9262 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9263 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
9264                         on success and a system specific error code otherwise.
9265 @end multitable
9266
9267 @item @emph{Example}:
9268 @smallexample
9269 PROGRAM test_stat
9270   INTEGER, DIMENSION(13) :: buff
9271   INTEGER :: status
9272
9273   CALL STAT("/etc/passwd", buff, status)
9274
9275   IF (status == 0) THEN
9276     WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
9277     WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
9278     WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
9279     WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
9280     WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
9281     WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
9282     WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
9283     WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
9284     WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
9285     WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
9286     WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
9287     WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
9288     WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
9289   END IF
9290 END PROGRAM
9291 @end smallexample
9292
9293 @item @emph{See also}:
9294 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
9295 @end table
9296
9297
9298
9299 @node SUM
9300 @section @code{SUM} --- Sum of array elements
9301 @fnindex SUM
9302 @cindex array, sum
9303 @cindex array, add elements
9304 @cindex array, conditionally add elements
9305 @cindex sum array elements
9306
9307 @table @asis
9308 @item @emph{Description}:
9309 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
9310 the corresponding element in @var{MASK} is @code{TRUE}.
9311
9312 @item @emph{Standard}:
9313 F95 and later
9314
9315 @item @emph{Class}:
9316 Transformational function
9317
9318 @item @emph{Syntax}:
9319 @code{RESULT = SUM(ARRAY[, MASK])}
9320 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
9321
9322 @item @emph{Arguments}:
9323 @multitable @columnfractions .15 .70
9324 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
9325 @code{REAL(*)} or @code{COMPLEX(*)}.
9326 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9327 @code{INTEGER} with a value in the range from 1 to n, where n
9328 equals the rank of @var{ARRAY}.
9329 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
9330 and either be a scalar or an array of the same shape as @var{ARRAY}.
9331 @end multitable
9332
9333 @item @emph{Return value}:
9334 The result is of the same type as @var{ARRAY}.
9335
9336 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
9337 is returned. Otherwise, an array of rank n-1, where n equals the rank of
9338 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
9339 dropped is returned.
9340
9341 @item @emph{Example}:
9342 @smallexample
9343 PROGRAM test_sum
9344   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9345   print *, SUM(x)                        ! all elements, sum = 15
9346   print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
9347 END PROGRAM
9348 @end smallexample
9349
9350 @item @emph{See also}:
9351 @ref{PRODUCT}
9352 @end table
9353
9354
9355
9356 @node SYMLNK
9357 @section @code{SYMLNK} --- Create a symbolic link
9358 @fnindex SYMLNK
9359 @cindex file system, create link
9360 @cindex file system, soft link
9361
9362 @table @asis
9363 @item @emph{Description}:
9364 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
9365 character (@code{CHAR(0)}) can be used to mark the end of the names in
9366 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9367 names are ignored.  If the @var{STATUS} argument is supplied, it
9368 contains 0 on success or a nonzero error code upon return; see
9369 @code{symlink(2)}.  If the system does not supply @code{symlink(2)},
9370 @code{ENOSYS} is returned.
9371
9372 This intrinsic is provided in both subroutine and function forms;
9373 however, only one form can be used in any given program unit.
9374
9375 @item @emph{Standard}:
9376 GNU extension
9377
9378 @item @emph{Class}:
9379 Subroutine, non-elemental function
9380
9381 @item @emph{Syntax}:
9382 @multitable @columnfractions .80
9383 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
9384 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
9385 @end multitable
9386
9387 @item @emph{Arguments}:
9388 @multitable @columnfractions .15 .70
9389 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9390 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9391 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9392 @end multitable
9393
9394 @item @emph{See also}:
9395 @ref{LINK}, @ref{UNLINK}
9396
9397 @end table
9398
9399
9400
9401 @node SYSTEM
9402 @section @code{SYSTEM} --- Execute a shell command
9403 @fnindex SYSTEM
9404 @cindex system, system call
9405
9406 @table @asis
9407 @item @emph{Description}:
9408 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
9409 argument @var{STATUS} is present, it contains the value returned by
9410 @code{system(3)}, which is presumably 0 if the shell command succeeded.
9411 Note that which shell is used to invoke the command is system-dependent
9412 and environment-dependent.
9413
9414 This intrinsic is provided in both subroutine and function forms;
9415 however, only one form can be used in any given program unit.
9416
9417 @item @emph{Standard}:
9418 GNU extension
9419
9420 @item @emph{Class}:
9421 Subroutine, non-elemental function
9422
9423 @item @emph{Syntax}:
9424 @multitable @columnfractions .80
9425 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
9426 @item @code{STATUS = SYSTEM(COMMAND)}
9427 @end multitable
9428
9429 @item @emph{Arguments}:
9430 @multitable @columnfractions .15 .70
9431 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
9432 @item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
9433 @end multitable
9434
9435 @item @emph{See also}:
9436 @end table
9437
9438
9439
9440 @node SYSTEM_CLOCK
9441 @section @code{SYSTEM_CLOCK} --- Time function
9442 @fnindex SYSTEM_CLOCK
9443 @cindex time, clock ticks
9444 @cindex clock ticks
9445
9446 @table @asis
9447 @item @emph{Description}:
9448 Determines the @var{COUNT} of milliseconds of wall clock time since
9449 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
9450 @var{COUNT_RATE} determines the number of clock ticks per second.
9451 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
9452 @command{gfortran}.
9453
9454 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
9455 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
9456
9457 @item @emph{Standard}:
9458 F95 and later
9459
9460 @item @emph{Class}:
9461 Subroutine
9462
9463 @item @emph{Syntax}:
9464 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
9465
9466 @item @emph{Arguments}:
9467 @item @emph{Arguments}:
9468 @multitable @columnfractions .15 .70
9469 @item @var{COUNT}      @tab (Optional) shall be a scalar of type default
9470 @code{INTEGER} with @code{INTENT(OUT)}.
9471 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
9472 @code{INTEGER} with @code{INTENT(OUT)}.
9473 @item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type default
9474 @code{INTEGER} with @code{INTENT(OUT)}.
9475 @end multitable
9476
9477 @item @emph{Example}:
9478 @smallexample
9479 PROGRAM test_system_clock
9480   INTEGER :: count, count_rate, count_max
9481   CALL SYSTEM_CLOCK(count, count_rate, count_max)
9482   WRITE(*,*) count, count_rate, count_max
9483 END PROGRAM
9484 @end smallexample
9485
9486 @item @emph{See also}:
9487 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
9488 @end table
9489
9490
9491
9492 @node TAN
9493 @section @code{TAN} --- Tangent function
9494 @fnindex TAN
9495 @fnindex DTAN
9496 @cindex trigonometric function, tangent
9497 @cindex tangent
9498
9499 @table @asis
9500 @item @emph{Description}:
9501 @code{TAN(X)} computes the tangent of @var{X}.
9502
9503 @item @emph{Standard}:
9504 F77 and later
9505
9506 @item @emph{Class}:
9507 Elemental function
9508
9509 @item @emph{Syntax}:
9510 @code{RESULT = TAN(X)}
9511
9512 @item @emph{Arguments}:
9513 @multitable @columnfractions .15 .70
9514 @item @var{X} @tab The type shall be @code{REAL(*)}.
9515 @end multitable
9516
9517 @item @emph{Return value}:
9518 The return value is of type @code{REAL(*)}.  The kind type parameter is
9519 the same as @var{X}.
9520
9521 @item @emph{Example}:
9522 @smallexample
9523 program test_tan
9524   real(8) :: x = 0.165_8
9525   x = tan(x)
9526 end program test_tan
9527 @end smallexample
9528
9529 @item @emph{Specific names}:
9530 @multitable @columnfractions .20 .20 .20 .25
9531 @item Name            @tab Argument          @tab Return type       @tab Standard
9532 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F95 and later
9533 @end multitable
9534
9535 @item @emph{See also}:
9536 @ref{ATAN}
9537 @end table
9538
9539
9540
9541 @node TANH
9542 @section @code{TANH} --- Hyperbolic tangent function
9543 @fnindex TANH
9544 @fnindex DTANH
9545 @cindex hyperbolic tangent
9546 @cindex hyperbolic function, tangent
9547 @cindex tangent, hyperbolic
9548
9549 @table @asis
9550 @item @emph{Description}:
9551 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
9552
9553 @item @emph{Standard}:
9554 F77 and later
9555
9556 @item @emph{Class}:
9557 Elemental function
9558
9559 @item @emph{Syntax}:
9560 @code{X = TANH(X)}
9561
9562 @item @emph{Arguments}:
9563 @multitable @columnfractions .15 .70
9564 @item @var{X} @tab The type shall be @code{REAL(*)}.
9565 @end multitable
9566
9567 @item @emph{Return value}:
9568 The return value is of type @code{REAL(*)} and lies in the range
9569 @math{ - 1 \leq tanh(x) \leq 1 }.
9570
9571 @item @emph{Example}:
9572 @smallexample
9573 program test_tanh
9574   real(8) :: x = 2.1_8
9575   x = tanh(x)
9576 end program test_tanh
9577 @end smallexample
9578
9579 @item @emph{Specific names}:
9580 @multitable @columnfractions .20 .20 .20 .25
9581 @item Name            @tab Argument          @tab Return type       @tab Standard
9582 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F95 and later
9583 @end multitable
9584
9585 @item @emph{See also}:
9586 @ref{ATANH}
9587 @end table
9588
9589
9590
9591 @node TIME
9592 @section @code{TIME} --- Time function
9593 @fnindex TIME
9594 @cindex time, current
9595 @cindex current time
9596
9597 @table @asis
9598 @item @emph{Description}:
9599 Returns the current time encoded as an integer (in the manner of the
9600 UNIX function @code{time(3)}). This value is suitable for passing to
9601 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
9602
9603 This intrinsic is not fully portable, such as to systems with 32-bit
9604 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
9605 the values returned by this intrinsic might be, or become, negative, or
9606 numerically less than previous values, during a single run of the
9607 compiled program.
9608
9609 See @ref{TIME8}, for information on a similar intrinsic that might be
9610 portable to more GNU Fortran implementations, though to fewer Fortran
9611 compilers.
9612
9613 @item @emph{Standard}:
9614 GNU extension
9615
9616 @item @emph{Class}:
9617 Non-elemental function
9618
9619 @item @emph{Syntax}:
9620 @code{RESULT = TIME()}
9621
9622 @item @emph{Return value}:
9623 The return value is a scalar of type @code{INTEGER(4)}.
9624
9625 @item @emph{See also}:
9626 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
9627
9628 @end table
9629
9630
9631
9632 @node TIME8
9633 @section @code{TIME8} --- Time function (64-bit)
9634 @fnindex TIME8
9635 @cindex time, current
9636 @cindex current time
9637
9638 @table @asis
9639 @item @emph{Description}:
9640 Returns the current time encoded as an integer (in the manner of the
9641 UNIX function @code{time(3)}). This value is suitable for passing to
9642 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
9643
9644 @emph{Warning:} this intrinsic does not increase the range of the timing
9645 values over that returned by @code{time(3)}. On a system with a 32-bit
9646 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
9647 it is converted to a 64-bit @code{INTEGER(8)} value. That means
9648 overflows of the 32-bit value can still occur. Therefore, the values
9649 returned by this intrinsic might be or become negative or numerically
9650 less than previous values during a single run of the compiled program.
9651
9652 @item @emph{Standard}:
9653 GNU extension
9654
9655 @item @emph{Class}:
9656 Non-elemental function
9657
9658 @item @emph{Syntax}:
9659 @code{RESULT = TIME8()}
9660
9661 @item @emph{Return value}:
9662 The return value is a scalar of type @code{INTEGER(8)}.
9663
9664 @item @emph{See also}:
9665 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
9666
9667 @end table
9668
9669
9670
9671 @node TINY
9672 @section @code{TINY} --- Smallest positive number of a real kind
9673 @fnindex TINY
9674 @cindex limits, smallest number
9675 @cindex model representation, smallest number
9676
9677 @table @asis
9678 @item @emph{Description}:
9679 @code{TINY(X)} returns the smallest positive (non zero) number
9680 in the model of the type of @code{X}.
9681
9682 @item @emph{Standard}:
9683 F95 and later
9684
9685 @item @emph{Class}:
9686 Inquiry function
9687
9688 @item @emph{Syntax}:
9689 @code{RESULT = TINY(X)}
9690
9691 @item @emph{Arguments}:
9692 @multitable @columnfractions .15 .70
9693 @item @var{X} @tab Shall be of type @code{REAL}.
9694 @end multitable
9695
9696 @item @emph{Return value}:
9697 The return value is of the same type and kind as @var{X}
9698
9699 @item @emph{Example}:
9700 See @code{HUGE} for an example.
9701 @end table
9702
9703
9704
9705 @node TRANSFER
9706 @section @code{TRANSFER} --- Transfer bit patterns
9707 @fnindex TRANSFER
9708 @cindex bits, move
9709 @cindex type cast
9710
9711 @table @asis
9712 @item @emph{Description}:
9713 Interprets the bitwise representation of @var{SOURCE} in memory as if it
9714 is the representation of a variable or array of the same type and type
9715 parameters as @var{MOLD}.
9716
9717 This is approximately equivalent to the C concept of @emph{casting} one
9718 type to another.
9719
9720 @item @emph{Standard}:
9721 F95 and later
9722
9723 @item @emph{Class}:
9724 Transformational function
9725
9726 @item @emph{Syntax}:
9727 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
9728
9729 @item @emph{Arguments}:
9730 @multitable @columnfractions .15 .70
9731 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
9732 @item @var{MOLD}   @tab Shall be a scalar or an array of any type.
9733 @item @var{SIZE}   @tab (Optional) shall be a scalar of type
9734 @code{INTEGER}.
9735 @end multitable
9736
9737 @item @emph{Return value}:
9738 The result has the same type as @var{MOLD}, with the bit level
9739 representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
9740 a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
9741 but @var{MOLD} is an array (of any size or shape), the result is a one-
9742 dimensional array of the minimum length needed to contain the entirety
9743 of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
9744 and @var{MOLD} is a scalar, the result is a scalar.
9745
9746 If the bitwise representation of the result is longer than that of
9747 @var{SOURCE}, then the leading bits of the result correspond to those of
9748 @var{SOURCE} and any trailing bits are filled arbitrarily.
9749
9750 When the resulting bit representation does not correspond to a valid
9751 representation of a variable of the same type as @var{MOLD}, the results
9752 are undefined, and subsequent operations on the result cannot be
9753 guaranteed to produce sensible behavior.  For example, it is possible to
9754 create @code{LOGICAL} variables for which @code{@var{VAR}} and
9755 @code{.NOT.@var{VAR}} both appear to be true.
9756
9757 @item @emph{Example}:
9758 @smallexample
9759 PROGRAM test_transfer
9760   integer :: x = 2143289344
9761   print *, transfer(x, 1.0)    ! prints "NaN" on i686
9762 END PROGRAM
9763 @end smallexample
9764 @end table
9765
9766
9767
9768 @node TRANSPOSE
9769 @section @code{TRANSPOSE} --- Transpose an array of rank two
9770 @fnindex TRANSPOSE
9771 @cindex array, transpose
9772 @cindex matrix, transpose
9773 @cindex transpose
9774
9775 @table @asis
9776 @item @emph{Description}:
9777 Transpose an array of rank two. Element (i, j) of the result has the value
9778 @code{MATRIX(j, i)}, for all i, j.
9779
9780 @item @emph{Standard}:
9781 F95 and later
9782
9783 @item @emph{Class}:
9784 Transformational function
9785
9786 @item @emph{Syntax}:
9787 @code{RESULT = TRANSPOSE(MATRIX)}
9788
9789 @item @emph{Arguments}:
9790 @multitable @columnfractions .15 .70
9791 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
9792 @end multitable
9793
9794 @item @emph{Return value}:
9795 The result has the the same type as @var{MATRIX}, and has shape
9796 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
9797 @end table
9798
9799
9800
9801 @node TRIM
9802 @section @code{TRIM} --- Remove trailing blank characters of a string
9803 @fnindex TRIM
9804 @cindex string, remove trailing whitespace
9805
9806 @table @asis
9807 @item @emph{Description}:
9808 Removes trailing blank characters of a string.
9809
9810 @item @emph{Standard}:
9811 F95 and later
9812
9813 @item @emph{Class}:
9814 Transformational function
9815
9816 @item @emph{Syntax}:
9817 @code{RESULT = TRIM(STRING)}
9818
9819 @item @emph{Arguments}:
9820 @multitable @columnfractions .15 .70
9821 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
9822 @end multitable
9823
9824 @item @emph{Return value}:
9825 A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
9826 less the number of trailing blanks.
9827
9828 @item @emph{Example}:
9829 @smallexample
9830 PROGRAM test_trim
9831   CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
9832   WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
9833 END PROGRAM
9834 @end smallexample
9835
9836 @item @emph{See also}:
9837 @ref{ADJUSTL}, @ref{ADJUSTR}
9838 @end table
9839
9840
9841
9842 @node TTYNAM
9843 @section @code{TTYNAM} --- Get the name of a terminal device.
9844 @fnindex TTYNAM
9845 @cindex system, terminal
9846
9847 @table @asis
9848 @item @emph{Description}:
9849 Get the name of a terminal device. For more information,
9850 see @code{ttyname(3)}.
9851
9852 This intrinsic is provided in both subroutine and function forms;
9853 however, only one form can be used in any given program unit.
9854
9855 @item @emph{Standard}:
9856 GNU extension
9857
9858 @item @emph{Class}:
9859 Subroutine, non-elemental function
9860
9861 @item @emph{Syntax}:
9862 @multitable @columnfractions .80
9863 @item @code{CALL TTYNAM(UNIT, NAME)}
9864 @item @code{NAME = TTYNAM(UNIT)}
9865 @end multitable
9866
9867 @item @emph{Arguments}:
9868 @multitable @columnfractions .15 .70
9869 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
9870 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
9871 @end multitable
9872
9873 @item @emph{Example}:
9874 @smallexample
9875 PROGRAM test_ttynam
9876   INTEGER :: unit
9877   DO unit = 1, 10
9878     IF (isatty(unit=unit)) write(*,*) ttynam(unit)
9879   END DO
9880 END PROGRAM
9881 @end smallexample
9882
9883 @item @emph{See also}:
9884 @ref{ISATTY}
9885 @end table
9886
9887
9888
9889 @node UBOUND
9890 @section @code{UBOUND} --- Upper dimension bounds of an array
9891 @fnindex UBOUND
9892 @cindex array, upper bound
9893
9894 @table @asis
9895 @item @emph{Description}:
9896 Returns the upper bounds of an array, or a single upper bound
9897 along the @var{DIM} dimension.
9898 @item @emph{Standard}:
9899 F95 and later
9900
9901 @item @emph{Class}:
9902 Inquiry function
9903
9904 @item @emph{Syntax}:
9905 @code{RESULT = UBOUND(ARRAY [, DIM])}
9906
9907 @item @emph{Arguments}:
9908 @multitable @columnfractions .15 .70
9909 @item @var{ARRAY} @tab Shall be an array, of any type.
9910 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
9911 @end multitable
9912
9913 @item @emph{Return value}:
9914 If @var{DIM} is absent, the result is an array of the upper bounds of
9915 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
9916 corresponding to the upper bound of the array along that dimension.  If
9917 @var{ARRAY} is an expression rather than a whole array or array
9918 structure component, or if it has a zero extent along the relevant
9919 dimension, the upper bound is taken to be the number of elements along
9920 the relevant dimension.
9921
9922 @item @emph{See also}:
9923 @ref{LBOUND}
9924 @end table
9925
9926
9927
9928 @node UMASK
9929 @section @code{UMASK} --- Set the file creation mask
9930 @fnindex UMASK
9931 @cindex file system, file creation mask
9932
9933 @table @asis
9934 @item @emph{Description}:
9935 Sets the file creation mask to @var{MASK} and returns the old value in
9936 argument @var{OLD} if it is supplied. See @code{umask(2)}.
9937
9938 @item @emph{Standard}:
9939 GNU extension
9940
9941 @item @emph{Class}:
9942 Subroutine
9943
9944 @item @emph{Syntax}:
9945 @code{CALL UMASK(MASK [, OLD])}
9946
9947 @item @emph{Arguments}:
9948 @multitable @columnfractions .15 .70
9949 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
9950 @item @var{MASK} @tab (Optional) Shall be a scalar of type
9951                       @code{INTEGER(*)}.
9952 @end multitable
9953
9954 @end table
9955
9956
9957
9958 @node UNLINK
9959 @section @code{UNLINK} --- Remove a file from the file system
9960 @fnindex UNLINK
9961 @cindex file system, remove file
9962
9963 @table @asis
9964 @item @emph{Description}:
9965 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
9966 used to mark the end of the name in @var{PATH}; otherwise, trailing
9967 blanks in the file name are ignored.  If the @var{STATUS} argument is
9968 supplied, it contains 0 on success or a nonzero error code upon return;
9969 see @code{unlink(2)}.
9970
9971 This intrinsic is provided in both subroutine and function forms;
9972 however, only one form can be used in any given program unit.
9973
9974 @item @emph{Standard}:
9975 GNU extension
9976
9977 @item @emph{Class}:
9978 Subroutine, non-elemental function
9979
9980 @item @emph{Syntax}:
9981 @multitable @columnfractions .80
9982 @item @code{CALL UNLINK(PATH [, STATUS])}
9983 @item @code{STATUS = UNLINK(PATH)}
9984 @end multitable
9985
9986 @item @emph{Arguments}:
9987 @multitable @columnfractions .15 .70
9988 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
9989 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9990 @end multitable
9991
9992 @item @emph{See also}:
9993 @ref{LINK}, @ref{SYMLNK}
9994 @end table
9995
9996
9997
9998 @node UNPACK
9999 @section @code{UNPACK} --- Unpack an array of rank one into an array
10000 @fnindex UNPACK
10001 @cindex array, unpacking
10002 @cindex array, increase dimension
10003 @cindex array, scatter elements
10004
10005 @table @asis
10006 @item @emph{Description}:
10007 Store the elements of @var{VECTOR} in an array of higher rank.
10008
10009 @item @emph{Standard}:
10010 F95 and later
10011
10012 @item @emph{Class}:
10013 Transformational function
10014
10015 @item @emph{Syntax}:
10016 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10017
10018 @item @emph{Arguments}:
10019 @multitable @columnfractions .15 .70
10020 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10021 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10022 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
10023 @item @var{FIELD}  @tab Shall be of the sam type as @var{VECTOR} and have
10024 the same shape as @var{MASK}.
10025 @end multitable
10026
10027 @item @emph{Return value}:
10028 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10029 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10030
10031 @item @emph{Example}:
10032 @smallexample
10033 PROGRAM test_unpack
10034   integer :: vector(2)  = (/1,1/)
10035   logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10036   integer :: field(2,2) = 0, unity(2,2)
10037
10038   ! result: unity matrix
10039   unity = unpack(vector, reshape(mask, (/2,2/)), field)
10040 END PROGRAM
10041 @end smallexample
10042
10043 @item @emph{See also}:
10044 @ref{PACK}, @ref{SPREAD}
10045 @end table
10046
10047
10048
10049 @node VERIFY
10050 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10051 @fnindex VERIFY
10052 @cindex string, find missing set
10053
10054 @table @asis
10055 @item @emph{Description}:
10056 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10057
10058 If @var{BACK} is either absent or equals @code{FALSE}, this function
10059 returns the position of the leftmost character of @var{STRING} that is
10060 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10061 is returned. If all characters of @var{SET} are found in @var{STRING}, the
10062 result is zero.
10063
10064 @item @emph{Standard}:
10065 F95 and later
10066
10067 @item @emph{Class}:
10068 Elemental function
10069
10070 @item @emph{Syntax}:
10071 @code{RESULT = VERFIY(STRING, SET[, BACK])}
10072
10073 @item @emph{Arguments}:
10074 @multitable @columnfractions .15 .70
10075 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
10076 @item @var{SET}    @tab Shall be of type @code{CHARACTER(*)}.
10077 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
10078 @end multitable
10079
10080 @item @emph{Return value}:
10081 The return value is of type @code{INTEGER} and of the default
10082 integer kind.
10083
10084 @item @emph{Example}:
10085 @smallexample
10086 PROGRAM test_verify
10087   WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
10088   WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
10089   WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
10090   WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
10091   WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
10092 END PROGRAM
10093 @end smallexample
10094
10095 @item @emph{See also}:
10096 @ref{SCAN}, @ref{INDEX}
10097 @end table
10098
10099
10100
10101 @node XOR
10102 @section @code{XOR} --- Bitwise logical exclusive OR
10103 @fnindex XOR
10104 @cindex bitwise logical exclusive or
10105 @cindex logical exclusive or, bitwise
10106
10107 @table @asis
10108 @item @emph{Description}:
10109 Bitwise logical exclusive or.
10110
10111 This intrinsic routine is provided for backwards compatibility with
10112 GNU Fortran 77.  For integer arguments, programmers should consider
10113 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
10114
10115 @item @emph{Standard}:
10116 GNU extension
10117
10118 @item @emph{Class}:
10119 Non-elemental function
10120
10121 @item @emph{Syntax}:
10122 @code{RESULT = XOR(X, Y)}
10123
10124 @item @emph{Arguments}:
10125 @multitable @columnfractions .15 .70
10126 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10127 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10128 @end multitable
10129
10130 @item @emph{Return value}:
10131 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
10132 after cross-promotion of the arguments.
10133
10134 @item @emph{Example}:
10135 @smallexample
10136 PROGRAM test_xor
10137   LOGICAL :: T = .TRUE., F = .FALSE.
10138   INTEGER :: a, b
10139   DATA a / Z'F' /, b / Z'3' /
10140
10141   WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
10142   WRITE (*,*) XOR(a, b)
10143 END PROGRAM
10144 @end smallexample
10145
10146 @item @emph{See also}:
10147 F95 elemental function: @ref{IEOR}
10148 @end table
10149
10150