gcc/fortran/intrinsic.texi

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