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 This portion of the document is incomplete and undergoing massive expansion
  42 and editing.  All contributions and corrections are strongly encouraged.
  43
  44 Implemented intrinsics are fully functional and available to the user to apply.
  45 Some intrinsics have documentation yet to be completed as indicated by 'documentation pending'.
  46
  47 @comment Missing intrinsics (double check with #19292)
  48 @comment  - MClock
  49 @comment  - Short
  50
  51 @menu
  52 * Introduction:         Introduction to Intrinsics
  53 * @code{ABORT}:         ABORT,     Abort the program
  54 * @code{ABS}:           ABS,       Absolute value
  55 * @code{ACCESS}:        ACCESS,    Checks file access modes
  56 * @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
  57 * @code{ACOS}:          ACOS,      Arccosine function
  58 * @code{ACOSH}:         ACOSH,     Hyperbolic arccosine function
  59 * @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
  60 * @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
  61 * @code{AIMAG}:         AIMAG,     Imaginary part of complex number
  62 * @code{AINT}:          AINT,      Truncate to a whole number
  63 * @code{ALARM}:         ALARM,     Set an alarm clock
  64 * @code{ALL}:           ALL,       Determine if all values are true
  65 * @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
  66 * @code{AND}:           AND,       Bitwise logical AND
  67 * @code{ANINT}:         ANINT,     Nearest whole number
  68 * @code{ANY}:           ANY,       Determine if any values are true
  69 * @code{ASIN}:          ASIN,      Arcsine function
  70 * @code{ASINH}:         ASINH,     Hyperbolic arcsine function
  71 * @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
  72 * @code{ATAN}:          ATAN,      Arctangent function
  73 * @code{ATAN2}:         ATAN2,     Arctangent function
  74 * @code{ATANH}:         ATANH,     Hyperbolic arctangent function
  75 * @code{BESJ0}:         BESJ0,     Bessel function of the first kind of order 0
  76 * @code{BESJ1}:         BESJ1,     Bessel function of the first kind of order 1
  77 * @code{BESJN}:         BESJN,     Bessel function of the first kind
  78 * @code{BESY0}:         BESY0,     Bessel function of the second kind of order 0
  79 * @code{BESY1}:         BESY1,     Bessel function of the second kind of order 1
  80 * @code{BESYN}:         BESYN,     Bessel function of the second kind
  81 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
  82 * @code{BTEST}:         BTEST,     Bit test function
  83 * @code{CEILING}:       CEILING,   Integer ceiling function
  84 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
  85 * @code{CHDIR}:         CHDIR,     Change working directory
  86 * @code{CHMOD}:         CHMOD,     Change access permissions of files
  87 * @code{CMPLX}:         CMPLX,     Complex conversion function
  88 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
  89 * @code{CONJG}:         CONJG,     Complex conjugate function
  90 * @code{COS}:           COS,       Cosine function
  91 * @code{COSH}:          COSH,      Hyperbolic cosine function
  92 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
  93 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
  94 * @code{CSHIFT}:        CSHIFT,    Circular array shift function
  95 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
  96 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
  97 * @code{DBLE}:          DBLE,      Double precision conversion function
  98 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
  99 * @code{DFLOAT}:        DFLOAT,    Double precision conversion function
 100 * @code{DIGITS}:        DIGITS,    Significant digits function
 101 * @code{DIM}:           DIM,       Dim function
 102 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
 103 * @code{DPROD}:         DPROD,     Double product function
 104 * @code{DREAL}:         DREAL,     Double real part function
 105 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
 106 * @code{EOSHIFT}:       EOSHIFT,   End-off shift function
 107 * @code{EPSILON}:       EPSILON,   Epsilon function
 108 * @code{ERF}:           ERF,       Error function
 109 * @code{ERFC}:          ERFC,      Complementary error function
 110 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
 111 * @code{EXIT}:          EXIT,      Exit the program with status.
 112 * @code{EXP}:           EXP,       Exponential function
 113 * @code{EXPONENT}:      EXPONENT,  Exponent function
 114 * @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
 115 * @code{FGET}:          FGET,      Read a single character in stream mode from stdin
 116 * @code{FGETC}:         FGETC,     Read a single character in stream mode
 117 * @code{FLOAT}:         FLOAT,     Convert integer to default real
 118 * @code{FLOOR}:         FLOOR,     Integer floor function
 119 * @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
 120 * @code{FNUM}:          FNUM,      File number function
 121 * @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
 122 * @code{FPUTC}:         FPUTC,     Write a single character in stream mode
 123 * @code{FRACTION}:      FRACTION,  Fractional part of the model representation
 124 * @code{FREE}:          FREE,      Memory de-allocation subroutine
 125 * @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
 126 * @code{FSTAT}:         FSTAT,     Get file status
 127 * @code{FTELL}:         FTELL,     Current stream position
 128 * @code{GETARG}:        GETARG,    Get command line arguments
 129 * @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
 130 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
 131 * @code{GETCWD}:        GETCWD,    Get current working directory
 132 * @code{GETENV}:        GETENV,    Get an environmental variable
 133 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
 134 * @code{GETGID}:        GETGID,    Group ID function
 135 * @code{GETLOG}:        GETLOG,    Get login name
 136 * @code{GETPID}:        GETPID,    Process ID function
 137 * @code{GETUID}:        GETUID,    User ID function
 138 * @code{GMTIME}:        GMTIME,    Convert time to GMT info
 139 * @code{HOSTNM}:        HOSTNM,    Get system host name
 140 * @code{HUGE}:          HUGE,      Largest number of a kind
 141 * @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
 142 * @code{IAND}:          IAND,      Bitwise logical and
 143 * @code{IARGC}:         IARGC,     Get the number of command line arguments
 144 * @code{IBCLR}:         IBCLR,     Clear bit
 145 * @code{IBITS}:         IBITS,     Bit extraction
 146 * @code{IBSET}:         IBSET,     Set bit
 147 * @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
 148 * @code{IDATE}:         IDATE,     Current local time (day/month/year)
 149 * @code{IEOR}:          IEOR,      Bitwise logical exclusive or
 150 * @code{IERRNO}:        IERRNO,    Function to get the last system error number
 151 * @code{INDEX}:         INDEX,     Position of a substring within a string
 152 * @code{INT}:           INT,       Convert to integer type
 153 * @code{IOR}:           IOR,       Bitwise logical or
 154 * @code{IRAND}:         IRAND,     Integer pseudo-random number
 155 * @code{ISHFT}:         ISHFT,     Shift bits
 156 * @code{ISHFTC}:        ISHFTC,    Shift bits circularly
 157 * @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
 158 * @code{KILL}:          KILL,      Send a signal to a process
 159 * @code{KIND}:          KIND,      Kind of an entity
 160 * @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
 161 * @code{LEN}:           LEN,       Length of a character entity
 162 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
 163 * @code{LGE}:           LGE,       Lexical greater than or equal
 164 * @code{LGT}:           LGT,       Lexical greater than
 165 * @code{LINK}:          LINK,      Create a hard link
 166 * @code{LLE}:           LLE,       Lexical less than or equal
 167 * @code{LLT}:           LLT,       Lexical less than
 168 * @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
 169 * @code{LOC}:           LOC,       Returns the address of a variable
 170 * @code{LOG}:           LOG,       Logarithm function
 171 * @code{LOG10}:         LOG10,     Base 10 logarithm function
 172 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
 173 * @code{LSHIFT}:        LSHIFT,    Left shift bits
 174 * @code{LSTAT}:         LSTAT,     Get file status
 175 * @code{LTIME}:         LTIME,     Convert time to local time info
 176 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
 177 * @code{MATMUL}:        MATMUL,    matrix multiplication
 178 * @code{MAX}:           MAX,       Maximum value of an argument list
 179 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
 180 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
 181 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
 182 * @code{MERGE}:         MERGE,     Merge arrays
 183 * @code{MIN}:           MIN,       Minimum value of an argument list
 184 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
 185 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
 186 * @code{MINVAL}:        MINVAL,    Minimum value of an array
 187 * @code{MOD}:           MOD,       Remainder function
 188 * @code{MODULO}:        MODULO,    Modulo function
 189 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
 190 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
 191 * @code{NEAREST}:       NEAREST,   Nearest representable number
 192 * @code{NEW_LINE}:      NEW_LINE,  New line character
 193 * @code{NINT}:          NINT,      Nearest whole number
 194 * @code{NOT}:           NOT,       Logical negation
 195 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
 196 * @code{OR}:            OR,        Bitwise logical OR
 197 * @code{PACK}:          PACK,      Pack an array into an array of rank one
 198 * @code{PERROR}:        PERROR,    Print system error message
 199 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
 200 * @code{PRESENT}:       PRESENT,   Determine whether an optional argument is specified
 201 * @code{PRODUCT}:       PRODUCT,   Product of array elements
 202 * @code{RADIX}:         RADIX,     Base of a data model
 203 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
 204 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
 205 * @code{RAND}:          RAND,      Real pseudo-random number
 206 * @code{RANGE}:         RANGE,     Decimal exponent range of a real kind
 207 * @code{RAN}:           RAN,       Real pseudo-random number
 208 * @code{REAL}:          REAL,      Convert to real type
 209 * @code{RENAME}:        RENAME,    Rename a file
 210 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
 211 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
 212 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
 213 * @code{RSHIFT}:        RSHIFT,    Right shift bits
 214 * @code{SCALE}:         SCALE,     Scale a real value
 215 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
 216 * @code{SECNDS}:        SECNDS,    Time function
 217 @comment * @code{SECOND}:        SECOND,    (?)
 218 @comment * @code{SECONDS}:       SECONDS,   (?)
 219 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
 220 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
 221 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
 222 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
 223 * @code{SIGN}:          SIGN,      Sign copying function
 224 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
 225 * @code{SIN}:           SIN,       Sine function
 226 * @code{SINH}:          SINH,      Hyperbolic sine function
 227 * @code{SIZE}:          SIZE,      Function to determine the size of an array
 228 * @code{SNGL}:          SNGL,      Convert double precision real to default real
 229 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
 230 * @code{SPREAD}:        SPREAD,    Add a dimension to an array
 231 * @code{SQRT}:          SQRT,      Square-root function
 232 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
 233 * @code{STAT}:          STAT,      Get file status
 234 * @code{SUM}:           SUM,       Sum of array elements
 235 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
 236 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
 237 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
 238 * @code{TAN}:           TAN,       Tangent function
 239 * @code{TANH}:          TANH,      Hyperbolic tangent function
 240 * @code{TIME}:          TIME,      Time function
 241 * @code{TIME8}:         TIME8,     Time function (64-bit)
 242 * @code{TINY}:          TINY,      Smallest positive number of a real kind
 243 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
 244 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
 245 * @code{TRIM}:          TRIM,      Function to remove trailing blank characters of a string
 246 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
 247 * @code{UMASK}:         UMASK,     Set the file creation mask
 248 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
 249 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
 250 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
 251 * @code{XOR}:           XOR,       Bitwise logical exclusive or
 252 @end menu
 253
 254 @node Introduction to Intrinsics
 255 @section Introduction to intrinsic procedures
 256
 257 The intrinsic procedures provided by GNU Fortran include all of the
 258 intrinsic procedures required by the Fortran 95 standard, a set of
 259 intrinsic procedures for backwards compatibility with G77, and a small
 260 selection of intrinsic procedures from the Fortran 2003 standard.  Any
 261 conflict between a description here and a description in either the
 262 Fortran 95 standard or the Fortran 2003 standard is unintentional, and
 263 the standard(s) should be considered authoritative.
 264
 265 The enumeration of the @code{KIND} type parameter is processor defined in
 266 the Fortran 95 standard.  GNU Fortran defines the default integer type and
 267 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 268 respectively.  The standard mandates that both data types shall have
 269 another kind, which have more precision.  On typical target architectures
 270 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 271 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 272 In the description of generic intrinsic procedures, the kind type parameter
 273 will be specified by @code{KIND=*}, and in the description of specific
 274 names for an intrinsic procedure the kind type parameter will be explicitly
 275 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
 276 brevity the optional @code{KIND=} syntax will be omitted.
 277
 278 Many of the intrinsic procedures take one or more optional arguments.
 279 This document follows the convention used in the Fortran 95 standard,
 280 and denotes such arguments by square brackets.
 281
 282 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
 283 which can be used to restrict the set of intrinsic procedures to a
 284 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
 285 option, and so all intrinsic procedures described here are accepted.  There
 286 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 287 implemented both a function and a subroutine.  Both classes
 288 have been implemented in @command{gfortran} for backwards compatibility
 289 with @command{g77}.  It is noted here that these functions and subroutines
 290 cannot be intermixed in a given subprogram.  In the descriptions that follow,
 291 the applicable standard for each intrinsic procedure is noted.
 292
 293
 294
 295 @node ABORT
 296 @section @code{ABORT} --- Abort the program
 297 @cindex @code{ABORT} intrinsic
 298 @cindex abort
 299
 300 @table @asis
 301 @item @emph{Description}:
 302 @code{ABORT} causes immediate termination of the program.  On operating
 303 systems that support a core dump, @code{ABORT} will produce a core dump,
 304 which is suitable for debugging purposes.
 305
 306 @item @emph{Standard}:
 307 GNU extension
 308
 309 @item @emph{Class}:
 310 non-elemental subroutine
 311
 312 @item @emph{Syntax}:
 313 @code{CALL ABORT}
 314
 315 @item @emph{Return value}:
 316 Does not return.
 317
 318 @item @emph{Example}:
 319 @smallexample
 320 program test_abort
 321   integer :: i = 1, j = 2
 322   if (i /= j) call abort
 323 end program test_abort
 324 @end smallexample
 325
 326 @item @emph{See also}:
 327 @ref{EXIT}, @ref{KILL}
 328
 329 @end table
 330
 331
 332 @node ABS
 333 @section @code{ABS} --- Absolute value
 334 @cindex @code{ABS} intrinsic
 335 @cindex @code{CABS} intrinsic
 336 @cindex @code{DABS} intrinsic
 337 @cindex @code{IABS} intrinsic
 338 @cindex @code{ZABS} intrinsic
 339 @cindex @code{CDABS} intrinsic
 340 @cindex absolute value
 341
 342 @table @asis
 343 @item @emph{Description}:
 344 @code{ABS(X)} computes the absolute value of @code{X}.
 345
 346 @item @emph{Standard}:
 347 F77 and later, has overloads that are GNU extensions
 348
 349 @item @emph{Class}:
 350 Elemental function
 351
 352 @item @emph{Syntax}:
 353 @code{RESULT = ABS(X)}
 354
 355 @item @emph{Arguments}:
 356 @multitable @columnfractions .15 .80
 357 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
 358 @code{REAL(*)}, or @code{COMPLEX(*)}.
 359 @end multitable
 360
 361 @item @emph{Return value}:
 362 The return value is of the same type and
 363 kind as the argument except the return value is @code{REAL(*)} for a
 364 @code{COMPLEX(*)} argument.
 365
 366 @item @emph{Example}:
 367 @smallexample
 368 program test_abs
 369   integer :: i = -1
 370   real :: x = -1.e0
 371   complex :: z = (-1.e0,0.e0)
 372   i = abs(i)
 373   x = abs(x)
 374   x = abs(z)
 375 end program test_abs
 376 @end smallexample
 377
 378 @item @emph{Specific names}:
 379 @multitable @columnfractions .20 .20 .20 .40
 380 @item Name            @tab Argument            @tab Return type       @tab Standard
 381 @item @code{CABS(Z)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab F77 and later
 382 @item @code{DABS(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}    @tab F77 and later
 383 @item @code{IABS(I)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
 384 @item @code{ZABS(Z)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
 385 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
 386 @end multitable
 387 @end table
 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 .80
 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 accessable 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 @node ACHAR
 448 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
 449 @cindex @code{ACHAR} intrinsic
 450 @cindex @acronym{ASCII} collating sequence
 451
 452 @table @asis
 453 @item @emph{Description}:
 454 @code{ACHAR(I)} returns the character located at position @code{I}
 455 in the @acronym{ASCII} collating sequence.
 456
 457 @item @emph{Standard}:
 458 F77 and later
 459
 460 @item @emph{Class}:
 461 Elemental function
 462
 463 @item @emph{Syntax}:
 464 @code{RESULT = ACHAR(I)}
 465
 466 @item @emph{Arguments}:
 467 @multitable @columnfractions .15 .80
 468 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
 469 @end multitable
 470
 471 @item @emph{Return value}:
 472 The return value is of type @code{CHARACTER} with a length of one.  The
 473 kind type parameter is the same as  @code{KIND('A')}.
 474
 475 @item @emph{Example}:
 476 @smallexample
 477 program test_achar
 478   character c
 479   c = achar(32)
 480 end program test_achar
 481 @end smallexample
 482
 483 @item @emph{See also}:
 484 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
 485
 486 @end table
 487
 488
 489
 490 @node ACOS
 491 @section @code{ACOS} --- Arccosine function
 492 @cindex @code{ACOS} intrinsic
 493 @cindex @code{DACOS} intrinsic
 494 @cindex trigonometric functions (inverse)
 495
 496 @table @asis
 497 @item @emph{Description}:
 498 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
 499
 500 @item @emph{Standard}:
 501 F77 and later
 502
 503 @item @emph{Class}:
 504 Elemental function
 505
 506 @item @emph{Syntax}:
 507 @code{RESULT = ACOS(X)}
 508
 509 @item @emph{Arguments}:
 510 @multitable @columnfractions .15 .80
 511 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
 512 less than one.
 513 @end multitable
 514
 515 @item @emph{Return value}:
 516 The return value is of type @code{REAL(*)} and it lies in the
 517 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter
 518 is the same as @var{X}.
 519
 520 @item @emph{Example}:
 521 @smallexample
 522 program test_acos
 523   real(8) :: x = 0.866_8
 524   x = acos(x)
 525 end program test_acos
 526 @end smallexample
 527
 528 @item @emph{Specific names}:
 529 @multitable @columnfractions .20 .20 .20 .40
 530 @item Name            @tab Argument          @tab Return type       @tab Standard
 531 @item @code{DACOS(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F77 and later
 532 @end multitable
 533
 534 @item @emph{See also}:
 535 Inverse function: @ref{COS}
 536
 537 @end table
 538
 539
 540 @node ACOSH
 541 @section @code{ACOSH} --- Hyperbolic arccosine function
 542 @cindex @code{ACOSH} intrinsic
 543 @cindex hyperbolic arccosine
 544 @cindex hyperbolic cosine (inverse)
 545
 546 @table @asis
 547 @item @emph{Description}:
 548 @code{ACOSH(X)} computes the area hyperbolic cosine of @var{X} (inverse of @code{COSH(X)}).
 549
 550 @item @emph{Standard}:
 551 GNU extension
 552
 553 @item @emph{Class}:
 554 Elemental function
 555
 556 @item @emph{Syntax}:
 557 @code{RESULT = ACOSH(X)}
 558
 559 @item @emph{Arguments}:
 560 @multitable @columnfractions .15 .80
 561 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
 562 greater or equal to one.
 563 @end multitable
 564
 565 @item @emph{Return value}:
 566 The return value is of type @code{REAL(*)} and it lies in the
 567 range @math{0 \leq \acosh (x) \leq \infty}.
 568
 569 @item @emph{Example}:
 570 @smallexample
 571 PROGRAM test_acosh
 572   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
 573   WRITE (*,*) ACOSH(x)
 574 END PROGRAM
 575 @end smallexample
 576
 577 @item @emph{See also}:
 578 Inverse function: @ref{COSH}
 579 @end table
 580
 581
 582
 583 @node ADJUSTL
 584 @section @code{ADJUSTL} --- Left adjust a string
 585 @cindex @code{ADJUSTL} intrinsic
 586 @cindex adjust string
 587
 588 @table @asis
 589 @item @emph{Description}:
 590 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
 591 Spaces are inserted at the end of the string as needed.
 592
 593 @item @emph{Standard}:
 594 F95 and later
 595
 596 @item @emph{Class}:
 597 Elemental function
 598
 599 @item @emph{Syntax}:
 600 @code{RESULT = ADJUSTL(STR)}
 601
 602 @item @emph{Arguments}:
 603 @multitable @columnfractions .15 .80
 604 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 605 @end multitable
 606
 607 @item @emph{Return value}:
 608 The return value is of type @code{CHARACTER} where leading spaces
 609 are removed and the same number of spaces are inserted on the end
 610 of @var{STR}.
 611
 612 @item @emph{Example}:
 613 @smallexample
 614 program test_adjustl
 615   character(len=20) :: str = '   gfortran'
 616   str = adjustl(str)
 617   print *, str
 618 end program test_adjustl
 619 @end smallexample
 620 @end table
 621
 622
 623
 624 @node ADJUSTR
 625 @section @code{ADJUSTR} --- Right adjust a string
 626 @cindex @code{ADJUSTR} intrinsic
 627 @cindex adjust string
 628
 629 @table @asis
 630 @item @emph{Description}:
 631 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
 632 Spaces are inserted at the start of the string as needed.
 633
 634 @item @emph{Standard}:
 635 F95 and later
 636
 637 @item @emph{Class}:
 638 Elemental function
 639
 640 @item @emph{Syntax}:
 641 @code{RESULT = ADJUSTR(STR)}
 642
 643 @item @emph{Arguments}:
 644 @multitable @columnfractions .15 .80
 645 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 646 @end multitable
 647
 648 @item @emph{Return value}:
 649 The return value is of type @code{CHARACTER} where trailing spaces
 650 are removed and the same number of spaces are inserted at the start
 651 of @var{STR}.
 652
 653 @item @emph{Example}:
 654 @smallexample
 655 program test_adjustr
 656   character(len=20) :: str = 'gfortran'
 657   str = adjustr(str)
 658   print *, str
 659 end program test_adjustr
 660 @end smallexample
 661 @end table
 662
 663
 664
 665 @node AIMAG
 666 @section @code{AIMAG} --- Imaginary part of complex number
 667 @cindex @code{AIMAG} intrinsic
 668 @cindex @code{DIMAG} intrinsic
 669 @cindex @code{IMAG} intrinsic
 670 @cindex @code{IMAGPART} intrinsic
 671 @cindex imaginary part of a complex number
 672
 673 @table @asis
 674 @item @emph{Description}:
 675 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
 676 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
 677 for compatibility with @command{g77}, and their use in new code is
 678 strongly discouraged.
 679
 680 @item @emph{Standard}:
 681 F77 and later, has overloads that are GNU extensions
 682
 683 @item @emph{Class}:
 684 Elemental function
 685
 686 @item @emph{Syntax}:
 687 @code{RESULT = AIMAG(Z)}
 688
 689 @item @emph{Arguments}:
 690 @multitable @columnfractions .15 .80
 691 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
 692 @end multitable
 693
 694 @item @emph{Return value}:
 695 The return value is of type real with the
 696 kind type parameter of the argument.
 697
 698 @item @emph{Example}:
 699 @smallexample
 700 program test_aimag
 701   complex(4) z4
 702   complex(8) z8
 703   z4 = cmplx(1.e0_4, 0.e0_4)
 704   z8 = cmplx(0.e0_8, 1.e0_8)
 705   print *, aimag(z4), dimag(z8)
 706 end program test_aimag
 707 @end smallexample
 708
 709 @item @emph{Specific names}:
 710 @multitable @columnfractions .20 .20 .20 .40
 711 @item Name            @tab Argument            @tab Return type       @tab Standard
 712 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}    @tab GNU extension
 713 @item @code{IMAG(Z)}  @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)}    @tab GNU extension
 714 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
 715 @end multitable
 716 @end table
 717
 718
 719
 720 @node AINT
 721 @section @code{AINT} --- Truncate to a whole number
 722 @cindex @code{AINT} intrinsic
 723 @cindex @code{DINT} intrinsic
 724 @cindex whole number
 725
 726 @table @asis
 727 @item @emph{Description}:
 728 @code{AINT(X [, KIND])} truncates its argument to a whole number.
 729
 730 @item @emph{Standard}:
 731 F77 and later
 732
 733 @item @emph{Class}:
 734 Elemental function
 735
 736 @item @emph{Syntax}:
 737 @code{RESULT = AINT(X [, KIND])}
 738
 739 @item @emph{Arguments}:
 740 @multitable @columnfractions .15 .80
 741 @item @var{X}    @tab The type of the argument shall be @code{REAL(*)}.
 742 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
 743                       expression indicating the kind parameter of
 744                       the result.
 745 @end multitable
 746
 747 @item @emph{Return value}:
 748 The return value is of type real with the kind type parameter of the
 749 argument if the optional @var{KIND} is absent; otherwise, the kind
 750 type parameter will be given by @var{KIND}.  If the magnitude of
 751 @var{X} is less than one, then @code{AINT(X)} returns zero.  If the
 752 magnitude is equal to or greater than one, then it returns the largest
 753 whole number that does not exceed its magnitude.  The sign is the same
 754 as the sign of @var{X}.
 755
 756 @item @emph{Example}:
 757 @smallexample
 758 program test_aint
 759   real(4) x4
 760   real(8) x8
 761   x4 = 1.234E0_4
 762   x8 = 4.321_8
 763   print *, aint(x4), dint(x8)
 764   x8 = aint(x4,8)
 765 end program test_aint
 766 @end smallexample
 767
 768 @item @emph{Specific names}:
 769 @multitable @columnfractions .20 .20 .20 .40
 770 @item Name           @tab Argument         @tab Return type      @tab Standard
 771 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab F77 and later
 772 @end multitable
 773 @end table
 774
 775
 776
 777 @node ALARM
 778 @section @code{ALARM} --- Execute a routine after a given delay
 779 @cindex @code{ALARM} intrinsic
 780
 781 @table @asis
 782 @item @emph{Description}:
 783 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
 784 to be executed after a delay of @var{SECONDS} by using @code{alarm(1)} to
 785 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
 786 supplied, it will be returned with the number of seconds remaining until
 787 any previously scheduled alarm was due to be delivered, or zero if there
 788 was no previously scheduled alarm.
 789
 790 @item @emph{Standard}:
 791 GNU extension
 792
 793 @item @emph{Class}:
 794 Subroutine
 795
 796 @item @emph{Syntax}:
 797 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
 798
 799 @item @emph{Arguments}:
 800 @multitable @columnfractions .15 .80
 801 @item @var{SECONDS} @tab The type of the argument shall be a scalar
 802 @code{INTEGER}. It is @code{INTENT(IN)}.
 803 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
 804 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
 805 @code{INTEGER}. It is @code{INTENT(IN)}.
 806 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
 807 @code{INTEGER} variable. It is @code{INTENT(OUT)}.
 808 @end multitable
 809
 810 @item @emph{Example}:
 811 @smallexample
 812 program test_alarm
 813   external handler_print
 814   integer i
 815   call alarm (3, handler_print, i)
 816   print *, i
 817   call sleep(10)
 818 end program test_alarm
 819 @end smallexample
 820 This will cause the external routine @var{handler_print} to be called
 821 after 3 seconds.
 822 @end table
 823
 824
 825
 826 @node ALL
 827 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
 828 @cindex @code{ALL} intrinsic
 829 @cindex true values
 830
 831 @table @asis
 832 @item @emph{Description}:
 833 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
 834 in the array along dimension @var{DIM}.
 835
 836 @item @emph{Standard}:
 837 F95 and later
 838
 839 @item @emph{Class}:
 840 transformational function
 841
 842 @item @emph{Syntax}:
 843 @code{RESULT = ALL(MASK [, DIM])}
 844
 845 @item @emph{Arguments}:
 846 @multitable @columnfractions .15 .80
 847 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
 848 it shall not be scalar.
 849 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
 850 with a value that lies between one and the rank of @var{MASK}.
 851 @end multitable
 852
 853 @item @emph{Return value}:
 854 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
 855 the kind type parameter is the same as the kind type parameter of
 856 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
 857 an array with the rank of @var{MASK} minus 1.  The shape is determined from
 858 the shape of @var{MASK} where the @var{DIM} dimension is elided.
 859
 860 @table @asis
 861 @item (A)
 862 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
 863 It also is true if @var{MASK} has zero size; otherwise, it is false.
 864 @item (B)
 865 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
 866 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
 867 is determined by applying @code{ALL} to the array sections.
 868 @end table
 869
 870 @item @emph{Example}:
 871 @smallexample
 872 program test_all
 873   logical l
 874   l = all((/.true., .true., .true./))
 875   print *, l
 876   call section
 877   contains
 878     subroutine section
 879       integer a(2,3), b(2,3)
 880       a = 1
 881       b = 1
 882       b(2,2) = 2
 883       print *, all(a .eq. b, 1)
 884       print *, all(a .eq. b, 2)
 885     end subroutine section
 886 end program test_all
 887 @end smallexample
 888 @end table
 889
 890
 891
 892 @node ALLOCATED
 893 @section @code{ALLOCATED} --- Status of an allocatable entity
 894 @cindex @code{ALLOCATED} intrinsic
 895 @cindex allocation status
 896
 897 @table @asis
 898 @item @emph{Description}:
 899 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
 900
 901 @item @emph{Standard}:
 902 F95 and later
 903
 904 @item @emph{Class}:
 905 Inquiry function
 906
 907 @item @emph{Syntax}:
 908 @code{RESULT = ALLOCATED(X)}
 909
 910 @item @emph{Arguments}:
 911 @multitable @columnfractions .15 .80
 912 @item @var{X}    @tab The argument shall be an @code{ALLOCATABLE} array.
 913 @end multitable
 914
 915 @item @emph{Return value}:
 916 The return value is a scalar @code{LOGICAL} with the default logical
 917 kind type parameter.  If @var{X} is allocated, @code{ALLOCATED(X)}
 918 is @code{.TRUE.}; otherwise, it returns the @code{.TRUE.}
 919
 920 @item @emph{Example}:
 921 @smallexample
 922 program test_allocated
 923   integer :: i = 4
 924   real(4), allocatable :: x(:)
 925   if (allocated(x) .eqv. .false.) allocate(x(i))
 926 end program test_allocated
 927 @end smallexample
 928 @end table
 929
 930
 931 @node AND
 932 @section @code{AND} --- Bitwise logical AND
 933 @cindex @code{AND} intrinsic
 934 @cindex bit operations
 935
 936 @table @asis
 937 @item @emph{Description}:
 938 Bitwise logical @code{AND}.
 939
 940 This intrinsic routine is provided for backwards compatibility with
 941 GNU Fortran 77.  For integer arguments, programmers should consider
 942 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
 943
 944 @item @emph{Standard}:
 945 GNU extension
 946
 947 @item @emph{Class}:
 948 Non-elemental function
 949
 950 @item @emph{Syntax}:
 951 @code{RESULT = AND(X, Y)}
 952
 953 @item @emph{Arguments}:
 954 @multitable @columnfractions .15 .80
 955 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
 956 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
 957 @end multitable
 958
 959 @item @emph{Return value}:
 960 The return type is either @code{INTEGER(*)} or @code{LOGICAL} after
 961 cross-promotion of the arguments.
 962
 963 @item @emph{Example}:
 964 @smallexample
 965 PROGRAM test_and
 966   LOGICAL :: T = .TRUE., F = ..FALSE.
 967   INTEGER :: a, b
 968   DATA a / Z'F' /, b / Z'3' /
 969
 970   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
 971   WRITE (*,*) AND(a, b)
 972 END PROGRAM
 973 @end smallexample
 974
 975 @item @emph{See also}:
 976 F95 elemental function: @ref{IAND}
 977 @end table
 978
 979
 980
 981 @node ANINT
 982 @section @code{ANINT} --- Nearest whole number
 983 @cindex @code{ANINT} intrinsic
 984 @cindex @code{DNINT} intrinsic
 985 @cindex whole number
 986
 987 @table @asis
 988 @item @emph{Description}:
 989 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
 990
 991 @item @emph{Standard}:
 992 F77 and later
 993
 994 @item @emph{Class}:
 995 Elemental function
 996
 997 @item @emph{Syntax}:
 998 @code{RESULT = ANINT(X [, KIND])}
 999
1000 @item @emph{Arguments}:
1001 @multitable @columnfractions .15 .80
1002 @item @var{X}    @tab The type of the argument shall be @code{REAL(*)}.
1003 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1004                       expression indicating the kind parameter of
1005                       the result.
1006 @end multitable
1007
1008 @item @emph{Return value}:
1009 The return value is of type real with the kind type parameter of the
1010 argument if the optional @var{KIND} is absent; otherwise, the kind
1011 type parameter will be given by @var{KIND}.  If @var{X} is greater than
1012 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}.  If @var{X} is
1013 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1014
1015 @item @emph{Example}:
1016 @smallexample
1017 program test_anint
1018   real(4) x4
1019   real(8) x8
1020   x4 = 1.234E0_4
1021   x8 = 4.321_8
1022   print *, anint(x4), dnint(x8)
1023   x8 = anint(x4,8)
1024 end program test_anint
1025 @end smallexample
1026
1027 @item @emph{Specific names}:
1028 @multitable @columnfractions .20 .20 .20 .40
1029 @item Name            @tab Argument         @tab Return type      @tab Standard
1030 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab F77 and later
1031 @end multitable
1032 @end table
1033
1034
1035
1036 @node ANY
1037 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1038 @cindex @code{ANY} intrinsic
1039 @cindex true values
1040
1041 @table @asis
1042 @item @emph{Description}:
1043 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1044 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1045
1046 @item @emph{Standard}:
1047 F95 and later
1048
1049 @item @emph{Class}:
1050 transformational function
1051
1052 @item @emph{Syntax}:
1053 @code{RESULT = ANY(MASK [, DIM])}
1054
1055 @item @emph{Arguments}:
1056 @multitable @columnfractions .15 .80
1057 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1058 it shall not be scalar.
1059 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1060 with a value that lies between one and the rank of @var{MASK}.
1061 @end multitable
1062
1063 @item @emph{Return value}:
1064 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1065 the kind type parameter is the same as the kind type parameter of
1066 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1067 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1068 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1069
1070 @table @asis
1071 @item (A)
1072 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1073 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1074 @item (B)
1075 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1076 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1077 is determined by applying @code{ANY} to the array sections.
1078 @end table
1079
1080 @item @emph{Example}:
1081 @smallexample
1082 program test_any
1083   logical l
1084   l = any((/.true., .true., .true./))
1085   print *, l
1086   call section
1087   contains
1088     subroutine section
1089       integer a(2,3), b(2,3)
1090       a = 1
1091       b = 1
1092       b(2,2) = 2
1093       print *, any(a .eq. b, 1)
1094       print *, any(a .eq. b, 2)
1095     end subroutine section
1096 end program test_any
1097 @end smallexample
1098 @end table
1099
1100
1101
1102 @node ASIN
1103 @section @code{ASIN} --- Arcsine function
1104 @cindex @code{ASIN} intrinsic
1105 @cindex @code{DASIN} intrinsic
1106 @cindex trigonometric functions (inverse)
1107
1108 @table @asis
1109 @item @emph{Description}:
1110 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1111
1112 @item @emph{Standard}:
1113 F77 and later
1114
1115 @item @emph{Class}:
1116 Elemental function
1117
1118 @item @emph{Syntax}:
1119 @code{RESULT = ASIN(X)}
1120
1121 @item @emph{Arguments}:
1122 @multitable @columnfractions .15 .80
1123 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1124 less than one.
1125 @end multitable
1126
1127 @item @emph{Return value}:
1128 The return value is of type @code{REAL(*)} and it lies in the
1129 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}.  The kind type
1130 parameter is the same as @var{X}.
1131
1132 @item @emph{Example}:
1133 @smallexample
1134 program test_asin
1135   real(8) :: x = 0.866_8
1136   x = asin(x)
1137 end program test_asin
1138 @end smallexample
1139
1140 @item @emph{Specific names}:
1141 @multitable @columnfractions .20 .20 .20 .40
1142 @item Name            @tab Argument          @tab Return type       @tab Standard
1143 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F77 and later
1144 @end multitable
1145
1146 @item @emph{See also}:
1147 Inverse function: @ref{SIN}
1148
1149 @end table
1150
1151
1152 @node ASINH
1153 @section @code{ASINH} --- Hyperbolic arcsine function
1154 @cindex @code{ASINH} intrinsic
1155 @cindex hyperbolic arcsine
1156 @cindex hyperbolic sine (inverse)
1157
1158 @table @asis
1159 @item @emph{Description}:
1160 @code{ASINH(X)} computes the area hyperbolic sine of @var{X} (inverse of @code{SINH(X)}).
1161
1162 @item @emph{Standard}:
1163 GNU extension
1164
1165 @item @emph{Class}:
1166 Elemental function
1167
1168 @item @emph{Syntax}:
1169 @code{RESULT = ASINH(X)}
1170
1171 @item @emph{Arguments}:
1172 @multitable @columnfractions .15 .80
1173 @item @var{X} @tab The type shall be @code{REAL(*)}, with @var{X} a real number.
1174 @end multitable
1175
1176 @item @emph{Return value}:
1177 The return value is of type @code{REAL(*)} and it lies in the
1178 range @math{-\infty \leq \asinh (x) \leq \infty}.
1179
1180 @item @emph{Example}:
1181 @smallexample
1182 PROGRAM test_asinh
1183   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1184   WRITE (*,*) ASINH(x)
1185 END PROGRAM
1186 @end smallexample
1187
1188 @item @emph{See also}:
1189 Inverse function: @ref{SINH}
1190 @end table
1191
1192
1193
1194 @node ASSOCIATED
1195 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1196 @cindex @code{ASSOCIATED} intrinsic
1197 @cindex pointer status
1198
1199 @table @asis
1200 @item @emph{Description}:
1201 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1202 or if @var{PTR} is associated with the target @var{TGT}.
1203
1204 @item @emph{Standard}:
1205 F95 and later
1206
1207 @item @emph{Class}:
1208 Inquiry function
1209
1210 @item @emph{Syntax}:
1211 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1212
1213 @item @emph{Arguments}:
1214 @multitable @columnfractions .15 .80
1215 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1216 it can be of any type.
1217 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1218 a @code{TARGET}.  It must have the same type, kind type parameter, and
1219 array rank as @var{PTR}.
1220 @end multitable
1221 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1222
1223 @item @emph{Return value}:
1224 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1225 There are several cases:
1226 @table @asis
1227 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1228 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1229 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1230 @var{TGT}
1231 is not a 0 sized storage sequence and the target associated with @var{PTR}
1232 occupies the same storage units.  If @var{PTR} is disassociated, then the
1233 result is false.
1234 @item (C) If @var{TGT} is present and an array target, the result is true if
1235 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1236 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1237 @var{PTR} occupy the same storage units in array element order.
1238 As in case(B), the result is false, if @var{PTR} is disassociated.
1239 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1240 target associated with @var{PTR} and the target associated with @var{TGT}
1241 are not 0 sized storage sequences and occupy the same storage units.
1242 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1243 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1244 target associated with @var{PTR} and the target associated with @var{TGT}
1245 have the same shape, are not 0 sized arrays, are arrays whose elements are
1246 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1247 storage units in array element order.
1248 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1249 @end table
1250
1251 @item @emph{Example}:
1252 @smallexample
1253 program test_associated
1254    implicit none
1255    real, target  :: tgt(2) = (/1., 2./)
1256    real, pointer :: ptr(:)
1257    ptr => tgt
1258    if (associated(ptr)     .eqv. .false.) call abort
1259    if (associated(ptr,tgt) .eqv. .false.) call abort
1260 end program test_associated
1261 @end smallexample
1262
1263 @item @emph{See also}:
1264 @ref{NULL}
1265 @end table
1266
1267
1268
1269 @node ATAN
1270 @section @code{ATAN} --- Arctangent function
1271 @cindex @code{ATAN} intrinsic
1272 @cindex @code{DATAN} intrinsic
1273 @cindex trigonometric functions (inverse)
1274
1275 @table @asis
1276 @item @emph{Description}:
1277 @code{ATAN(X)} computes the arctangent of @var{X}.
1278
1279 @item @emph{Standard}:
1280 F77 and later
1281
1282 @item @emph{Class}:
1283 Elemental function
1284
1285 @item @emph{Syntax}:
1286 @code{RESULT = ATAN(X)}
1287
1288 @item @emph{Arguments}:
1289 @multitable @columnfractions .15 .80
1290 @item @var{X} @tab The type shall be @code{REAL(*)}.
1291 @end multitable
1292
1293 @item @emph{Return value}:
1294 The return value is of type @code{REAL(*)} and it lies in the
1295 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1296
1297 @item @emph{Example}:
1298 @smallexample
1299 program test_atan
1300   real(8) :: x = 2.866_8
1301   x = atan(x)
1302 end program test_atan
1303 @end smallexample
1304
1305 @item @emph{Specific names}:
1306 @multitable @columnfractions .20 .20 .20 .40
1307 @item Name            @tab Argument          @tab Return type       @tab Standard
1308 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F77 and later
1309 @end multitable
1310
1311 @item @emph{See also}:
1312 Inverse function: @ref{TAN}
1313
1314 @end table
1315
1316
1317
1318 @node ATAN2
1319 @section @code{ATAN2} --- Arctangent function
1320 @cindex @code{ATAN2} intrinsic
1321 @cindex @code{DATAN2} intrinsic
1322 @cindex trigonometric functions (inverse)
1323
1324 @table @asis
1325 @item @emph{Description}:
1326 @code{ATAN2(Y,X)} computes the arctangent of the complex number @math{X + i Y}.
1327
1328 @item @emph{Standard}:
1329 F77 and later
1330
1331 @item @emph{Class}:
1332 Elemental function
1333
1334 @item @emph{Syntax}:
1335 @code{RESULT = ATAN2(Y,X)}
1336
1337 @item @emph{Arguments}:
1338 @multitable @columnfractions .15 .80
1339 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1340 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1341 If @var{Y} is zero, then @var{X} must be nonzero.
1342 @end multitable
1343
1344 @item @emph{Return value}:
1345 The return value has the same type and kind type parameter as @var{Y}.
1346 It is the principal value of the complex number @math{X + i Y}.  If
1347 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1348 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1349 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1350 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1351 is @math{\pi/2}.
1352
1353 @item @emph{Example}:
1354 @smallexample
1355 program test_atan2
1356   real(4) :: x = 1.e0_4, y = 0.5e0_4
1357   x = atan2(y,x)
1358 end program test_atan2
1359 @end smallexample
1360
1361 @item @emph{Specific names}:
1362 @multitable @columnfractions .20 .20 .20 .40
1363 @item Name            @tab Argument          @tab Return type    @tab Standard
1364 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1365 @end multitable
1366 @end table
1367
1368
1369
1370 @node ATANH
1371 @section @code{ATANH} --- Hyperbolic arctangent function
1372 @cindex @code{ASINH} intrinsic
1373 @cindex hyperbolic arctangent
1374 @cindex hyperbolic tangent (inverse)
1375
1376 @table @asis
1377 @item @emph{Description}:
1378 @code{ATANH(X)} computes the area hyperbolic sine of @var{X} (inverse of @code{TANH(X)}).
1379
1380 @item @emph{Standard}:
1381 GNU extension
1382
1383 @item @emph{Class}:
1384 Elemental function
1385
1386 @item @emph{Syntax}:
1387 @code{RESULT = ATANH(X)}
1388
1389 @item @emph{Arguments}:
1390 @multitable @columnfractions .15 .80
1391 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude
1392 that is less than or equal to one.
1393 @end multitable
1394
1395 @item @emph{Return value}:
1396 The return value is of type @code{REAL(*)} and it lies in the
1397 range @math{-\infty \leq \atanh(x) \leq \infty}.
1398
1399 @item @emph{Example}:
1400 @smallexample
1401 PROGRAM test_atanh
1402   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1403   WRITE (*,*) ATANH(x)
1404 END PROGRAM
1405 @end smallexample
1406
1407 @item @emph{See also}:
1408 Inverse function: @ref{TANH}
1409 @end table
1410
1411
1412
1413
1414 @node BESJ0
1415 @section @code{BESJ0} --- Bessel function of the first kind of order 0
1416 @cindex @code{BESJ0} intrinsic
1417 @cindex @code{DBESJ0} intrinsic
1418 @cindex Bessel
1419
1420 @table @asis
1421 @item @emph{Description}:
1422 @code{BESJ0(X)} computes the Bessel function of the first kind of order 0
1423 of @var{X}.
1424
1425 @item @emph{Standard}:
1426 GNU extension
1427
1428 @item @emph{Class}:
1429 Elemental function
1430
1431 @item @emph{Syntax}:
1432 @code{RESULT = BESJ0(X)}
1433
1434 @item @emph{Arguments}:
1435 @multitable @columnfractions .15 .80
1436 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1437 @end multitable
1438
1439 @item @emph{Return value}:
1440 The return value is of type @code{REAL(*)} and it lies in the
1441 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1442
1443 @item @emph{Example}:
1444 @smallexample
1445 program test_besj0
1446   real(8) :: x = 0.0_8
1447   x = besj0(x)
1448 end program test_besj0
1449 @end smallexample
1450
1451 @item @emph{Specific names}:
1452 @multitable @columnfractions .20 .20 .20 .40
1453 @item Name            @tab Argument          @tab Return type       @tab Standard
1454 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1455 @end multitable
1456 @end table
1457
1458
1459
1460 @node BESJ1
1461 @section @code{BESJ1} --- Bessel function of the first kind of order 1
1462 @cindex @code{BESJ1} intrinsic
1463 @cindex @code{DBESJ1} intrinsic
1464 @cindex Bessel
1465
1466 @table @asis
1467 @item @emph{Description}:
1468 @code{BESJ1(X)} computes the Bessel function of the first kind of order 1
1469 of @var{X}.
1470
1471 @item @emph{Standard}:
1472 GNU extension
1473
1474 @item @emph{Class}:
1475 Elemental function
1476
1477 @item @emph{Syntax}:
1478 @code{RESULT = BESJ1(X)}
1479
1480 @item @emph{Arguments}:
1481 @multitable @columnfractions .15 .80
1482 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1483 @end multitable
1484
1485 @item @emph{Return value}:
1486 The return value is of type @code{REAL(*)} and it lies in the
1487 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1488
1489 @item @emph{Example}:
1490 @smallexample
1491 program test_besj1
1492   real(8) :: x = 1.0_8
1493   x = besj1(x)
1494 end program test_besj1
1495 @end smallexample
1496
1497 @item @emph{Specific names}:
1498 @multitable @columnfractions .20 .20 .20 .40
1499 @item Name            @tab Argument          @tab Return type       @tab Standard
1500 @item @code{DBESJ1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1501 @end multitable
1502 @end table
1503
1504
1505
1506 @node BESJN
1507 @section @code{BESJN} --- Bessel function of the first kind
1508 @cindex @code{BESJN} intrinsic
1509 @cindex @code{DBESJN} intrinsic
1510 @cindex Bessel
1511
1512 @table @asis
1513 @item @emph{Description}:
1514 @code{BESJN(N, X)} computes the Bessel function of the first kind of order
1515 @var{N} of @var{X}.
1516
1517 @item @emph{Standard}:
1518 GNU extension
1519
1520 @item @emph{Class}:
1521 Elemental function
1522
1523 @item @emph{Syntax}:
1524 @code{RESULT = BESJN(N, X)}
1525
1526 @item @emph{Arguments}:
1527 @multitable @columnfractions .15 .80
1528 @item @var{N} @tab The type shall be @code{INTEGER(*)}, and it shall be scalar.
1529 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1530 @end multitable
1531
1532 @item @emph{Return value}:
1533 The return value is a scalar of type @code{REAL(*)}.
1534
1535 @item @emph{Example}:
1536 @smallexample
1537 program test_besjn
1538   real(8) :: x = 1.0_8
1539   x = besjn(5,x)
1540 end program test_besjn
1541 @end smallexample
1542
1543 @item @emph{Specific names}:
1544 @multitable @columnfractions .20 .20 .20 .40
1545 @item Name             @tab Argument            @tab Return type       @tab Standard
1546 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)}    @tab GNU extension
1547 @item                  @tab @code{REAL(8) X}    @tab                   @tab
1548 @end multitable
1549 @end table
1550
1551
1552
1553 @node BESY0
1554 @section @code{BESY0} --- Bessel function of the second kind of order 0
1555 @cindex @code{BESY0} intrinsic
1556 @cindex @code{DBESY0} intrinsic
1557 @cindex Bessel
1558
1559 @table @asis
1560 @item @emph{Description}:
1561 @code{BESY0(X)} computes the Bessel function of the second kind of order 0
1562 of @var{X}.
1563
1564 @item @emph{Standard}:
1565 GNU extension
1566
1567 @item @emph{Class}:
1568 Elemental function
1569
1570 @item @emph{Syntax}:
1571 @code{RESULT = BESY0(X)}
1572
1573 @item @emph{Arguments}:
1574 @multitable @columnfractions .15 .80
1575 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1576 @end multitable
1577
1578 @item @emph{Return value}:
1579 The return value is a scalar of type @code{REAL(*)}.
1580
1581 @item @emph{Example}:
1582 @smallexample
1583 program test_besy0
1584   real(8) :: x = 0.0_8
1585   x = besy0(x)
1586 end program test_besy0
1587 @end smallexample
1588
1589 @item @emph{Specific names}:
1590 @multitable @columnfractions .20 .20 .20 .40
1591 @item Name            @tab Argument          @tab Return type       @tab Standard
1592 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1593 @end multitable
1594 @end table
1595
1596
1597
1598 @node BESY1
1599 @section @code{BESY1} --- Bessel function of the second kind of order 1
1600 @cindex @code{BESY1} intrinsic
1601 @cindex @code{DBESY1} intrinsic
1602 @cindex Bessel
1603
1604 @table @asis
1605 @item @emph{Description}:
1606 @code{BESY1(X)} computes the Bessel function of the second kind of order 1
1607 of @var{X}.
1608
1609 @item @emph{Standard}:
1610 GNU extension
1611
1612 @item @emph{Class}:
1613 Elemental function
1614
1615 @item @emph{Syntax}:
1616 @code{RESULT = BESY1(X)}
1617
1618 @item @emph{Arguments}:
1619 @multitable @columnfractions .15 .80
1620 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1621 @end multitable
1622
1623 @item @emph{Return value}:
1624 The return value is a scalar of type @code{REAL(*)}.
1625
1626 @item @emph{Example}:
1627 @smallexample
1628 program test_besy1
1629   real(8) :: x = 1.0_8
1630   x = besy1(x)
1631 end program test_besy1
1632 @end smallexample
1633
1634 @item @emph{Specific names}:
1635 @multitable @columnfractions .20 .20 .20 .40
1636 @item Name            @tab Argument          @tab Return type       @tab Standard
1637 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1638 @end multitable
1639 @end table
1640
1641
1642
1643 @node BESYN
1644 @section @code{BESYN} --- Bessel function of the second kind
1645 @cindex @code{BESYN} intrinsic
1646 @cindex @code{DBESYN} intrinsic
1647 @cindex Bessel
1648
1649 @table @asis
1650 @item @emph{Description}:
1651 @code{BESYN(N, X)} computes the Bessel function of the second kind of order
1652 @var{N} of @var{X}.
1653
1654 @item @emph{Standard}:
1655 GNU extension
1656
1657 @item @emph{Class}:
1658 Elemental function
1659
1660 @item @emph{Syntax}:
1661 @code{RESULT = BESYN(N, X)}
1662
1663 @item @emph{Arguments}:
1664 @multitable @columnfractions .15 .80
1665 @item @var{N} @tab The type shall be @code{INTEGER(*)}, and it shall be scalar.
1666 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1667 @end multitable
1668
1669 @item @emph{Return value}:
1670 The return value is a scalar of type @code{REAL(*)}.
1671
1672 @item @emph{Example}:
1673 @smallexample
1674 program test_besyn
1675   real(8) :: x = 1.0_8
1676   x = besyn(5,x)
1677 end program test_besyn
1678 @end smallexample
1679
1680 @item @emph{Specific names}:
1681 @multitable @columnfractions .20 .20 .20 .40
1682 @item Name               @tab Argument            @tab Return type     @tab Standard
1683 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)}  @tab GNU extension
1684 @item                    @tab @code{REAL(8)    X} @tab                 @tab
1685 @end multitable
1686 @end table
1687
1688
1689
1690 @node BIT_SIZE
1691 @section @code{BIT_SIZE} --- Bit size inquiry function
1692 @cindex @code{BIT_SIZE} intrinsic
1693 @cindex bit size of a variable
1694 @cindex size of a variable, in bits
1695
1696 @table @asis
1697 @item @emph{Description}:
1698 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1699 represented by the type of @var{I}.
1700
1701 @item @emph{Standard}:
1702 F95 and later
1703
1704 @item @emph{Class}:
1705 Inquiry function
1706
1707 @item @emph{Syntax}:
1708 @code{RESULT = BIT_SIZE(I)}
1709
1710 @item @emph{Arguments}:
1711 @multitable @columnfractions .15 .80
1712 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1713 @end multitable
1714
1715 @item @emph{Return value}:
1716 The return value is of type @code{INTEGER(*)}
1717
1718 @item @emph{Example}:
1719 @smallexample
1720 program test_bit_size
1721     integer :: i = 123
1722     integer :: size
1723     size = bit_size(i)
1724     print *, size
1725 end program test_bit_size
1726 @end smallexample
1727 @end table
1728
1729
1730
1731 @node BTEST
1732 @section @code{BTEST} --- Bit test function
1733 @cindex @code{BTEST} intrinsic
1734 @cindex bit operations
1735
1736 @table @asis
1737 @item @emph{Description}:
1738 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1739 in @var{I} is set.
1740
1741 @item @emph{Standard}:
1742 F95 and later
1743
1744 @item @emph{Class}:
1745 Elemental function
1746
1747 @item @emph{Syntax}:
1748 @code{RESULT = BTEST(I, POS)}
1749
1750 @item @emph{Arguments}:
1751 @multitable @columnfractions .15 .80
1752 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1753 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1754 @end multitable
1755
1756 @item @emph{Return value}:
1757 The return value is of type @code{LOGICAL}
1758
1759 @item @emph{Example}:
1760 @smallexample
1761 program test_btest
1762     integer :: i = 32768 + 1024 + 64
1763     integer :: pos
1764     logical :: bool
1765     do pos=0,16
1766         bool = btest(i, pos)
1767         print *, pos, bool
1768     end do
1769 end program test_btest
1770 @end smallexample
1771 @end table
1772
1773
1774
1775 @node CEILING
1776 @section @code{CEILING} --- Integer ceiling function
1777 @cindex @code{CEILING} intrinsic
1778 @cindex ceiling
1779
1780 @table @asis
1781 @item @emph{Description}:
1782 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
1783
1784 @item @emph{Standard}:
1785 F95 and later
1786
1787 @item @emph{Class}:
1788 Elemental function
1789
1790 @item @emph{Syntax}:
1791 @code{RESULT = CEILING(X [, KIND])}
1792
1793 @item @emph{Arguments}:
1794 @multitable @columnfractions .15 .80
1795 @item @var{X} @tab The type shall be @code{REAL(*)}.
1796 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1797                       expression indicating the kind parameter of
1798                       the result.
1799 @end multitable
1800
1801 @item @emph{Return value}:
1802 The return value is of type @code{INTEGER(KIND)}
1803
1804 @item @emph{Example}:
1805 @smallexample
1806 program test_ceiling
1807     real :: x = 63.29
1808     real :: y = -63.59
1809     print *, ceiling(x) ! returns 64
1810     print *, ceiling(y) ! returns -63
1811 end program test_ceiling
1812 @end smallexample
1813
1814 @item @emph{See also}:
1815 @ref{FLOOR}, @ref{NINT}
1816
1817 @end table
1818
1819
1820
1821 @node CHAR
1822 @section @code{CHAR} --- Character conversion function
1823 @cindex @code{CHAR} intrinsic
1824 @cindex conversion function (character)
1825
1826 @table @asis
1827 @item @emph{Description}:
1828 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
1829
1830 @item @emph{Standard}:
1831 F77 and later
1832
1833 @item @emph{Class}:
1834 Elemental function
1835
1836 @item @emph{Syntax}:
1837 @code{RESULT = CHAR(I [, KIND])}
1838
1839 @item @emph{Arguments}:
1840 @multitable @columnfractions .15 .80
1841 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1842 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1843                       expression indicating the kind parameter of
1844                       the result.
1845 @end multitable
1846
1847 @item @emph{Return value}:
1848 The return value is of type @code{CHARACTER(1)}
1849
1850 @item @emph{Example}:
1851 @smallexample
1852 program test_char
1853     integer :: i = 74
1854     character(1) :: c
1855     c = char(i)
1856     print *, i, c ! returns 'J'
1857 end program test_char
1858 @end smallexample
1859
1860 @item @emph{See also}:
1861 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
1862
1863 @end table
1864
1865
1866 @node CHDIR
1867 @section @code{CHDIR} --- Change working directory
1868 @cindex @code{CHDIR} intrinsic
1869 @cindex file system operations
1870
1871 @table @asis
1872 @item @emph{Description}:
1873 Change current working directory to a specified @var{PATH}.
1874
1875 @item @emph{Standard}:
1876 GNU extension
1877
1878 @item @emph{Class}:
1879 Non-elemental subroutine
1880
1881 @item @emph{Syntax}:
1882 @code{CALL CHDIR(PATH [, STATUS])}
1883
1884 @item @emph{Arguments}:
1885 @multitable @columnfractions .15 .80
1886 @item @var{PATH}   @tab The type shall be @code{CHARACTER(*)} and shall
1887                         specify a valid path within the file system.
1888 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
1889                         a system specific and non-zero error code otherwise.
1890 @end multitable
1891
1892 @item @emph{Example}:
1893 @smallexample
1894 PROGRAM test_chdir
1895   CHARACTER(len=255) :: path
1896   CALL getcwd(path)
1897   WRITE(*,*) TRIM(path)
1898   CALL chdir("/tmp")
1899   CALL getcwd(path)
1900   WRITE(*,*) TRIM(path)
1901 END PROGRAM
1902 @end smallexample
1903
1904 @item @emph{See also}:
1905 @ref{GETCWD}
1906 @end table
1907
1908
1909
1910 @node CHMOD
1911 @section @code{CHMOD} --- Change access permissions of files
1912 @cindex @code{CHMOD} intrinsic
1913 @cindex file system operations
1914
1915 @table @asis
1916 @item @emph{Description}:
1917 @code{CHMOD} changes the permissions of a file. This function invokes
1918 @code{/bin/chmod} and might therefore not work on all platforms.
1919
1920 This intrinsic is provided in both subroutine and function forms; however,
1921 only one form can be used in any given program unit.
1922
1923 @item @emph{Standard}:
1924 GNU extension
1925
1926 @item @emph{Class}:
1927 Subroutine, non-elemental function
1928
1929 @item @emph{Syntax}:
1930 @multitable @columnfractions .80
1931 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
1932 @item @code{STATUS = CHMOD(NAME, MODE)}
1933 @end multitable
1934
1935 @item @emph{Arguments}:
1936 @multitable @columnfractions .15 .80
1937 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
1938 Trailing blanks are ignored unless the character @code{achar(0)} is
1939 present, then all characters up to and excluding @code{achar(0)} are
1940 used as the file name.
1941
1942 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
1943 @var{MODE} uses the same syntax as the @var{MODE} argument of
1944 @code{/bin/chmod}.
1945
1946 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
1947 @code{0} on success and non-zero otherwise.
1948 @end multitable
1949
1950 @item @emph{Return value}:
1951 In either syntax, @var{STATUS} is set to @code{0} on success and non-zero
1952 otherwise.
1953
1954 @item @emph{Example}:
1955 @code{CHMOD} as subroutine
1956 @smallexample
1957 program chmod_test
1958   implicit none
1959   integer :: status
1960   call chmod('test.dat','u+x',status)
1961   print *, 'Status: ', status
1962 end program chmod_test
1963 @end smallexample
1964 @code{CHMOD} as non-elemental function:
1965 @smallexample
1966 program chmod_test
1967   implicit none
1968   integer :: status
1969   status = chmod('test.dat','u+x')
1970   print *, 'Status: ', status
1971 end program chmod_test
1972 @end smallexample
1973 @item @emph{Specific names}:
1974 @item @emph{See also}:
1975
1976 @end table
1977
1978
1979 @node CMPLX
1980 @section @code{CMPLX} --- Complex conversion function
1981 @cindex @code{CMPLX} intrinsic
1982 @cindex complex numbers, conversion to
1983
1984 @table @asis
1985 @item @emph{Description}:
1986 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
1987 the real component.  If @var{Y} is present it is converted to the imaginary
1988 component.  If @var{Y} is not present then the imaginary component is set to
1989 0.0.  If @var{X} is complex then @var{Y} must not be present.
1990
1991 @item @emph{Standard}:
1992 F77 and later
1993
1994 @item @emph{Class}:
1995 Elemental function
1996
1997 @item @emph{Syntax}:
1998 @code{RESULT = CMPLX(X [, Y [, KIND]])}
1999
2000 @item @emph{Arguments}:
2001 @multitable @columnfractions .15 .80
2002 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2003                    or @code{COMPLEX(*)}.
2004 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2005                    @code{COMPLEX(*)}.)  May be @code{INTEGER(*)}
2006                    or @code{REAL(*)}.
2007 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2008                       expression indicating the kind parameter of
2009                       the result.
2010 @end multitable
2011
2012 @item @emph{Return value}:
2013 The return value is of type @code{COMPLEX(*)}
2014
2015 @item @emph{Example}:
2016 @smallexample
2017 program test_cmplx
2018     integer :: i = 42
2019     real :: x = 3.14
2020     complex :: z
2021     z = cmplx(i, x)
2022     print *, z, cmplx(x)
2023 end program test_cmplx
2024 @end smallexample
2025 @end table
2026
2027
2028
2029 @node COMMAND_ARGUMENT_COUNT
2030 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2031 @cindex @code{COMMAND_ARGUMENT_COUNT} intrinsic
2032 @cindex command-line arguments, to program
2033
2034 @table @asis
2035 @item @emph{Description}:
2036 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2037 command line when the containing program was invoked.
2038
2039 @item @emph{Standard}:
2040 F2003
2041
2042 @item @emph{Class}:
2043 Inquiry function
2044
2045 @item @emph{Syntax}:
2046 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2047
2048 @item @emph{Arguments}:
2049 @multitable @columnfractions .15 .80
2050 @item None
2051 @end multitable
2052
2053 @item @emph{Return value}:
2054 The return value is of type @code{INTEGER(4)}
2055
2056 @item @emph{Example}:
2057 @smallexample
2058 program test_command_argument_count
2059     integer :: count
2060     count = command_argument_count()
2061     print *, count
2062 end program test_command_argument_count
2063 @end smallexample
2064
2065 @item @emph{See also}:
2066 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2067 @end table
2068
2069 @node CONJG
2070 @section @code{CONJG} --- Complex conjugate function
2071 @cindex @code{CONJG} intrinsic
2072 @cindex @code{DCONJG} intrinsic
2073 @cindex complex conjugate
2074 @table @asis
2075 @item @emph{Description}:
2076 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2077 then the result is @code{(x, -y)}
2078
2079 @item @emph{Standard}:
2080 F77 and later, has overloads that are GNU extensions
2081
2082 @item @emph{Class}:
2083 Elemental function
2084
2085 @item @emph{Syntax}:
2086 @code{Z = CONJG(Z)}
2087
2088 @item @emph{Arguments}:
2089 @multitable @columnfractions .15 .80
2090 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2091 @end multitable
2092
2093 @item @emph{Return value}:
2094 The return value is of type @code{COMPLEX(*)}.
2095
2096 @item @emph{Example}:
2097 @smallexample
2098 program test_conjg
2099     complex :: z = (2.0, 3.0)
2100     complex(8) :: dz = (2.71_8, -3.14_8)
2101     z= conjg(z)
2102     print *, z
2103     dz = dconjg(dz)
2104     print *, dz
2105 end program test_conjg
2106 @end smallexample
2107
2108 @item @emph{Specific names}:
2109 @multitable @columnfractions .20 .20 .20 .40
2110 @item Name             @tab Argument             @tab Return type          @tab Standard
2111 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)}    @tab GNU extension
2112 @end multitable
2113 @end table
2114
2115
2116
2117 @node COS
2118 @section @code{COS} --- Cosine function
2119 @cindex @code{COS} intrinsic
2120 @cindex @code{DCOS} intrinsic
2121 @cindex @code{ZCOS} intrinsic
2122 @cindex @code{CDCOS} intrinsic
2123 @cindex trigonometric functions
2124
2125 @table @asis
2126 @item @emph{Description}:
2127 @code{COS(X)} computes the cosine of @var{X}.
2128
2129 @item @emph{Standard}:
2130 F77 and later, has overloads that are GNU extensions
2131
2132 @item @emph{Class}:
2133 Elemental function
2134
2135 @item @emph{Syntax}:
2136 @code{RESULT = COS(X)}
2137
2138 @item @emph{Arguments}:
2139 @multitable @columnfractions .15 .80
2140 @item @var{X} @tab The type shall be @code{REAL(*)} or
2141 @code{COMPLEX(*)}.
2142 @end multitable
2143
2144 @item @emph{Return value}:
2145 The return value is of type @code{REAL(*)} and it lies in the
2146 range @math{ -1 \leq \cos (x) \leq 1}.  The kind type
2147 parameter is the same as @var{X}.
2148
2149 @item @emph{Example}:
2150 @smallexample
2151 program test_cos
2152   real :: x = 0.0
2153   x = cos(x)
2154 end program test_cos
2155 @end smallexample
2156
2157 @item @emph{Specific names}:
2158 @multitable @columnfractions .20 .20 .20 .40
2159 @item Name            @tab Argument            @tab Return type       @tab Standard
2160 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab F77 and later
2161 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
2162 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2163 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2164 @end multitable
2165
2166 @item @emph{See also}:
2167 Inverse function: @ref{ACOS}
2168
2169 @end table
2170
2171
2172
2173 @node COSH
2174 @section @code{COSH} --- Hyperbolic cosine function
2175 @cindex @code{COSH} intrinsic
2176 @cindex @code{DCOSH} intrinsic
2177 @cindex hyperbolic cosine
2178
2179 @table @asis
2180 @item @emph{Description}:
2181 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2182
2183 @item @emph{Standard}:
2184 F77 and later
2185
2186 @item @emph{Class}:
2187 Elemental function
2188
2189 @item @emph{Syntax}:
2190 @code{X = COSH(X)}
2191
2192 @item @emph{Arguments}:
2193 @multitable @columnfractions .15 .80
2194 @item @var{X} @tab The type shall be @code{REAL(*)}.
2195 @end multitable
2196
2197 @item @emph{Return value}:
2198 The return value is of type @code{REAL(*)} and it is positive
2199 (@math{ \cosh (x) \geq 0 }.
2200
2201 @item @emph{Example}:
2202 @smallexample
2203 program test_cosh
2204   real(8) :: x = 1.0_8
2205   x = cosh(x)
2206 end program test_cosh
2207 @end smallexample
2208
2209 @item @emph{Specific names}:
2210 @multitable @columnfractions .20 .20 .20 .40
2211 @item Name            @tab Argument          @tab Return type       @tab Standard
2212 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F77 and later
2213 @end multitable
2214
2215 @item @emph{See also}:
2216 Inverse function: @ref{ACOSH}
2217
2218 @end table
2219
2220
2221
2222 @node COUNT
2223 @section @code{COUNT} --- Count function
2224 @cindex @code{COUNT} intrinsic
2225 @cindex count
2226
2227 @table @asis
2228 @item @emph{Description}:
2229 @code{COUNT(MASK [, DIM])} counts the number of @code{.TRUE.} elements of
2230 @var{MASK} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
2231 taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the
2232 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{MASK}.
2233
2234 @item @emph{Standard}:
2235 F95 and later
2236
2237 @item @emph{Class}:
2238 transformational function
2239
2240 @item @emph{Syntax}:
2241 @code{RESULT = COUNT(MASK [, DIM])}
2242
2243 @item @emph{Arguments}:
2244 @multitable @columnfractions .15 .80
2245 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2246 @item @var{DIM}  @tab The type shall be @code{INTEGER}.
2247 @end multitable
2248
2249 @item @emph{Return value}:
2250 The return value is of type @code{INTEGER} with rank equal to that of
2251 @var{MASK}.
2252
2253 @item @emph{Example}:
2254 @smallexample
2255 program test_count
2256     integer, dimension(2,3) :: a, b
2257     logical, dimension(2,3) :: mask
2258     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2259     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2260     print '(3i3)', a(1,:)
2261     print '(3i3)', a(2,:)
2262     print *
2263     print '(3i3)', b(1,:)
2264     print '(3i3)', b(2,:)
2265     print *
2266     mask = a.ne.b
2267     print '(3l3)', mask(1,:)
2268     print '(3l3)', mask(2,:)
2269     print *
2270     print '(3i3)', count(mask)
2271     print *
2272     print '(3i3)', count(mask, 1)
2273     print *
2274     print '(3i3)', count(mask, 2)
2275 end program test_count
2276 @end smallexample
2277 @end table
2278
2279
2280
2281 @node CPU_TIME
2282 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2283 @cindex @code{CPU_TIME} intrinsic
2284 @cindex time, elapsed
2285 @cindex elapsed time
2286
2287 @table @asis
2288 @item @emph{Description}:
2289 Returns a @code{REAL} value representing the elapsed CPU time in seconds.  This
2290 is useful for testing segments of code to determine execution time.
2291
2292 @item @emph{Standard}:
2293 F95 and later
2294
2295 @item @emph{Class}:
2296 Subroutine
2297
2298 @item @emph{Syntax}:
2299 @code{CALL CPU_TIME(X)}
2300
2301 @item @emph{Arguments}:
2302 @multitable @columnfractions .15 .80
2303 @item @var{X} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2304 @end multitable
2305
2306 @item @emph{Return value}:
2307 None
2308
2309 @item @emph{Example}:
2310 @smallexample
2311 program test_cpu_time
2312     real :: start, finish
2313     call cpu_time(start)
2314         ! put code to test here
2315     call cpu_time(finish)
2316     print '("Time = ",f6.3," seconds.")',finish-start
2317 end program test_cpu_time
2318 @end smallexample
2319 @end table
2320
2321
2322
2323 @node CSHIFT
2324 @section @code{CSHIFT} --- Circular shift function
2325 @cindex @code{CSHIFT} intrinsic
2326 @cindex bit operations
2327
2328 @table @asis
2329 @item @emph{Description}:
2330 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2331 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
2332 taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the
2333 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2334 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2335 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
2336 sections of @var{ARRAY} along the given dimension are shifted.  Elements
2337 shifted out one end of each rank one section are shifted back in the other end.
2338
2339 @item @emph{Standard}:
2340 F95 and later
2341
2342 @item @emph{Class}:
2343 transformational function
2344
2345 @item @emph{Syntax}:
2346 @code{RESULT = CSHIFT(A, SHIFT [, DIM])}
2347
2348 @item @emph{Arguments}:
2349 @multitable @columnfractions .15 .80
2350 @item @var{ARRAY}  @tab May be any type, not scaler.
2351 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
2352 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
2353 @end multitable
2354
2355 @item @emph{Return value}:
2356 Returns an array of same type and rank as the @var{ARRAY} argument.
2357
2358 @item @emph{Example}:
2359 @smallexample
2360 program test_cshift
2361     integer, dimension(3,3) :: a
2362     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2363     print '(3i3)', a(1,:)
2364     print '(3i3)', a(2,:)
2365     print '(3i3)', a(3,:)
2366     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2367     print *
2368     print '(3i3)', a(1,:)
2369     print '(3i3)', a(2,:)
2370     print '(3i3)', a(3,:)
2371 end program test_cshift
2372 @end smallexample
2373 @end table
2374
2375
2376 @node CTIME
2377 @section @code{CTIME} --- Convert a time into a string
2378 @cindex @code{CTIME} intrinsic
2379 @cindex time, conversion function
2380
2381 @table @asis
2382 @item @emph{Description}:
2383 @code{CTIME(T,S)} converts @var{T}, a system time value, such as returned
2384 by @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14
2385 1995}, and returns that string into @var{S}.
2386
2387 If @code{CTIME} is invoked as a function, it can not be invoked as a
2388 subroutine, and vice versa.
2389
2390 @var{T} is an @code{INTENT(IN)} @code{INTEGER(KIND=8)} variable.
2391 @var{S} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
2392
2393 @item @emph{Standard}:
2394 GNU extension
2395
2396 @item @emph{Class}:
2397 Subroutine
2398
2399 @item @emph{Syntax}:
2400 @multitable @columnfractions .80
2401 @item @code{CALL CTIME(T,S)}.
2402 @item @code{S = CTIME(T)}, (not recommended).
2403 @end multitable
2404
2405 @item @emph{Arguments}:
2406 @multitable @columnfractions .15 .80
2407 @item @var{S}@tab The type shall be of type @code{CHARACTER}.
2408 @item @var{T}@tab The type shall be of type @code{INTEGER(KIND=8)}.
2409 @end multitable
2410
2411 @item @emph{Return value}:
2412 The converted date and time as a string.
2413
2414 @item @emph{Example}:
2415 @smallexample
2416 program test_ctime
2417     integer(8) :: i
2418     character(len=30) :: date
2419     i = time8()
2420
2421     ! Do something, main part of the program
2422
2423     call ctime(i,date)
2424     print *, 'Program was started on ', date
2425 end program test_ctime
2426 @end smallexample
2427
2428 @item @emph{See Also}:
2429 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2430
2431 @end table
2432
2433
2434
2435 @node DATE_AND_TIME
2436 @section @code{DATE_AND_TIME} --- Date and time subroutine
2437 @cindex @code{DATE_AND_TIME} intrinsic
2438 @cindex date, current
2439 @cindex current date
2440 @cindex time, current
2441 @cindex current time
2442
2443 @table @asis
2444 @item @emph{Description}:
2445 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2446 time information from the real-time system clock.  @var{DATE} is
2447 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
2448 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2449 representing the difference with respect to Coordinated Universal Time (UTC).
2450 Unavailable time and date parameters return blanks.
2451
2452 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2453
2454 @multitable @columnfractions .15 .30 .60
2455 @item @tab @code{VALUE(1)}: @tab The year
2456 @item @tab @code{VALUE(2)}: @tab The month
2457 @item @tab @code{VALUE(3)}: @tab The day of the month
2458 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2459 @item @tab @code{VALUE(5)}: @tab The hour of the day
2460 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2461 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2462 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2463 @end multitable
2464
2465 @item @emph{Standard}:
2466 F95 and later
2467
2468 @item @emph{Class}:
2469 Subroutine
2470
2471 @item @emph{Syntax}:
2472 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2473
2474 @item @emph{Arguments}:
2475 @multitable @columnfractions .15 .80
2476 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2477 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2478 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2479 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2480 @end multitable
2481
2482 @item @emph{Return value}:
2483 None
2484
2485 @item @emph{Example}:
2486 @smallexample
2487 program test_time_and_date
2488     character(8)  :: date
2489     character(10) :: time
2490     character(5)  :: zone
2491     integer,dimension(8) :: values
2492     ! using keyword arguments
2493     call date_and_time(date,time,zone,values)
2494     call date_and_time(DATE=date,ZONE=zone)
2495     call date_and_time(TIME=time)
2496     call date_and_time(VALUES=values)
2497     print '(a,2x,a,2x,a)', date, time, zone
2498     print '(8i5))', values
2499 end program test_time_and_date
2500 @end smallexample
2501 @end table
2502
2503
2504
2505 @node DBLE
2506 @section @code{DBLE} --- Double conversion function
2507 @cindex @code{DBLE} intrinsic
2508 @cindex double conversion
2509
2510 @table @asis
2511 @item @emph{Description}:
2512 @code{DBLE(X)} Converts @var{X} to double precision real type.
2513
2514 @item @emph{Standard}:
2515 F77 and later
2516
2517 @item @emph{Class}:
2518 Elemental function
2519
2520 @item @emph{Syntax}:
2521 @code{RESULT = DBLE(X)}
2522
2523 @item @emph{Arguments}:
2524 @multitable @columnfractions .15 .80
2525 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2526                    or @code{COMPLEX(*)}.
2527 @end multitable
2528
2529 @item @emph{Return value}:
2530 The return value is of type double precision real.
2531
2532 @item @emph{Example}:
2533 @smallexample
2534 program test_dble
2535     real    :: x = 2.18
2536     integer :: i = 5
2537     complex :: z = (2.3,1.14)
2538     print *, dble(x), dble(i), dble(z)
2539 end program test_dble
2540 @end smallexample
2541
2542 @item @emph{See also}:
2543 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
2544 @end table
2545
2546
2547
2548 @node DCMPLX
2549 @section @code{DCMPLX} --- Double complex conversion function
2550 @cindex @code{DCMPLX} intrinsic
2551 @cindex complex numbers, conversion to
2552
2553 @table @asis
2554 @item @emph{Description}:
2555 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
2556 converted to the real component.  If @var{Y} is present it is converted to the
2557 imaginary component.  If @var{Y} is not present then the imaginary component is
2558 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
2559
2560 @item @emph{Standard}:
2561 GNU extension
2562
2563 @item @emph{Class}:
2564 Elemental function
2565
2566 @item @emph{Syntax}:
2567 @code{RESULT = DCMPLX(X [, Y])}
2568
2569 @item @emph{Arguments}:
2570 @multitable @columnfractions .15 .80
2571 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2572                    or @code{COMPLEX(*)}.
2573 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
2574                    @code{INTEGER(*)} or @code{REAL(*)}.
2575 @end multitable
2576
2577 @item @emph{Return value}:
2578 The return value is of type @code{COMPLEX(8)}
2579
2580 @item @emph{Example}:
2581 @smallexample
2582 program test_dcmplx
2583     integer :: i = 42
2584     real :: x = 3.14
2585     complex :: z
2586     z = cmplx(i, x)
2587     print *, dcmplx(i)
2588     print *, dcmplx(x)
2589     print *, dcmplx(z)
2590     print *, dcmplx(x,i)
2591 end program test_dcmplx
2592 @end smallexample
2593 @end table
2594
2595
2596
2597 @node DFLOAT
2598 @section @code{DFLOAT} --- Double conversion function
2599 @cindex @code{DFLOAT} intrinsic
2600 @cindex double float conversion
2601
2602 @table @asis
2603 @item @emph{Description}:
2604 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
2605
2606 @item @emph{Standard}:
2607 GNU extension
2608
2609 @item @emph{Class}:
2610 Elemental function
2611
2612 @item @emph{Syntax}:
2613 @code{RESULT = DFLOAT(X)}
2614
2615 @item @emph{Arguments}:
2616 @multitable @columnfractions .15 .80
2617 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
2618 @end multitable
2619
2620 @item @emph{Return value}:
2621 The return value is of type double precision real.
2622
2623 @item @emph{Example}:
2624 @smallexample
2625 program test_dfloat
2626     integer :: i = 5
2627     print *, dfloat(i)
2628 end program test_dfloat
2629 @end smallexample
2630
2631 @item @emph{See also}:
2632 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
2633 @end table
2634
2635
2636
2637 @node DIGITS
2638 @section @code{DIGITS} --- Significant digits function
2639 @cindex @code{DIGITS} intrinsic
2640 @cindex digits, significant
2641
2642 @table @asis
2643 @item @emph{Description}:
2644 @code{DIGITS(X)} returns the number of significant digits of the internal model
2645 representation of @var{X}.  For example, on a system using a 32-bit
2646 floating point representation, a default real number would likely return 24.
2647
2648 @item @emph{Standard}:
2649 F95 and later
2650
2651 @item @emph{Class}:
2652 Inquiry function
2653
2654 @item @emph{Syntax}:
2655 @code{RESULT = DIGITS(X)}
2656
2657 @item @emph{Arguments}:
2658 @multitable @columnfractions .15 .80
2659 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2660 @end multitable
2661
2662 @item @emph{Return value}:
2663 The return value is of type @code{INTEGER}.
2664
2665 @item @emph{Example}:
2666 @smallexample
2667 program test_digits
2668     integer :: i = 12345
2669     real :: x = 3.143
2670     real(8) :: y = 2.33
2671     print *, digits(i)
2672     print *, digits(x)
2673     print *, digits(y)
2674 end program test_digits
2675 @end smallexample
2676 @end table
2677
2678
2679
2680 @node DIM
2681 @section @code{DIM} --- Dim function
2682 @cindex @code{DIM} intrinsic
2683 @cindex @code{IDIM} intrinsic
2684 @cindex @code{DDIM} intrinsic
2685 @cindex dim
2686
2687 @table @asis
2688 @item @emph{Description}:
2689 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
2690 otherwise returns zero.
2691
2692 @item @emph{Standard}:
2693 F77 and later
2694
2695 @item @emph{Class}:
2696 Elemental function
2697
2698 @item @emph{Syntax}:
2699 @code{RESULT = DIM(X, Y)}
2700
2701 @item @emph{Arguments}:
2702 @multitable @columnfractions .15 .80
2703 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
2704 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
2705 @end multitable
2706
2707 @item @emph{Return value}:
2708 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
2709
2710 @item @emph{Example}:
2711 @smallexample
2712 program test_dim
2713     integer :: i
2714     real(8) :: x
2715     i = dim(4, 15)
2716     x = dim(4.345_8, 2.111_8)
2717     print *, i
2718     print *, x
2719 end program test_dim
2720 @end smallexample
2721
2722 @item @emph{Specific names}:
2723 @multitable @columnfractions .20 .20 .20 .40
2724 @item Name             @tab Argument              @tab Return type       @tab Standard
2725 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
2726 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}    @tab @code{REAL(8)}    @tab F77 and later
2727 @end multitable
2728 @end table
2729
2730
2731
2732 @node DOT_PRODUCT
2733 @section @code{DOT_PRODUCT} --- Dot product function
2734 @cindex @code{DOT_PRODUCT} intrinsic
2735 @cindex dot product
2736
2737 @table @asis
2738 @item @emph{Description}:
2739 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
2740 @var{X} and @var{Y}.  The two vectors may be either numeric or logical
2741 and must be arrays of rank one and of equal size. If the vectors are
2742 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
2743 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
2744 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
2745
2746 @item @emph{Standard}:
2747 F95 and later
2748
2749 @item @emph{Class}:
2750 transformational function
2751
2752 @item @emph{Syntax}:
2753 @code{RESULT = DOT_PRODUCT(X, Y)}
2754
2755 @item @emph{Arguments}:
2756 @multitable @columnfractions .15 .80
2757 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
2758 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
2759 @end multitable
2760
2761 @item @emph{Return value}:
2762 If the arguments are numeric, the return value is a scaler of numeric type,
2763 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}.  If the arguments are
2764 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
2765
2766 @item @emph{Example}:
2767 @smallexample
2768 program test_dot_prod
2769     integer, dimension(3) :: a, b
2770     a = (/ 1, 2, 3 /)
2771     b = (/ 4, 5, 6 /)
2772     print '(3i3)', a
2773     print *
2774     print '(3i3)', b
2775     print *
2776     print *, dot_product(a,b)
2777 end program test_dot_prod
2778 @end smallexample
2779 @end table
2780
2781
2782
2783 @node DPROD
2784 @section @code{DPROD} --- Double product function
2785 @cindex @code{DPROD} intrinsic
2786 @cindex double-precision product
2787
2788 @table @asis
2789 @item @emph{Description}:
2790 @code{DPROD(X,Y)} returns the product @code{X*Y}.
2791
2792 @item @emph{Standard}:
2793 F77 and later
2794
2795 @item @emph{Class}:
2796 Elemental function
2797
2798 @item @emph{Syntax}:
2799 @code{RESULT = DPROD(X, Y)}
2800
2801 @item @emph{Arguments}:
2802 @multitable @columnfractions .15 .80
2803 @item @var{X} @tab The type shall be @code{REAL}.
2804 @item @var{Y} @tab The type shall be @code{REAL}.
2805 @end multitable
2806
2807 @item @emph{Return value}:
2808 The return value is of type @code{REAL(8)}.
2809
2810 @item @emph{Example}:
2811 @smallexample
2812 program test_dprod
2813     integer :: i
2814     real :: x = 5.2
2815     real :: y = 2.3
2816     real(8) :: d
2817     d = dprod(x,y)
2818     print *, d
2819 end program test_dprod
2820 @end smallexample
2821 @end table
2822
2823
2824
2825 @node DREAL
2826 @section @code{DREAL} --- Double real part function
2827 @cindex @code{DREAL} intrinsic
2828 @cindex double-precision real part
2829
2830 @table @asis
2831 @item @emph{Description}:
2832 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
2833
2834 @item @emph{Standard}:
2835 GNU extension
2836
2837 @item @emph{Class}:
2838 Elemental function
2839
2840 @item @emph{Syntax}:
2841 @code{RESULT = DREAL(Z)}
2842
2843 @item @emph{Arguments}:
2844 @multitable @columnfractions .15 .80
2845 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
2846 @end multitable
2847
2848 @item @emph{Return value}:
2849 The return value is of type @code{REAL(8)}.
2850
2851 @item @emph{Example}:
2852 @smallexample
2853 program test_dreal
2854     complex(8) :: z = (1.3_8,7.2_8)
2855     print *, dreal(z)
2856 end program test_dreal
2857 @end smallexample
2858
2859 @item @emph{See also}:
2860 @ref{AIMAG}
2861
2862 @end table
2863
2864
2865
2866 @node DTIME
2867 @section @code{DTIME} --- Execution time subroutine (or function)
2868 @cindex @code{DTIME} intrinsic
2869 @cindex time, elapsed
2870 @cindex elapsed time
2871
2872 @table @asis
2873 @item @emph{Description}:
2874 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
2875 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
2876 returns the user and system components of this time in @code{TARRAY(1)} and
2877 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
2878 TARRAY(2)}.
2879
2880 Subsequent invocations of @code{DTIME} return values accumulated since the
2881 previous invocation.
2882
2883 On some systems, the underlying timings are represented using types with
2884 sufficiently small limits that overflows (wrap around) are possible, such as
2885 32-bit types. Therefore, the values returned by this intrinsic might be, or
2886 become, negative, or numerically less than previous values, during a single
2887 run of the compiled program.
2888
2889 If @code{DTIME} is invoked as a function, it can not be invoked as a
2890 subroutine, and vice versa.
2891
2892 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
2893
2894 @multitable @columnfractions .15 .30 .60
2895 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
2896 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
2897 @item @tab @code{RESULT}: @tab Run time since start in seconds.
2898 @end multitable
2899
2900 @item @emph{Standard}:
2901 GNU extension
2902
2903 @item @emph{Class}:
2904 Subroutine
2905
2906 @item @emph{Syntax}:
2907 @multitable @columnfractions .80
2908 @item @code{CALL DTIME(TARRAY, RESULT)}.
2909 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
2910 @end multitable
2911
2912 @item @emph{Arguments}:
2913 @multitable @columnfractions .15 .80
2914 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
2915 @item @var{RESULT}@tab The type shall be @code{REAL}.
2916 @end multitable
2917
2918 @item @emph{Return value}:
2919 Elapsed time in seconds since the start of program execution.
2920
2921 @item @emph{Example}:
2922 @smallexample
2923 program test_dtime
2924     integer(8) :: i, j
2925     real, dimension(2) :: tarray
2926     real :: result
2927     call dtime(tarray, result)
2928     print *, result
2929     print *, tarray(1)
2930     print *, tarray(2)
2931     do i=1,100000000    ! Just a delay
2932         j = i * i - i
2933     end do
2934     call dtime(tarray, result)
2935     print *, result
2936     print *, tarray(1)
2937     print *, tarray(2)
2938 end program test_dtime
2939 @end smallexample
2940 @end table
2941
2942
2943
2944 @node EOSHIFT
2945 @section @code{EOSHIFT} --- End-off shift function
2946 @cindex @code{EOSHIFT} intrinsic
2947 @cindex bit operations
2948
2949 @table @asis
2950 @item @emph{Description}:
2951 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
2952 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
2953 omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type
2954 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
2955 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
2956 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
2957 then all complete rank one sections of @var{ARRAY} along the given dimension are
2958 shifted.  Elements shifted out one end of each rank one section are dropped.  If
2959 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
2960 is copied back in the other end.  If @var{BOUNDARY} is not present then the
2961 following are copied in depending on the type of @var{ARRAY}.
2962
2963 @multitable @columnfractions .15 .80
2964 @item @emph{Array Type} @tab @emph{Boundary Value}
2965 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
2966 @item Logical  @tab @code{.FALSE.}.
2967 @item Character(@var{len}) @tab @var{len} blanks.
2968 @end multitable
2969
2970 @item @emph{Standard}:
2971 F95 and later
2972
2973 @item @emph{Class}:
2974 transformational function
2975
2976 @item @emph{Syntax}:
2977 @code{RESULT = EOSHIFT(A, SHIFT [, BOUNDARY, DIM])}
2978
2979 @item @emph{Arguments}:
2980 @multitable @columnfractions .15 .80
2981 @item @var{ARRAY}  @tab May be any type, not scaler.
2982 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
2983 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
2984 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
2985 @end multitable
2986
2987 @item @emph{Return value}:
2988 Returns an array of same type and rank as the @var{ARRAY} argument.
2989
2990 @item @emph{Example}:
2991 @smallexample
2992 program test_eoshift
2993     integer, dimension(3,3) :: a
2994     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2995     print '(3i3)', a(1,:)
2996     print '(3i3)', a(2,:)
2997     print '(3i3)', a(3,:)
2998     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
2999     print *
3000     print '(3i3)', a(1,:)
3001     print '(3i3)', a(2,:)
3002     print '(3i3)', a(3,:)
3003 end program test_eoshift
3004 @end smallexample
3005 @end table
3006
3007
3008
3009 @node EPSILON
3010 @section @code{EPSILON} --- Epsilon function
3011 @cindex @code{EPSILON} intrinsic
3012 @cindex epsilon, significant
3013
3014 @table @asis
3015 @item @emph{Description}:
3016 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3017
3018 @item @emph{Standard}:
3019 F95 and later
3020
3021 @item @emph{Class}:
3022 Inquiry function
3023
3024 @item @emph{Syntax}:
3025 @code{RESULT = EPSILON(X)}
3026
3027 @item @emph{Arguments}:
3028 @multitable @columnfractions .15 .80
3029 @item @var{X} @tab The type shall be @code{REAL(*)}.
3030 @end multitable
3031
3032 @item @emph{Return value}:
3033 The return value is of same type as the argument.
3034
3035 @item @emph{Example}:
3036 @smallexample
3037 program test_epsilon
3038     real :: x = 3.143
3039     real(8) :: y = 2.33
3040     print *, EPSILON(x)
3041     print *, EPSILON(y)
3042 end program test_epsilon
3043 @end smallexample
3044 @end table
3045
3046
3047
3048 @node ERF
3049 @section @code{ERF} --- Error function
3050 @cindex @code{ERF} intrinsic
3051 @cindex error function
3052
3053 @table @asis
3054 @item @emph{Description}:
3055 @code{ERF(X)} computes the error function of @var{X}.
3056
3057 @item @emph{Standard}:
3058 GNU Extension
3059
3060 @item @emph{Class}:
3061 Elemental function
3062
3063 @item @emph{Syntax}:
3064 @code{RESULT = ERF(X)}
3065
3066 @item @emph{Arguments}:
3067 @multitable @columnfractions .15 .80
3068 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3069 @end multitable
3070
3071 @item @emph{Return value}:
3072 The return value is a scalar of type @code{REAL(*)} and it is positive
3073 (@math{ - 1 \leq erf (x) \leq 1 }.
3074
3075 @item @emph{Example}:
3076 @smallexample
3077 program test_erf
3078   real(8) :: x = 0.17_8
3079   x = erf(x)
3080 end program test_erf
3081 @end smallexample
3082
3083 @item @emph{Specific names}:
3084 @multitable @columnfractions .20 .20 .20 .40
3085 @item Name            @tab Argument          @tab Return type       @tab Standard
3086 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3087 @end multitable
3088 @end table
3089
3090
3091
3092 @node ERFC
3093 @section @code{ERFC} --- Error function
3094 @cindex @code{ERFC} intrinsic
3095 @cindex error function
3096
3097 @table @asis
3098 @item @emph{Description}:
3099 @code{ERFC(X)} computes the complementary 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 = ERFC(X)}
3109
3110 @item @emph{Arguments}:
3111 @multitable @columnfractions .15 .80
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{ 0 \leq erfc (x) \leq 2 }.
3118
3119 @item @emph{Example}:
3120 @smallexample
3121 program test_erfc
3122   real(8) :: x = 0.17_8
3123   x = erfc(x)
3124 end program test_erfc
3125 @end smallexample
3126
3127 @item @emph{Specific names}:
3128 @multitable @columnfractions .20 .20 .20 .40
3129 @item Name            @tab Argument          @tab Return type       @tab Standard
3130 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3131 @end multitable
3132 @end table
3133
3134
3135
3136 @node ETIME
3137 @section @code{ETIME} --- Execution time subroutine (or function)
3138 @cindex @code{ETIME} intrinsic
3139 @cindex time, elapsed
3140
3141 @table @asis
3142 @item @emph{Description}:
3143 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3144 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
3145 returns the user and system components of this time in @code{TARRAY(1)} and
3146 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3147
3148 On some systems, the underlying timings are represented using types with
3149 sufficiently small limits that overflows (wrap around) are possible, such as
3150 32-bit types. Therefore, the values returned by this intrinsic might be, or
3151 become, negative, or numerically less than previous values, during a single
3152 run of the compiled program.
3153
3154 If @code{ETIME} is invoked as a function, it can not be invoked as a
3155 subroutine, and vice versa.
3156
3157 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3158
3159 @multitable @columnfractions .15 .30 .60
3160 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3161 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3162 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3163 @end multitable
3164
3165 @item @emph{Standard}:
3166 GNU extension
3167
3168 @item @emph{Class}:
3169 Subroutine
3170
3171 @item @emph{Syntax}:
3172 @multitable @columnfractions .8
3173 @item @code{CALL ETIME(TARRAY, RESULT)}.
3174 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3175 @end multitable
3176
3177 @item @emph{Arguments}:
3178 @multitable @columnfractions .15 .80
3179 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3180 @item @var{RESULT}@tab The type shall be @code{REAL}.
3181 @end multitable
3182
3183 @item @emph{Return value}:
3184 Elapsed time in seconds since the start of program execution.
3185
3186 @item @emph{Example}:
3187 @smallexample
3188 program test_etime
3189     integer(8) :: i, j
3190     real, dimension(2) :: tarray
3191     real :: result
3192     call ETIME(tarray, result)
3193     print *, result
3194     print *, tarray(1)
3195     print *, tarray(2)
3196     do i=1,100000000    ! Just a delay
3197         j = i * i - i
3198     end do
3199     call ETIME(tarray, result)
3200     print *, result
3201     print *, tarray(1)
3202     print *, tarray(2)
3203 end program test_etime
3204 @end smallexample
3205
3206 @item @emph{See also}:
3207 @ref{CPU_TIME}
3208
3209 @end table
3210
3211
3212
3213 @node EXIT
3214 @section @code{EXIT} --- Exit the program with status.
3215 @cindex @code{EXIT} intrinsic
3216 @cindex exit program
3217
3218 @table @asis
3219 @item @emph{Description}:
3220 @code{EXIT} causes immediate termination of the program with status.  If status
3221 is omitted it returns the canonical @emph{success} for the system.  All Fortran
3222 I/O units are closed.
3223
3224 @item @emph{Standard}:
3225 GNU extension
3226
3227 @item @emph{Class}:
3228 Subroutine
3229
3230 @item @emph{Syntax}:
3231 @code{CALL EXIT([STATUS])}
3232
3233 @item @emph{Arguments}:
3234 @multitable @columnfractions .15 .80
3235 @item @var{STATUS} @tab The type of the argument shall be @code{INTEGER(*)}.
3236 @end multitable
3237
3238 @item @emph{Return value}:
3239 @code{STATUS} is passed to the parent process on exit.
3240
3241 @item @emph{Example}:
3242 @smallexample
3243 program test_exit
3244   integer :: STATUS = 0
3245   print *, 'This program is going to exit.'
3246   call EXIT(STATUS)
3247 end program test_exit
3248 @end smallexample
3249
3250 @item @emph{See also}:
3251 @ref{ABORT}, @ref{KILL}
3252 @end table
3253
3254
3255
3256 @node EXP
3257 @section @code{EXP} --- Exponential function
3258 @cindex @code{EXP} intrinsic
3259 @cindex @code{DEXP} intrinsic
3260 @cindex @code{ZEXP} intrinsic
3261 @cindex @code{CDEXP} intrinsic
3262 @cindex exponential
3263
3264 @table @asis
3265 @item @emph{Description}:
3266 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3267
3268 @item @emph{Standard}:
3269 F77 and later, has overloads that are GNU extensions
3270
3271 @item @emph{Class}:
3272 Elemental function
3273
3274 @item @emph{Syntax}:
3275 @code{RESULT = EXP(X)}
3276
3277 @item @emph{Arguments}:
3278 @multitable @columnfractions .15 .80
3279 @item @var{X} @tab The type shall be @code{REAL(*)} or
3280 @code{COMPLEX(*)}.
3281 @end multitable
3282
3283 @item @emph{Return value}:
3284 The return value has same type and kind as @var{X}.
3285
3286 @item @emph{Example}:
3287 @smallexample
3288 program test_exp
3289   real :: x = 1.0
3290   x = exp(x)
3291 end program test_exp
3292 @end smallexample
3293
3294 @item @emph{Specific names}:
3295 @multitable @columnfractions .20 .20 .20 .40
3296 @item Name            @tab Argument             @tab Return type         @tab Standard
3297 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab F77 and later
3298 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab F77 and later
3299 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3300 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3301 @end multitable
3302 @end table
3303
3304
3305
3306 @node EXPONENT
3307 @section @code{EXPONENT} --- Exponent function
3308 @cindex @code{EXPONENT} intrinsic
3309 @cindex exponent part of a real number
3310
3311 @table @asis
3312 @item @emph{Description}:
3313 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3314 is zero the value returned is zero.
3315
3316 @item @emph{Standard}:
3317 F95 and later
3318
3319 @item @emph{Class}:
3320 Elemental function
3321
3322 @item @emph{Syntax}:
3323 @code{RESULT = EXPONENT(X)}
3324
3325 @item @emph{Arguments}:
3326 @multitable @columnfractions .15 .80
3327 @item @var{X} @tab The type shall be @code{REAL(*)}.
3328 @end multitable
3329
3330 @item @emph{Return value}:
3331 The return value is of type default @code{INTEGER}.
3332
3333 @item @emph{Example}:
3334 @smallexample
3335 program test_exponent
3336   real :: x = 1.0
3337   integer :: i
3338   i = exponent(x)
3339   print *, i
3340   print *, exponent(0.0)
3341 end program test_exponent
3342 @end smallexample
3343 @end table
3344
3345
3346 @node FDATE
3347 @section @code{FDATE} --- Get the current time as a string
3348 @cindex @code{FDATE} intrinsic
3349 @cindex time, current
3350 @cindex current time
3351 @cindex date, current
3352 @cindex current date
3353
3354 @table @asis
3355 @item @emph{Description}:
3356 @code{FDATE(DATE)} returns the current date (using the same format as
3357 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3358 TIME())}.
3359
3360 If @code{FDATE} is invoked as a function, it can not be invoked as a
3361 subroutine, and vice versa.
3362
3363 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3364
3365 @item @emph{Standard}:
3366 GNU extension
3367
3368 @item @emph{Class}:
3369 Subroutine
3370
3371 @item @emph{Syntax}:
3372 @multitable @columnfractions .80
3373 @item @code{CALL FDATE(DATE)}.
3374 @item @code{DATE = FDATE()}, (not recommended).
3375 @end multitable
3376
3377 @item @emph{Arguments}:
3378 @multitable @columnfractions .15 .80
3379 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3380 @end multitable
3381
3382 @item @emph{Return value}:
3383 The current date as a string.
3384
3385 @item @emph{Example}:
3386 @smallexample
3387 program test_fdate
3388     integer(8) :: i, j
3389     character(len=30) :: date
3390     call fdate(date)
3391     print *, 'Program started on ', date
3392     do i = 1, 100000000 ! Just a delay
3393         j = i * i - i
3394     end do
3395     call fdate(date)
3396     print *, 'Program ended on ', date
3397 end program test_fdate
3398 @end smallexample
3399 @end table
3400
3401 @node FLOAT
3402
3403 @section @code{FLOAT} --- Convert integer to default real
3404 @cindex @code{FLOAT} intrinsic
3405 @cindex conversion function (float)
3406
3407 @table @asis
3408 @item @emph{Description}:
3409 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3410
3411 @item @emph{Standard}:
3412 GNU extension
3413
3414 @item @emph{Class}:
3415 Elemental function
3416
3417 @item @emph{Syntax}:
3418 @code{RESULT = FLOAT(I)}
3419
3420 @item @emph{Arguments}:
3421 @multitable @columnfractions .15 .80
3422 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3423 @end multitable
3424
3425 @item @emph{Return value}:
3426 The return value is of type default @code{REAL}.
3427
3428 @item @emph{Example}:
3429 @smallexample
3430 program test_float
3431     integer :: i = 1
3432     if (float(i) /= 1.) call abort
3433 end program test_float
3434 @end smallexample
3435
3436 @item @emph{See also}:
3437 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3438 @end table
3439
3440
3441
3442 @node FGET
3443 @section @code{FGET} --- Read a single character in stream mode from stdin
3444 @cindex @code{FGET} intrinsic
3445 @cindex file operations
3446 @cindex stream operations
3447
3448 @table @asis
3449 @item @emph{Description}:
3450 Read a single character in stream mode from stdin by bypassing normal
3451 formatted output. Stream I/O should not be mixed with normal record-oriented
3452 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3453
3454 This intrinsic routine is provided for backwards compatibility with
3455 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
3456 Programmers should consider the use of new stream IO feature in new code
3457 for future portability. See also @ref{Fortran 2003 status}.
3458
3459 @item @emph{Standard}:
3460 GNU extension
3461
3462 @item @emph{Class}:
3463 Non-elemental subroutine
3464
3465 @item @emph{Syntax}:
3466 @code{CALL FGET(C [, STATUS])}
3467
3468 @item @emph{Arguments}:
3469 @multitable @columnfractions .15 .80
3470 @item @var{C}      @tab The type shall be @code{CHARACTER}.
3471 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3472                         Returns 0 on success, -1 on end-of-file, and a
3473                         system specific positive error code otherwise.
3474 @end multitable
3475
3476 @item @emph{Example}:
3477 @smallexample
3478 PROGRAM test_fget
3479   INTEGER, PARAMETER :: strlen = 100
3480   INTEGER :: status, i = 1
3481   CHARACTER(len=strlen) :: str = ""
3482
3483   WRITE (*,*) 'Enter text:'
3484   DO
3485     CALL fget(str(i:i), status)
3486     if (status /= 0 .OR. i > strlen) exit
3487     i = i + 1
3488   END DO
3489   WRITE (*,*) TRIM(str)
3490 END PROGRAM
3491 @end smallexample
3492
3493 @item @emph{See also}:
3494 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
3495 @end table
3496
3497
3498 @node FGETC
3499 @section @code{FGETC} --- Read a single character in stream mode
3500 @cindex @code{FGETC} intrinsic
3501 @cindex file operations
3502 @cindex stream operations
3503
3504 @table @asis
3505 @item @emph{Description}:
3506 Read a single character in stream mode by bypassing normal formatted output.
3507 Stream I/O should not be mixed with normal record-oriented (formatted or
3508 unformatted) I/O on the same unit; the results are unpredictable.
3509
3510 This intrinsic routine is provided for backwards compatibility with
3511 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
3512 Programmers should consider the use of new stream IO feature in new code
3513 for future portability. See also @ref{Fortran 2003 status}.
3514
3515 @item @emph{Standard}:
3516 GNU extension
3517
3518 @item @emph{Class}:
3519 Non-elemental subroutine
3520
3521 @item @emph{Syntax}:
3522 @code{CALL FGETC(UNIT, C [, STATUS])}
3523
3524 @item @emph{Arguments}:
3525 @multitable @columnfractions .15 .80
3526 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
3527 @item @var{C}      @tab The type shall be @code{CHARACTER}.
3528 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3529                         -1 on end-of-file and a system specific positive error code otherwise.
3530 @end multitable
3531
3532 @item @emph{Example}:
3533 @smallexample
3534 PROGRAM test_fgetc
3535   INTEGER :: fd = 42, status
3536   CHARACTER :: c
3537
3538   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
3539   DO
3540     CALL fgetc(fd, c, status)
3541     IF (status /= 0) EXIT
3542     call fput(c)
3543   END DO
3544   CLOSE(UNIT=fd)
3545 END PROGRAM
3546 @end smallexample
3547
3548 @item @emph{See also}:
3549 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
3550 @end table
3551
3552
3553
3554 @node FLOOR
3555 @section @code{FLOOR} --- Integer floor function
3556 @cindex @code{FLOOR} intrinsic
3557 @cindex floor
3558
3559 @table @asis
3560 @item @emph{Description}:
3561 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
3562
3563 @item @emph{Standard}:
3564 F95 and later
3565
3566 @item @emph{Class}:
3567 Elemental function
3568
3569 @item @emph{Syntax}:
3570 @code{RESULT = FLOOR(X [, KIND])}
3571
3572 @item @emph{Arguments}:
3573 @multitable @columnfractions .15 .80
3574 @item @var{X} @tab The type shall be @code{REAL(*)}.
3575 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
3576                       expression indicating the kind parameter of
3577                       the result.
3578 @end multitable
3579
3580 @item @emph{Return value}:
3581 The return value is of type @code{INTEGER(KIND)}
3582
3583 @item @emph{Example}:
3584 @smallexample
3585 program test_floor
3586     real :: x = 63.29
3587     real :: y = -63.59
3588     print *, floor(x) ! returns 63
3589     print *, floor(y) ! returns -64
3590 end program test_floor
3591 @end smallexample
3592
3593 @item @emph{See also}:
3594 @ref{CEILING}, @ref{NINT}
3595
3596 @end table
3597
3598
3599
3600 @node FLUSH
3601 @section @code{FLUSH} --- Flush I/O unit(s)
3602 @cindex @code{FLUSH} intrinsic
3603 @cindex flush output files
3604
3605 @table @asis
3606 @item @emph{Description}:
3607 Flushes Fortran unit(s) currently open for output. Without the optional
3608 argument, all units are flushed, otherwise just the unit specified.
3609
3610 @item @emph{Standard}:
3611 GNU extension
3612
3613 @item @emph{Class}:
3614 non-elemental subroutine
3615
3616 @item @emph{Syntax}:
3617 @code{CALL FLUSH(UNIT)}
3618
3619 @item @emph{Arguments}:
3620 @multitable @columnfractions .15 .80
3621 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
3622 @end multitable
3623
3624 @item @emph{Note}:
3625 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
3626 statement that should be preferred over the @code{FLUSH} intrinsic.
3627
3628 @end table
3629
3630
3631
3632 @node FNUM
3633 @section @code{FNUM} --- File number function
3634 @cindex @code{FNUM} intrinsic
3635 @cindex fnum
3636
3637 @table @asis
3638 @item @emph{Description}:
3639 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
3640 open Fortran I/O unit @code{UNIT}.
3641
3642 @item @emph{Standard}:
3643 GNU extension
3644
3645 @item @emph{Class}:
3646 non-elemental function
3647
3648 @item @emph{Syntax}:
3649 @code{RESULT = FNUM(UNIT)}
3650
3651 @item @emph{Arguments}:
3652 @multitable @columnfractions .15 .80
3653 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3654 @end multitable
3655
3656 @item @emph{Return value}:
3657 The return value is of type @code{INTEGER}
3658
3659 @item @emph{Example}:
3660 @smallexample
3661 program test_fnum
3662   integer :: i
3663   open (unit=10, status = "scratch")
3664   i = fnum(10)
3665   print *, i
3666   close (10)
3667 end program test_fnum
3668 @end smallexample
3669 @end table
3670
3671
3672
3673 @node FPUT
3674 @section @code{FPUT} --- Write a single character in stream mode to stdout
3675 @cindex @code{FPUT} intrinsic
3676 @cindex file operations
3677 @cindex stream operations
3678
3679 @table @asis
3680 @item @emph{Description}:
3681 Write a single character in stream mode to stdout by bypassing normal
3682 formatted output. Stream I/O should not be mixed with normal record-oriented
3683 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3684
3685 This intrinsic routine is provided for backwards compatibility with
3686 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
3687 Programmers should consider the use of new stream IO feature in new code
3688 for future portability. See also @ref{Fortran 2003 status}.
3689
3690 @item @emph{Standard}:
3691 GNU extension
3692
3693 @item @emph{Class}:
3694 Non-elemental subroutine
3695
3696 @item @emph{Syntax}:
3697 @code{CALL FPUT(C [, STATUS])}
3698
3699 @item @emph{Arguments}:
3700 @multitable @columnfractions .15 .80
3701 @item @var{C}      @tab The type shall be @code{CHARACTER}.
3702 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3703                         -1 on end-of-file and a system specific positive error code otherwise.
3704 @end multitable
3705
3706 @item @emph{Example}:
3707 @smallexample
3708 PROGRAM test_fput
3709   CHARACTER(len=*) :: str = "gfortran"
3710   INTEGER :: i
3711   DO i = 1, len_trim(str)
3712     CALL fput(str(i:i))
3713   END DO
3714 END PROGRAM
3715 @end smallexample
3716
3717 @item @emph{See also}:
3718 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
3719 @end table
3720
3721
3722
3723 @node FPUTC
3724 @section @code{FPUTC} --- Write a single character in stream mode
3725 @cindex @code{FPUTC} intrinsic
3726 @cindex file operations
3727 @cindex stream operations
3728
3729 @table @asis
3730 @item @emph{Description}:
3731 Write&