gcc/fortran/intrinsic.texi

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