gcc/fortran/intrinsic.texi

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