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