gcc/fortran/intrinsic.texi

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