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