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