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