gcc/fortran/intrinsic.texi

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