gcc/fortran/intrinsic.texi

   1 @ignore
   2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
   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.3 or
   9 any later version published by the Free Software Foundation; with the
  10 Invariant Sections being ``Funding Free Software'', the Front-Cover
  11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
  12 (see below).  A copy of the license is included in the gfdl(7) man page.
  13
  14
  15 Some basic guidelines for editing this document:
  16
  17   (1) The intrinsic procedures are to be listed in alphabetical order.
  18   (2) The generic name is to be used.
  19   (3) The specific names are included in the function index and in a
  20       table at the end of the node (See ABS entry).
  21   (4) Try to maintain the same style for each entry.
  22
  23
  24 @end ignore
  25
  26 @tex
  27 \gdef\acos{\mathop{\rm acos}\nolimits}
  28 \gdef\asin{\mathop{\rm asin}\nolimits}
  29 \gdef\atan{\mathop{\rm atan}\nolimits}
  30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
  31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
  32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
  33 @end tex
  34
  35
  36 @node Intrinsic Procedures
  37 @chapter Intrinsic Procedures
  38 @cindex intrinsic procedures
  39
  40 @menu
  41 * Introduction:         Introduction to Intrinsics
  42 * @code{ABORT}:         ABORT,     Abort the program
  43 * @code{ABS}:           ABS,       Absolute value
  44 * @code{ACCESS}:        ACCESS,    Checks file access modes
  45 * @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
  46 * @code{ACOS}:          ACOS,      Arccosine function
  47 * @code{ACOSH}:         ACOSH,     Inverse hyperbolic cosine function
  48 * @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
  49 * @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
  50 * @code{AIMAG}:         AIMAG,     Imaginary part of complex number
  51 * @code{AINT}:          AINT,      Truncate to a whole number
  52 * @code{ALARM}:         ALARM,     Set an alarm clock
  53 * @code{ALL}:           ALL,       Determine if all values are true
  54 * @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
  55 * @code{AND}:           AND,       Bitwise logical AND
  56 * @code{ANINT}:         ANINT,     Nearest whole number
  57 * @code{ANY}:           ANY,       Determine if any values are true
  58 * @code{ASIN}:          ASIN,      Arcsine function
  59 * @code{ASINH}:         ASINH,     Inverse hyperbolic sine function
  60 * @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
  61 * @code{ATAN}:          ATAN,      Arctangent function
  62 * @code{ATAN2}:         ATAN2,     Arctangent function
  63 * @code{ATANH}:         ATANH,     Inverse hyperbolic tangent function
  64 * @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
  65 * @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
  66 * @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
  67 * @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
  68 * @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
  69 * @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
  70 * @code{BGE}:           BGE,       Bitwise greater than or equal to
  71 * @code{BGT}:           BGT,       Bitwise greater than
  72 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
  73 * @code{BLE}:           BLE,       Bitwise less than or equal to
  74 * @code{BLT}:           BLT,       Bitwise less than
  75 * @code{BTEST}:         BTEST,     Bit test function
  76 * @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
  77 * @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
  78 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
  79 * @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
  80 * @code{C_LOC}:         C_LOC,     Obtain the C address of an object
  81 * @code{C_SIZEOF}:      C_SIZEOF,  Size in bytes of an expression
  82 * @code{CEILING}:       CEILING,   Integer ceiling function
  83 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
  84 * @code{CHDIR}:         CHDIR,     Change working directory
  85 * @code{CHMOD}:         CHMOD,     Change access permissions of files
  86 * @code{CMPLX}:         CMPLX,     Complex conversion function
  87 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
  88 * @code{COMPLEX}:       COMPLEX,   Complex conversion function
  89 * @code{CONJG}:         CONJG,     Complex conjugate function
  90 * @code{COS}:           COS,       Cosine function
  91 * @code{COSH}:          COSH,      Hyperbolic cosine function
  92 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
  93 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
  94 * @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
  95 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
  96 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
  97 * @code{DBLE}:          DBLE,      Double precision conversion function
  98 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
  99 * @code{DIGITS}:        DIGITS,    Significant digits function
 100 * @code{DIM}:           DIM,       Positive difference
 101 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
 102 * @code{DPROD}:         DPROD,     Double product function
 103 * @code{DREAL}:         DREAL,     Double real part function
 104 * @code{DSHIFTL}:       DSHIFTL,   Combined left shift
 105 * @code{DSHIFTR}:       DSHIFTR,   Combined right shift
 106 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
 107 * @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
 108 * @code{EPSILON}:       EPSILON,   Epsilon function
 109 * @code{ERF}:           ERF,       Error function
 110 * @code{ERFC}:          ERFC,      Complementary error function
 111 * @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
 112 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
 113 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
 114 * @code{EXIT}:          EXIT,      Exit the program with status.
 115 * @code{EXP}:           EXP,       Exponential function
 116 * @code{EXPONENT}:      EXPONENT,  Exponent function
 117 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF,  Query dynamic type for extension
 118 * @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
 119 * @code{FGET}:          FGET,      Read a single character in stream mode from stdin
 120 * @code{FGETC}:         FGETC,     Read a single character in stream mode
 121 * @code{FLOOR}:         FLOOR,     Integer floor function
 122 * @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
 123 * @code{FNUM}:          FNUM,      File number function
 124 * @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
 125 * @code{FPUTC}:         FPUTC,     Write a single character in stream mode
 126 * @code{FRACTION}:      FRACTION,  Fractional part of the model representation
 127 * @code{FREE}:          FREE,      Memory de-allocation subroutine
 128 * @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
 129 * @code{FSTAT}:         FSTAT,     Get file status
 130 * @code{FTELL}:         FTELL,     Current stream position
 131 * @code{GAMMA}:         GAMMA,     Gamma function
 132 * @code{GERROR}:        GERROR,    Get last system error message
 133 * @code{GETARG}:        GETARG,    Get command line arguments
 134 * @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
 135 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
 136 * @code{GETCWD}:        GETCWD,    Get current working directory
 137 * @code{GETENV}:        GETENV,    Get an environmental variable
 138 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
 139 * @code{GETGID}:        GETGID,    Group ID function
 140 * @code{GETLOG}:        GETLOG,    Get login name
 141 * @code{GETPID}:        GETPID,    Process ID function
 142 * @code{GETUID}:        GETUID,    User ID function
 143 * @code{GMTIME}:        GMTIME,    Convert time to GMT info
 144 * @code{HOSTNM}:        HOSTNM,    Get system host name
 145 * @code{HUGE}:          HUGE,      Largest number of a kind
 146 * @code{HYPOT}:         HYPOT,     Euclidian distance function
 147 * @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
 148 * @code{IALL}:          IALL,      Bitwise AND of array elements
 149 * @code{IAND}:          IAND,      Bitwise logical and
 150 * @code{IANY}:          IANY,      Bitwise OR of array elements
 151 * @code{IARGC}:         IARGC,     Get the number of command line arguments
 152 * @code{IBCLR}:         IBCLR,     Clear bit
 153 * @code{IBITS}:         IBITS,     Bit extraction
 154 * @code{IBSET}:         IBSET,     Set bit
 155 * @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
 156 * @code{IDATE}:         IDATE,     Current local time (day/month/year)
 157 * @code{IEOR}:          IEOR,      Bitwise logical exclusive or
 158 * @code{IERRNO}:        IERRNO,    Function to get the last system error number
 159 * @code{IMAGE_INDEX}:   IMAGE_INDEX, Cosubscript to image index convertion
 160 * @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
 161 * @code{INT}:           INT,       Convert to integer type
 162 * @code{INT2}:          INT2,      Convert to 16-bit integer type
 163 * @code{INT8}:          INT8,      Convert to 64-bit integer type
 164 * @code{IOR}:           IOR,       Bitwise logical or
 165 * @code{IPARITY}:       IPARITY,   Bitwise XOR of array elements
 166 * @code{IRAND}:         IRAND,     Integer pseudo-random number
 167 * @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
 168 * @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
 169 * @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
 170 * @code{ISHFT}:         ISHFT,     Shift bits
 171 * @code{ISHFTC}:        ISHFTC,    Shift bits circularly
 172 * @code{ISNAN}:         ISNAN,     Tests for a NaN
 173 * @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
 174 * @code{KILL}:          KILL,      Send a signal to a process
 175 * @code{KIND}:          KIND,      Kind of an entity
 176 * @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
 177 * @code{LCOBOUND}:      LCOBOUND,  Lower codimension bounds of an array
 178 * @code{LEADZ}:         LEADZ,     Number of leading zero bits of an integer
 179 * @code{LEN}:           LEN,       Length of a character entity
 180 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
 181 * @code{LGE}:           LGE,       Lexical greater than or equal
 182 * @code{LGT}:           LGT,       Lexical greater than
 183 * @code{LINK}:          LINK,      Create a hard link
 184 * @code{LLE}:           LLE,       Lexical less than or equal
 185 * @code{LLT}:           LLT,       Lexical less than
 186 * @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
 187 * @code{LOC}:           LOC,       Returns the address of a variable
 188 * @code{LOG}:           LOG,       Logarithm function
 189 * @code{LOG10}:         LOG10,     Base 10 logarithm function
 190 * @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
 191 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
 192 * @code{LONG}:          LONG,      Convert to integer type
 193 * @code{LSHIFT}:        LSHIFT,    Left shift bits
 194 * @code{LSTAT}:         LSTAT,     Get file status
 195 * @code{LTIME}:         LTIME,     Convert time to local time info
 196 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
 197 * @code{MASKL}:         MASKL,     Left justified mask
 198 * @code{MASKR}:         MASKR,     Right justified mask
 199 * @code{MATMUL}:        MATMUL,    matrix multiplication
 200 * @code{MAX}:           MAX,       Maximum value of an argument list
 201 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
 202 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
 203 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
 204 * @code{MCLOCK}:        MCLOCK,    Time function
 205 * @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
 206 * @code{MERGE}:         MERGE,     Merge arrays
 207 * @code{MERGE_BITS}:    MERGE_BITS, Merge of bits under mask
 208 * @code{MIN}:           MIN,       Minimum value of an argument list
 209 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
 210 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
 211 * @code{MINVAL}:        MINVAL,    Minimum value of an array
 212 * @code{MOD}:           MOD,       Remainder function
 213 * @code{MODULO}:        MODULO,    Modulo function
 214 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
 215 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
 216 * @code{NEAREST}:       NEAREST,   Nearest representable number
 217 * @code{NEW_LINE}:      NEW_LINE,  New line character
 218 * @code{NINT}:          NINT,      Nearest whole number
 219 * @code{NORM2}:         NORM2,     Euclidean vector norm
 220 * @code{NOT}:           NOT,       Logical negation
 221 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
 222 * @code{NUM_IMAGES}:    NUM_IMAGES, Number of images
 223 * @code{OR}:            OR,        Bitwise logical OR
 224 * @code{PACK}:          PACK,      Pack an array into an array of rank one
 225 * @code{PARITY}:        PARITY,    Reduction with exclusive OR
 226 * @code{PERROR}:        PERROR,    Print system error message
 227 * @code{POPCNT}:        POPCNT,    Number of bits set
 228 * @code{POPPAR}:        POPPAR,    Parity of the number of bits set
 229 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
 230 * @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
 231 * @code{PRODUCT}:       PRODUCT,   Product of array elements
 232 * @code{RADIX}:         RADIX,     Base of a data model
 233 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
 234 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
 235 * @code{RAND}:          RAND,      Real pseudo-random number
 236 * @code{RANGE}:         RANGE,     Decimal exponent range
 237 * @code{RAN}:           RAN,       Real pseudo-random number
 238 * @code{REAL}:          REAL,      Convert to real type
 239 * @code{RENAME}:        RENAME,    Rename a file
 240 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
 241 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
 242 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
 243 * @code{RSHIFT}:        RSHIFT,    Right shift bits
 244 * @code{SAME_TYPE_AS}:  SAME_TYPE_AS,  Query dynamic types for equality
 245 * @code{SCALE}:         SCALE,     Scale a real value
 246 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
 247 * @code{SECNDS}:        SECNDS,    Time function
 248 * @code{SECOND}:        SECOND,    CPU time function
 249 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
 250 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
 251 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
 252 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
 253 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
 254 * @code{SHIFTA}:        SHIFTA,    Right shift with fill
 255 * @code{SHIFTL}:        SHIFTL,    Left shift
 256 * @code{SHIFTR}:        SHIFTR,    Right shift
 257 * @code{SIGN}:          SIGN,      Sign copying function
 258 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
 259 * @code{SIN}:           SIN,       Sine function
 260 * @code{SINH}:          SINH,      Hyperbolic sine function
 261 * @code{SIZE}:          SIZE,      Function to determine the size of an array
 262 * @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
 263 * @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
 264 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
 265 * @code{SPREAD}:        SPREAD,    Add a dimension to an array
 266 * @code{SQRT}:          SQRT,      Square-root function
 267 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
 268 * @code{STAT}:          STAT,      Get file status
 269 * @code{STORAGE_SIZE}:  STORAGE_SIZE, Storage size in bits
 270 * @code{SUM}:           SUM,       Sum of array elements
 271 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
 272 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
 273 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
 274 * @code{TAN}:           TAN,       Tangent function
 275 * @code{TANH}:          TANH,      Hyperbolic tangent function
 276 * @code{THIS_IMAGE}:    THIS_IMAGE, Cosubscript index of this image
 277 * @code{TIME}:          TIME,      Time function
 278 * @code{TIME8}:         TIME8,     Time function (64-bit)
 279 * @code{TINY}:          TINY,      Smallest positive number of a real kind
 280 * @code{TRAILZ}:        TRAILZ,    Number of trailing zero bits of an integer
 281 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
 282 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
 283 * @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
 284 * @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
 285 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
 286 * @code{UCOBOUND}:      UCOBOUND,  Upper codimension bounds of an array
 287 * @code{UMASK}:         UMASK,     Set the file creation mask
 288 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
 289 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
 290 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
 291 * @code{XOR}:           XOR,       Bitwise logical exclusive or
 292 @end menu
 293
 294 @node Introduction to Intrinsics
 295 @section Introduction to intrinsic procedures
 296
 297 The intrinsic procedures provided by GNU Fortran include all of the
 298 intrinsic procedures required by the Fortran 95 standard, a set of
 299 intrinsic procedures for backwards compatibility with G77, and a
 300 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
 301 standards.  Any conflict between a description here and a description in
 302 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
 303 2008 standard is unintentional, and the standard(s) should be considered
 304 authoritative.
 305
 306 The enumeration of the @code{KIND} type parameter is processor defined in
 307 the Fortran 95 standard.  GNU Fortran defines the default integer type and
 308 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 309 respectively.  The standard mandates that both data types shall have
 310 another kind, which have more precision.  On typical target architectures
 311 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 312 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 313 In the description of generic intrinsic procedures, the kind type parameter
 314 will be specified by @code{KIND=*}, and in the description of specific
 315 names for an intrinsic procedure the kind type parameter will be explicitly
 316 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
 317 brevity the optional @code{KIND=} syntax will be omitted.
 318
 319 Many of the intrinsic procedures take one or more optional arguments.
 320 This document follows the convention used in the Fortran 95 standard,
 321 and denotes such arguments by square brackets.
 322
 323 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
 324 which can be used to restrict the set of intrinsic procedures to a
 325 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
 326 option, and so all intrinsic procedures described here are accepted.  There
 327 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 328 implemented both a function and a subroutine.  Both classes
 329 have been implemented in @command{gfortran} for backwards compatibility
 330 with @command{g77}.  It is noted here that these functions and subroutines
 331 cannot be intermixed in a given subprogram.  In the descriptions that follow,
 332 the applicable standard for each intrinsic procedure is noted.
 333
 334
 335
 336 @node ABORT
 337 @section @code{ABORT} --- Abort the program
 338 @fnindex ABORT
 339 @cindex program termination, with core dump
 340 @cindex terminate program, with core dump
 341 @cindex core, dump
 342
 343 @table @asis
 344 @item @emph{Description}:
 345 @code{ABORT} causes immediate termination of the program.  On operating
 346 systems that support a core dump, @code{ABORT} will produce a core dump even if
 347 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
 348 purposes.
 349 @c TODO: Check if this (with -fno-dump-core) is correct.
 350
 351 @item @emph{Standard}:
 352 GNU extension
 353
 354 @item @emph{Class}:
 355 Subroutine
 356
 357 @item @emph{Syntax}:
 358 @code{CALL ABORT}
 359
 360 @item @emph{Return value}:
 361 Does not return.
 362
 363 @item @emph{Example}:
 364 @smallexample
 365 program test_abort
 366   integer :: i = 1, j = 2
 367   if (i /= j) call abort
 368 end program test_abort
 369 @end smallexample
 370
 371 @item @emph{See also}:
 372 @ref{EXIT}, @ref{KILL}
 373
 374 @end table
 375
 376
 377
 378 @node ABS
 379 @section @code{ABS} --- Absolute value
 380 @fnindex ABS
 381 @fnindex CABS
 382 @fnindex DABS
 383 @fnindex IABS
 384 @fnindex ZABS
 385 @fnindex CDABS
 386 @cindex absolute value
 387
 388 @table @asis
 389 @item @emph{Description}:
 390 @code{ABS(A)} computes the absolute value of @code{A}.
 391
 392 @item @emph{Standard}:
 393 Fortran 77 and later, has overloads that are GNU extensions
 394
 395 @item @emph{Class}:
 396 Elemental function
 397
 398 @item @emph{Syntax}:
 399 @code{RESULT = ABS(A)}
 400
 401 @item @emph{Arguments}:
 402 @multitable @columnfractions .15 .70
 403 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
 404 @code{REAL}, or @code{COMPLEX}.
 405 @end multitable
 406
 407 @item @emph{Return value}:
 408 The return value is of the same type and
 409 kind as the argument except the return value is @code{REAL} for a
 410 @code{COMPLEX} argument.
 411
 412 @item @emph{Example}:
 413 @smallexample
 414 program test_abs
 415   integer :: i = -1
 416   real :: x = -1.e0
 417   complex :: z = (-1.e0,0.e0)
 418   i = abs(i)
 419   x = abs(x)
 420   x = abs(z)
 421 end program test_abs
 422 @end smallexample
 423
 424 @item @emph{Specific names}:
 425 @multitable @columnfractions .20 .20 .20 .25
 426 @item Name            @tab Argument            @tab Return type       @tab Standard
 427 @item @code{ABS(A)}   @tab @code{REAL(4) A}    @tab @code{REAL(4)}    @tab Fortran 77 and later
 428 @item @code{CABS(A)}  @tab @code{COMPLEX(4) A} @tab @code{REAL(4)}    @tab Fortran 77 and later
 429 @item @code{DABS(A)}  @tab @code{REAL(8) A}    @tab @code{REAL(8)}    @tab Fortran 77 and later
 430 @item @code{IABS(A)}  @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
 431 @item @code{ZABS(A)}  @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
 432 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
 433 @end multitable
 434 @end table
 435
 436
 437
 438 @node ACCESS
 439 @section @code{ACCESS} --- Checks file access modes
 440 @fnindex ACCESS
 441 @cindex file system, access mode
 442
 443 @table @asis
 444 @item @emph{Description}:
 445 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
 446 exists, is readable, writable or executable. Except for the
 447 executable check, @code{ACCESS} can be replaced by
 448 Fortran 95's @code{INQUIRE}.
 449
 450 @item @emph{Standard}:
 451 GNU extension
 452
 453 @item @emph{Class}:
 454 Inquiry function
 455
 456 @item @emph{Syntax}:
 457 @code{RESULT = ACCESS(NAME, MODE)}
 458
 459 @item @emph{Arguments}:
 460 @multitable @columnfractions .15 .70
 461 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
 462 file name. Tailing blank are ignored unless the character @code{achar(0)}
 463 is present, then all characters up to and excluding @code{achar(0)} are
 464 used as file name.
 465 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
 466 file access mode, may be any concatenation of @code{"r"} (readable),
 467 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
 468 for existence.
 469 @end multitable
 470
 471 @item @emph{Return value}:
 472 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
 473 accessible in the given mode; otherwise or if an invalid argument
 474 has been given for @code{MODE} the value @code{1} is returned.
 475
 476 @item @emph{Example}:
 477 @smallexample
 478 program access_test
 479   implicit none
 480   character(len=*), parameter :: file  = 'test.dat'
 481   character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
 482   if(access(file,' ') == 0) print *, trim(file),' is exists'
 483   if(access(file,'r') == 0) print *, trim(file),' is readable'
 484   if(access(file,'w') == 0) print *, trim(file),' is writable'
 485   if(access(file,'x') == 0) print *, trim(file),' is executable'
 486   if(access(file2,'rwx') == 0) &
 487     print *, trim(file2),' is readable, writable and executable'
 488 end program access_test
 489 @end smallexample
 490 @item @emph{Specific names}:
 491 @item @emph{See also}:
 492
 493 @end table
 494
 495
 496
 497 @node ACHAR
 498 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
 499 @fnindex ACHAR
 500 @cindex @acronym{ASCII} collating sequence
 501 @cindex collating sequence, @acronym{ASCII}
 502
 503 @table @asis
 504 @item @emph{Description}:
 505 @code{ACHAR(I)} returns the character located at position @code{I}
 506 in the @acronym{ASCII} collating sequence.
 507
 508 @item @emph{Standard}:
 509 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
 510
 511 @item @emph{Class}:
 512 Elemental function
 513
 514 @item @emph{Syntax}:
 515 @code{RESULT = ACHAR(I [, KIND])}
 516
 517 @item @emph{Arguments}:
 518 @multitable @columnfractions .15 .70
 519 @item @var{I}    @tab The type shall be @code{INTEGER}.
 520 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 521 expression indicating the kind parameter of the result.
 522 @end multitable
 523
 524 @item @emph{Return value}:
 525 The return value is of type @code{CHARACTER} with a length of one.
 526 If the @var{KIND} argument is present, the return value is of the
 527 specified kind and of the default kind otherwise.
 528
 529 @item @emph{Example}:
 530 @smallexample
 531 program test_achar
 532   character c
 533   c = achar(32)
 534 end program test_achar
 535 @end smallexample
 536
 537 @item @emph{Note}:
 538 See @ref{ICHAR} for a discussion of converting between numerical values
 539 and formatted string representations.
 540
 541 @item @emph{See also}:
 542 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
 543
 544 @end table
 545
 546
 547
 548 @node ACOS
 549 @section @code{ACOS} --- Arccosine function
 550 @fnindex ACOS
 551 @fnindex DACOS
 552 @cindex trigonometric function, cosine, inverse
 553 @cindex cosine, inverse
 554
 555 @table @asis
 556 @item @emph{Description}:
 557 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
 558
 559 @item @emph{Standard}:
 560 Fortran 77 and later, for a complex argument Fortran 2008 or later
 561
 562 @item @emph{Class}:
 563 Elemental function
 564
 565 @item @emph{Syntax}:
 566 @code{RESULT = ACOS(X)}
 567
 568 @item @emph{Arguments}:
 569 @multitable @columnfractions .15 .70
 570 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
 571 less than or equal to one - or the type shall be @code{COMPLEX}.
 572 @end multitable
 573
 574 @item @emph{Return value}:
 575 The return value is of the same type and kind as @var{X}.
 576 The real part of the result is in radians and lies in the range
 577 @math{0 \leq \Re \acos(x) \leq \pi}.
 578
 579 @item @emph{Example}:
 580 @smallexample
 581 program test_acos
 582   real(8) :: x = 0.866_8
 583   x = acos(x)
 584 end program test_acos
 585 @end smallexample
 586
 587 @item @emph{Specific names}:
 588 @multitable @columnfractions .20 .20 .20 .25
 589 @item Name            @tab Argument         @tab Return type     @tab Standard
 590 @item @code{ACOS(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}  @tab Fortran 77 and later
 591 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}  @tab Fortran 77 and later
 592 @end multitable
 593
 594 @item @emph{See also}:
 595 Inverse function: @ref{COS}
 596
 597 @end table
 598
 599
 600
 601 @node ACOSH
 602 @section @code{ACOSH} --- Inverse hyperbolic cosine function
 603 @fnindex ACOSH
 604 @fnindex DACOSH
 605 @cindex area hyperbolic cosine
 606 @cindex inverse hyperbolic cosine
 607 @cindex hyperbolic function, cosine, inverse
 608 @cindex cosine, hyperbolic, inverse
 609
 610 @table @asis
 611 @item @emph{Description}:
 612 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
 613
 614 @item @emph{Standard}:
 615 Fortran 2008 and later
 616
 617 @item @emph{Class}:
 618 Elemental function
 619
 620 @item @emph{Syntax}:
 621 @code{RESULT = ACOSH(X)}
 622
 623 @item @emph{Arguments}:
 624 @multitable @columnfractions .15 .70
 625 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
 626 @end multitable
 627
 628 @item @emph{Return value}:
 629 The return value has the same type and kind as @var{X}. If @var{X} is
 630 complex, the imaginary part of the result is in radians and lies between
 631 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
 632
 633 @item @emph{Example}:
 634 @smallexample
 635 PROGRAM test_acosh
 636   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
 637   WRITE (*,*) ACOSH(x)
 638 END PROGRAM
 639 @end smallexample
 640
 641 @item @emph{Specific names}:
 642 @multitable @columnfractions .20 .20 .20 .25
 643 @item Name             @tab Argument          @tab Return type       @tab Standard
 644 @item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
 645 @end multitable
 646
 647 @item @emph{See also}:
 648 Inverse function: @ref{COSH}
 649 @end table
 650
 651
 652
 653 @node ADJUSTL
 654 @section @code{ADJUSTL} --- Left adjust a string
 655 @fnindex ADJUSTL
 656 @cindex string, adjust left
 657 @cindex adjust string
 658
 659 @table @asis
 660 @item @emph{Description}:
 661 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
 662 Spaces are inserted at the end of the string as needed.
 663
 664 @item @emph{Standard}:
 665 Fortran 90 and later
 666
 667 @item @emph{Class}:
 668 Elemental function
 669
 670 @item @emph{Syntax}:
 671 @code{RESULT = ADJUSTL(STRING)}
 672
 673 @item @emph{Arguments}:
 674 @multitable @columnfractions .15 .70
 675 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
 676 @end multitable
 677
 678 @item @emph{Return value}:
 679 The return value is of type @code{CHARACTER} and of the same kind as
 680 @var{STRING} where leading spaces are removed and the same number of
 681 spaces are inserted on the end of @var{STRING}.
 682
 683 @item @emph{Example}:
 684 @smallexample
 685 program test_adjustl
 686   character(len=20) :: str = '   gfortran'
 687   str = adjustl(str)
 688   print *, str
 689 end program test_adjustl
 690 @end smallexample
 691
 692 @item @emph{See also}:
 693 @ref{ADJUSTR}, @ref{TRIM}
 694 @end table
 695
 696
 697
 698 @node ADJUSTR
 699 @section @code{ADJUSTR} --- Right adjust a string
 700 @fnindex ADJUSTR
 701 @cindex string, adjust right
 702 @cindex adjust string
 703
 704 @table @asis
 705 @item @emph{Description}:
 706 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
 707 Spaces are inserted at the start of the string as needed.
 708
 709 @item @emph{Standard}:
 710 Fortran 95 and later
 711
 712 @item @emph{Class}:
 713 Elemental function
 714
 715 @item @emph{Syntax}:
 716 @code{RESULT = ADJUSTR(STRING)}
 717
 718 @item @emph{Arguments}:
 719 @multitable @columnfractions .15 .70
 720 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 721 @end multitable
 722
 723 @item @emph{Return value}:
 724 The return value is of type @code{CHARACTER} and of the same kind as
 725 @var{STRING} where trailing spaces are removed and the same number of
 726 spaces are inserted at the start of @var{STRING}.
 727
 728 @item @emph{Example}:
 729 @smallexample
 730 program test_adjustr
 731   character(len=20) :: str = 'gfortran'
 732   str = adjustr(str)
 733   print *, str
 734 end program test_adjustr
 735 @end smallexample
 736
 737 @item @emph{See also}:
 738 @ref{ADJUSTL}, @ref{TRIM}
 739 @end table
 740
 741
 742
 743 @node AIMAG
 744 @section @code{AIMAG} --- Imaginary part of complex number
 745 @fnindex AIMAG
 746 @fnindex DIMAG
 747 @fnindex IMAG
 748 @fnindex IMAGPART
 749 @cindex complex numbers, imaginary part
 750
 751 @table @asis
 752 @item @emph{Description}:
 753 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
 754 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
 755 for compatibility with @command{g77}, and their use in new code is
 756 strongly discouraged.
 757
 758 @item @emph{Standard}:
 759 Fortran 77 and later, has overloads that are GNU extensions
 760
 761 @item @emph{Class}:
 762 Elemental function
 763
 764 @item @emph{Syntax}:
 765 @code{RESULT = AIMAG(Z)}
 766
 767 @item @emph{Arguments}:
 768 @multitable @columnfractions .15 .70
 769 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
 770 @end multitable
 771
 772 @item @emph{Return value}:
 773 The return value is of type @code{REAL} with the
 774 kind type parameter of the argument.
 775
 776 @item @emph{Example}:
 777 @smallexample
 778 program test_aimag
 779   complex(4) z4
 780   complex(8) z8
 781   z4 = cmplx(1.e0_4, 0.e0_4)
 782   z8 = cmplx(0.e0_8, 1.e0_8)
 783   print *, aimag(z4), dimag(z8)
 784 end program test_aimag
 785 @end smallexample
 786
 787 @item @emph{Specific names}:
 788 @multitable @columnfractions .20 .20 .20 .25
 789 @item Name               @tab Argument            @tab Return type     @tab Standard
 790 @item @code{AIMAG(Z)}    @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 791 @item @code{DIMAG(Z)}    @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}  @tab GNU extension
 792 @item @code{IMAG(Z)}     @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 793 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 794 @end multitable
 795 @end table
 796
 797
 798
 799 @node AINT
 800 @section @code{AINT} --- Truncate to a whole number
 801 @fnindex AINT
 802 @fnindex DINT
 803 @cindex floor
 804 @cindex rounding, floor
 805
 806 @table @asis
 807 @item @emph{Description}:
 808 @code{AINT(A [, KIND])} truncates its argument to a whole number.
 809
 810 @item @emph{Standard}:
 811 Fortran 77 and later
 812
 813 @item @emph{Class}:
 814 Elemental function
 815
 816 @item @emph{Syntax}:
 817 @code{RESULT = AINT(A [, KIND])}
 818
 819 @item @emph{Arguments}:
 820 @multitable @columnfractions .15 .70
 821 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
 822 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 823 expression indicating the kind parameter of the result.
 824 @end multitable
 825
 826 @item @emph{Return value}:
 827 The return value is of type @code{REAL} with the kind type parameter of the
 828 argument if the optional @var{KIND} is absent; otherwise, the kind
 829 type parameter will be given by @var{KIND}.  If the magnitude of
 830 @var{X} is less than one, @code{AINT(X)} returns zero.  If the
 831 magnitude is equal to or greater than one then it returns the largest
 832 whole number that does not exceed its magnitude.  The sign is the same
 833 as the sign of @var{X}.
 834
 835 @item @emph{Example}:
 836 @smallexample
 837 program test_aint
 838   real(4) x4
 839   real(8) x8
 840   x4 = 1.234E0_4
 841   x8 = 4.321_8
 842   print *, aint(x4), dint(x8)
 843   x8 = aint(x4,8)
 844 end program test_aint
 845 @end smallexample
 846
 847 @item @emph{Specific names}:
 848 @multitable @columnfractions .20 .20 .20 .25
 849 @item Name           @tab Argument         @tab Return type      @tab Standard
 850 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
 851 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
 852 @end multitable
 853 @end table
 854
 855
 856
 857 @node ALARM
 858 @section @code{ALARM} --- Execute a routine after a given delay
 859 @fnindex ALARM
 860 @cindex delayed execution
 861
 862 @table @asis
 863 @item @emph{Description}:
 864 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
 865 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
 866 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
 867 supplied, it will be returned with the number of seconds remaining until
 868 any previously scheduled alarm was due to be delivered, or zero if there
 869 was no previously scheduled alarm.
 870
 871 @item @emph{Standard}:
 872 GNU extension
 873
 874 @item @emph{Class}:
 875 Subroutine
 876
 877 @item @emph{Syntax}:
 878 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
 879
 880 @item @emph{Arguments}:
 881 @multitable @columnfractions .15 .70
 882 @item @var{SECONDS} @tab The type of the argument shall be a scalar
 883 @code{INTEGER}. It is @code{INTENT(IN)}.
 884 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
 885 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
 886 values may be either @code{SIG_IGN=1} to ignore the alarm generated
 887 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
 888 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
 889 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
 890 @end multitable
 891
 892 @item @emph{Example}:
 893 @smallexample
 894 program test_alarm
 895   external handler_print
 896   integer i
 897   call alarm (3, handler_print, i)
 898   print *, i
 899   call sleep(10)
 900 end program test_alarm
 901 @end smallexample
 902 This will cause the external routine @var{handler_print} to be called
 903 after 3 seconds.
 904 @end table
 905
 906
 907
 908 @node ALL
 909 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
 910 @fnindex ALL
 911 @cindex array, apply condition
 912 @cindex array, condition testing
 913
 914 @table @asis
 915 @item @emph{Description}:
 916 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
 917 in the array along dimension @var{DIM}.
 918
 919 @item @emph{Standard}:
 920 Fortran 95 and later
 921
 922 @item @emph{Class}:
 923 Transformational function
 924
 925 @item @emph{Syntax}:
 926 @code{RESULT = ALL(MASK [, DIM])}
 927
 928 @item @emph{Arguments}:
 929 @multitable @columnfractions .15 .70
 930 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
 931 it shall not be scalar.
 932 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
 933 with a value that lies between one and the rank of @var{MASK}.
 934 @end multitable
 935
 936 @item @emph{Return value}:
 937 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
 938 the kind type parameter is the same as the kind type parameter of
 939 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
 940 an array with the rank of @var{MASK} minus 1.  The shape is determined from
 941 the shape of @var{MASK} where the @var{DIM} dimension is elided.
 942
 943 @table @asis
 944 @item (A)
 945 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
 946 It also is true if @var{MASK} has zero size; otherwise, it is false.
 947 @item (B)
 948 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
 949 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
 950 is determined by applying @code{ALL} to the array sections.
 951 @end table
 952
 953 @item @emph{Example}:
 954 @smallexample
 955 program test_all
 956   logical l
 957   l = all((/.true., .true., .true./))
 958   print *, l
 959   call section
 960   contains
 961     subroutine section
 962       integer a(2,3), b(2,3)
 963       a = 1
 964       b = 1
 965       b(2,2) = 2
 966       print *, all(a .eq. b, 1)
 967       print *, all(a .eq. b, 2)
 968     end subroutine section
 969 end program test_all
 970 @end smallexample
 971 @end table
 972
 973
 974
 975 @node ALLOCATED
 976 @section @code{ALLOCATED} --- Status of an allocatable entity
 977 @fnindex ALLOCATED
 978 @cindex allocation, status
 979
 980 @table @asis
 981 @item @emph{Description}:
 982 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
 983 status of @var{ARRAY} and @var{SCALAR}, respectively.
 984
 985 @item @emph{Standard}:
 986 Fortran 95 and later.  Note, the @code{SCALAR=} keyword and allocatable
 987 scalar entities are available in Fortran 2003 and later.
 988
 989 @item @emph{Class}:
 990 Inquiry function
 991
 992 @item @emph{Syntax}:
 993 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
 994
 995 @item @emph{Arguments}:
 996 @multitable @columnfractions .15 .70
 997 @item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
 998 @item @var{SCALAR}   @tab The argument shall be an @code{ALLOCATABLE} scalar.
 999 @end multitable
1000
1001 @item @emph{Return value}:
1002 The return value is a scalar @code{LOGICAL} with the default logical
1003 kind type parameter.  If the argument is allocated, then the result is
1004 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1005
1006 @item @emph{Example}:
1007 @smallexample
1008 program test_allocated
1009   integer :: i = 4
1010   real(4), allocatable :: x(:)
1011   if (.not. allocated(x)) allocate(x(i))
1012 end program test_allocated
1013 @end smallexample
1014 @end table
1015
1016
1017
1018 @node AND
1019 @section @code{AND} --- Bitwise logical AND
1020 @fnindex AND
1021 @cindex bitwise logical and
1022 @cindex logical and, bitwise
1023
1024 @table @asis
1025 @item @emph{Description}:
1026 Bitwise logical @code{AND}.
1027
1028 This intrinsic routine is provided for backwards compatibility with
1029 GNU Fortran 77.  For integer arguments, programmers should consider
1030 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1031
1032 @item @emph{Standard}:
1033 GNU extension
1034
1035 @item @emph{Class}:
1036 Function
1037
1038 @item @emph{Syntax}:
1039 @code{RESULT = AND(I, J)}
1040
1041 @item @emph{Arguments}:
1042 @multitable @columnfractions .15 .70
1043 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1044 type or a scalar @code{LOGICAL} type.
1045 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1046 @end multitable
1047
1048 @item @emph{Return value}:
1049 The return type is either a scalar @code{INTEGER} or a scalar
1050 @code{LOGICAL}.  If the kind type parameters differ, then the
1051 smaller kind type is implicitly converted to larger kind, and the
1052 return has the larger kind.
1053
1054 @item @emph{Example}:
1055 @smallexample
1056 PROGRAM test_and
1057   LOGICAL :: T = .TRUE., F = .FALSE.
1058   INTEGER :: a, b
1059   DATA a / Z'F' /, b / Z'3' /
1060
1061   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1062   WRITE (*,*) AND(a, b)
1063 END PROGRAM
1064 @end smallexample
1065
1066 @item @emph{See also}:
1067 Fortran 95 elemental function: @ref{IAND}
1068 @end table
1069
1070
1071
1072 @node ANINT
1073 @section @code{ANINT} --- Nearest whole number
1074 @fnindex ANINT
1075 @fnindex DNINT
1076 @cindex ceiling
1077 @cindex rounding, ceiling
1078
1079 @table @asis
1080 @item @emph{Description}:
1081 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1082
1083 @item @emph{Standard}:
1084 Fortran 77 and later
1085
1086 @item @emph{Class}:
1087 Elemental function
1088
1089 @item @emph{Syntax}:
1090 @code{RESULT = ANINT(A [, KIND])}
1091
1092 @item @emph{Arguments}:
1093 @multitable @columnfractions .15 .70
1094 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
1095 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1096 expression indicating the kind parameter of the result.
1097 @end multitable
1098
1099 @item @emph{Return value}:
1100 The return value is of type real with the kind type parameter of the
1101 argument if the optional @var{KIND} is absent; otherwise, the kind
1102 type parameter will be given by @var{KIND}.  If @var{A} is greater than
1103 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1104 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1105
1106 @item @emph{Example}:
1107 @smallexample
1108 program test_anint
1109   real(4) x4
1110   real(8) x8
1111   x4 = 1.234E0_4
1112   x8 = 4.321_8
1113   print *, anint(x4), dnint(x8)
1114   x8 = anint(x4,8)
1115 end program test_anint
1116 @end smallexample
1117
1118 @item @emph{Specific names}:
1119 @multitable @columnfractions .20 .20 .20 .25
1120 @item Name            @tab Argument         @tab Return type      @tab Standard
1121 @item @code{AINT(A)}  @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
1122 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1123 @end multitable
1124 @end table
1125
1126
1127
1128 @node ANY
1129 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1130 @fnindex ANY
1131 @cindex array, apply condition
1132 @cindex array, condition testing
1133
1134 @table @asis
1135 @item @emph{Description}:
1136 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1137 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1138
1139 @item @emph{Standard}:
1140 Fortran 95 and later
1141
1142 @item @emph{Class}:
1143 Transformational function
1144
1145 @item @emph{Syntax}:
1146 @code{RESULT = ANY(MASK [, DIM])}
1147
1148 @item @emph{Arguments}:
1149 @multitable @columnfractions .15 .70
1150 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1151 it shall not be scalar.
1152 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1153 with a value that lies between one and the rank of @var{MASK}.
1154 @end multitable
1155
1156 @item @emph{Return value}:
1157 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1158 the kind type parameter is the same as the kind type parameter of
1159 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1160 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1161 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1162
1163 @table @asis
1164 @item (A)
1165 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1166 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1167 @item (B)
1168 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1169 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1170 is determined by applying @code{ANY} to the array sections.
1171 @end table
1172
1173 @item @emph{Example}:
1174 @smallexample
1175 program test_any
1176   logical l
1177   l = any((/.true., .true., .true./))
1178   print *, l
1179   call section
1180   contains
1181     subroutine section
1182       integer a(2,3), b(2,3)
1183       a = 1
1184       b = 1
1185       b(2,2) = 2
1186       print *, any(a .eq. b, 1)
1187       print *, any(a .eq. b, 2)
1188     end subroutine section
1189 end program test_any
1190 @end smallexample
1191 @end table
1192
1193
1194
1195 @node ASIN
1196 @section @code{ASIN} --- Arcsine function
1197 @fnindex ASIN
1198 @fnindex DASIN
1199 @cindex trigonometric function, sine, inverse
1200 @cindex sine, inverse
1201
1202 @table @asis
1203 @item @emph{Description}:
1204 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1205
1206 @item @emph{Standard}:
1207 Fortran 77 and later, for a complex argument Fortran 2008 or later
1208
1209 @item @emph{Class}:
1210 Elemental function
1211
1212 @item @emph{Syntax}:
1213 @code{RESULT = ASIN(X)}
1214
1215 @item @emph{Arguments}:
1216 @multitable @columnfractions .15 .70
1217 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1218 less than or equal to one - or be @code{COMPLEX}.
1219 @end multitable
1220
1221 @item @emph{Return value}:
1222 The return value is of the same type and kind as @var{X}.
1223 The real part of the result is in radians and lies in the range
1224 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1225
1226 @item @emph{Example}:
1227 @smallexample
1228 program test_asin
1229   real(8) :: x = 0.866_8
1230   x = asin(x)
1231 end program test_asin
1232 @end smallexample
1233
1234 @item @emph{Specific names}:
1235 @multitable @columnfractions .20 .20 .20 .25
1236 @item Name            @tab Argument          @tab Return type       @tab Standard
1237 @item @code{ASIN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1238 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1239 @end multitable
1240
1241 @item @emph{See also}:
1242 Inverse function: @ref{SIN}
1243
1244 @end table
1245
1246
1247
1248 @node ASINH
1249 @section @code{ASINH} --- Inverse hyperbolic sine function
1250 @fnindex ASINH
1251 @fnindex DASINH
1252 @cindex area hyperbolic sine
1253 @cindex inverse hyperbolic sine
1254 @cindex hyperbolic function, sine, inverse
1255 @cindex sine, hyperbolic, inverse
1256
1257 @table @asis
1258 @item @emph{Description}:
1259 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1260
1261 @item @emph{Standard}:
1262 Fortran 2008 and later
1263
1264 @item @emph{Class}:
1265 Elemental function
1266
1267 @item @emph{Syntax}:
1268 @code{RESULT = ASINH(X)}
1269
1270 @item @emph{Arguments}:
1271 @multitable @columnfractions .15 .70
1272 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1273 @end multitable
1274
1275 @item @emph{Return value}:
1276 The return value is of the same type and kind as  @var{X}. If @var{X} is
1277 complex, the imaginary part of the result is in radians and lies between
1278 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1279
1280 @item @emph{Example}:
1281 @smallexample
1282 PROGRAM test_asinh
1283   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1284   WRITE (*,*) ASINH(x)
1285 END PROGRAM
1286 @end smallexample
1287
1288 @item @emph{Specific names}:
1289 @multitable @columnfractions .20 .20 .20 .25
1290 @item Name             @tab Argument          @tab Return type       @tab Standard
1291 @item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1292 @end multitable
1293
1294 @item @emph{See also}:
1295 Inverse function: @ref{SINH}
1296 @end table
1297
1298
1299
1300 @node ASSOCIATED
1301 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1302 @fnindex ASSOCIATED
1303 @cindex pointer, status
1304 @cindex association status
1305
1306 @table @asis
1307 @item @emph{Description}:
1308 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1309 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1310
1311 @item @emph{Standard}:
1312 Fortran 95 and later
1313
1314 @item @emph{Class}:
1315 Inquiry function
1316
1317 @item @emph{Syntax}:
1318 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1319
1320 @item @emph{Arguments}:
1321 @multitable @columnfractions .15 .70
1322 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1323 and it can be of any type.
1324 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1325 a target.  It must have the same type, kind type parameter, and
1326 array rank as @var{POINTER}.
1327 @end multitable
1328 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1329 undefined.
1330
1331 @item @emph{Return value}:
1332 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1333 There are several cases:
1334 @table @asis
1335 @item (A) When the optional @var{TARGET} is not present then
1336 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1337 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1338 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units.  If @var{POINTER} is
1339 disassociated, the result is false.
1340 @item (C) If @var{TARGET} is present and an array target, the result is true if
1341 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1342 are arrays whose elements are not zero-sized storage sequences, and
1343 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1344 order.
1345 As in case(B), the result is false, if @var{POINTER} is disassociated.
1346 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1347 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1348 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1349 units.
1350 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1351 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1352 target associated with @var{POINTER} and the target associated with @var{TARGET}
1353 have the same shape, are not zero-sized arrays, are arrays whose elements are
1354 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1355 the same storage units in array element order.
1356 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1357 @end table
1358
1359 @item @emph{Example}:
1360 @smallexample
1361 program test_associated
1362    implicit none
1363    real, target  :: tgt(2) = (/1., 2./)
1364    real, pointer :: ptr(:)
1365    ptr => tgt
1366    if (associated(ptr)     .eqv. .false.) call abort
1367    if (associated(ptr,tgt) .eqv. .false.) call abort
1368 end program test_associated
1369 @end smallexample
1370
1371 @item @emph{See also}:
1372 @ref{NULL}
1373 @end table
1374
1375
1376
1377 @node ATAN
1378 @section @code{ATAN} --- Arctangent function
1379 @fnindex ATAN
1380 @fnindex DATAN
1381 @cindex trigonometric function, tangent, inverse
1382 @cindex tangent, inverse
1383
1384 @table @asis
1385 @item @emph{Description}:
1386 @code{ATAN(X)} computes the arctangent of @var{X}.
1387
1388 @item @emph{Standard}:
1389 Fortran 77 and later, for a complex argument and for two arguments
1390 Fortran 2008 or later
1391
1392 @item @emph{Class}:
1393 Elemental function
1394
1395 @item @emph{Syntax}:
1396 @code{RESULT = ATAN(X)}
1397 @code{RESULT = ATAN(Y, X)}
1398
1399 @item @emph{Arguments}:
1400 @multitable @columnfractions .15 .70
1401 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1402 if @var{Y} is present, @var{X} shall be REAL.
1403 @item @var{Y} shall be of the same type and kind as @var{X}.
1404 @end multitable
1405
1406 @item @emph{Return value}:
1407 The return value is of the same type and kind as @var{X}.
1408 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1409 Otherwise, it the arcus tangent of @var{X}, where the real part of
1410 the result is in radians and lies in the range
1411 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1412
1413 @item @emph{Example}:
1414 @smallexample
1415 program test_atan
1416   real(8) :: x = 2.866_8
1417   x = atan(x)
1418 end program test_atan
1419 @end smallexample
1420
1421 @item @emph{Specific names}:
1422 @multitable @columnfractions .20 .20 .20 .25
1423 @item Name            @tab Argument          @tab Return type       @tab Standard
1424 @item @code{ATAN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1425 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1426 @end multitable
1427
1428 @item @emph{See also}:
1429 Inverse function: @ref{TAN}
1430
1431 @end table
1432
1433
1434
1435 @node ATAN2
1436 @section @code{ATAN2} --- Arctangent function
1437 @fnindex ATAN2
1438 @fnindex DATAN2
1439 @cindex trigonometric function, tangent, inverse
1440 @cindex tangent, inverse
1441
1442 @table @asis
1443 @item @emph{Description}:
1444 @code{ATAN2(Y, X)} computes the principal value of the argument
1445 function of the complex number @math{X + i Y}. This function can
1446 be used to transform from carthesian into polar coordinates and
1447 allows to determine the angle in the correct quadrant.
1448
1449 @item @emph{Standard}:
1450 Fortran 77 and later
1451
1452 @item @emph{Class}:
1453 Elemental function
1454
1455 @item @emph{Syntax}:
1456 @code{RESULT = ATAN2(Y, X)}
1457
1458 @item @emph{Arguments}:
1459 @multitable @columnfractions .15 .70
1460 @item @var{Y} @tab The type shall be @code{REAL}.
1461 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1462 If @var{Y} is zero, then @var{X} must be nonzero.
1463 @end multitable
1464
1465 @item @emph{Return value}:
1466 The return value has the same type and kind type parameter as @var{Y}.
1467 It is the principal value of the complex number @math{X + i Y}.  If
1468 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1469 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1470 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1471 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1472 is @math{\pi/2}.
1473
1474 @item @emph{Example}:
1475 @smallexample
1476 program test_atan2
1477   real(4) :: x = 1.e0_4, y = 0.5e0_4
1478   x = atan2(y,x)
1479 end program test_atan2
1480 @end smallexample
1481
1482 @item @emph{Specific names}:
1483 @multitable @columnfractions .20 .20 .20 .25
1484 @item Name                @tab Argument            @tab Return type    @tab Standard
1485 @item @code{ATAN2(X, Y)}  @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1486 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1487 @end multitable
1488 @end table
1489
1490
1491
1492 @node ATANH
1493 @section @code{ATANH} --- Inverse hyperbolic tangent function
1494 @fnindex ATANH
1495 @fnindex DATANH
1496 @cindex area hyperbolic tangent
1497 @cindex inverse hyperbolic tangent
1498 @cindex hyperbolic function, tangent, inverse
1499 @cindex tangent, hyperbolic, inverse
1500
1501 @table @asis
1502 @item @emph{Description}:
1503 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1504
1505 @item @emph{Standard}:
1506 Fortran 2008 and later
1507
1508 @item @emph{Class}:
1509 Elemental function
1510
1511 @item @emph{Syntax}:
1512 @code{RESULT = ATANH(X)}
1513
1514 @item @emph{Arguments}:
1515 @multitable @columnfractions .15 .70
1516 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1517 @end multitable
1518
1519 @item @emph{Return value}:
1520 The return value has same type and kind as @var{X}. If @var{X} is
1521 complex, the imaginary part of the result is in radians and lies between
1522 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1523
1524 @item @emph{Example}:
1525 @smallexample
1526 PROGRAM test_atanh
1527   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1528   WRITE (*,*) ATANH(x)
1529 END PROGRAM
1530 @end smallexample
1531
1532 @item @emph{Specific names}:
1533 @multitable @columnfractions .20 .20 .20 .25
1534 @item Name             @tab Argument          @tab Return type       @tab Standard
1535 @item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1536 @end multitable
1537
1538 @item @emph{See also}:
1539 Inverse function: @ref{TANH}
1540 @end table
1541
1542
1543
1544 @node BESSEL_J0
1545 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1546 @fnindex BESSEL_J0
1547 @fnindex BESJ0
1548 @fnindex DBESJ0
1549 @cindex Bessel function, first kind
1550
1551 @table @asis
1552 @item @emph{Description}:
1553 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1554 order 0 of @var{X}. This function is available under the name
1555 @code{BESJ0} as a GNU extension.
1556
1557 @item @emph{Standard}:
1558 Fortran 2008 and later
1559
1560 @item @emph{Class}:
1561 Elemental function
1562
1563 @item @emph{Syntax}:
1564 @code{RESULT = BESSEL_J0(X)}
1565
1566 @item @emph{Arguments}:
1567 @multitable @columnfractions .15 .70
1568 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1569 @end multitable
1570
1571 @item @emph{Return value}:
1572 The return value is of type @code{REAL} and lies in the
1573 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1574 kind as @var{X}.
1575
1576 @item @emph{Example}:
1577 @smallexample
1578 program test_besj0
1579   real(8) :: x = 0.0_8
1580   x = bessel_j0(x)
1581 end program test_besj0
1582 @end smallexample
1583
1584 @item @emph{Specific names}:
1585 @multitable @columnfractions .20 .20 .20 .25
1586 @item Name            @tab Argument          @tab Return type       @tab Standard
1587 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1588 @end multitable
1589 @end table
1590
1591
1592
1593 @node BESSEL_J1
1594 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1595 @fnindex BESSEL_J1
1596 @fnindex BESJ1
1597 @fnindex DBESJ1
1598 @cindex Bessel function, first kind
1599
1600 @table @asis
1601 @item @emph{Description}:
1602 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1603 order 1 of @var{X}. This function is available under the name
1604 @code{BESJ1} as a GNU extension.
1605
1606 @item @emph{Standard}:
1607 Fortran 2008
1608
1609 @item @emph{Class}:
1610 Elemental function
1611
1612 @item @emph{Syntax}:
1613 @code{RESULT = BESSEL_J1(X)}
1614
1615 @item @emph{Arguments}:
1616 @multitable @columnfractions .15 .70
1617 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1618 @end multitable
1619
1620 @item @emph{Return value}:
1621 The return value is of type @code{REAL} and it lies in the
1622 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1623 kind as @var{X}.
1624
1625 @item @emph{Example}:
1626 @smallexample
1627 program test_besj1
1628   real(8) :: x = 1.0_8
1629   x = bessel_j1(x)
1630 end program test_besj1
1631 @end smallexample
1632
1633 @item @emph{Specific names}:
1634 @multitable @columnfractions .20 .20 .20 .25
1635 @item Name             @tab Argument          @tab Return type       @tab Standard
1636 @item @code{DBESJ1(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1637 @end multitable
1638 @end table
1639
1640
1641
1642 @node BESSEL_JN
1643 @section @code{BESSEL_JN} --- Bessel function of the first kind
1644 @fnindex BESSEL_JN
1645 @fnindex BESJN
1646 @fnindex DBESJN
1647 @cindex Bessel function, first kind
1648
1649 @table @asis
1650 @item @emph{Description}:
1651 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1652 order @var{N} of @var{X}. This function is available under the name
1653 @code{BESJN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1654 their ranks and shapes shall conform.
1655
1656 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1657 of the first kind of the orders @var{N1} to @var{N2}.
1658
1659 @item @emph{Standard}:
1660 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1661
1662 @item @emph{Class}:
1663 Elemental function, except for the tranformational function
1664 @code{BESSEL_JN(N1, N2, X)}
1665
1666 @item @emph{Syntax}:
1667 @code{RESULT = BESSEL_JN(N, X)}
1668 @code{RESULT = BESSEL_JN(N1, N2, X)}
1669
1670 @item @emph{Arguments}:
1671 @multitable @columnfractions .15 .70
1672 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1673 @item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1674 @item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1675 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1676 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1677 @end multitable
1678
1679 @item @emph{Return value}:
1680 The return value is a scalar of type @code{REAL}. It has the same
1681 kind as @var{X}.
1682
1683 @item @emph{Note}:
1684 The transformational function uses a recurrence algorithm which might,
1685 for some values of @var{X}, lead to different results than calls to
1686 the elemental function.
1687
1688 @item @emph{Example}:
1689 @smallexample
1690 program test_besjn
1691   real(8) :: x = 1.0_8
1692   x = bessel_jn(5,x)
1693 end program test_besjn
1694 @end smallexample
1695
1696 @item @emph{Specific names}:
1697 @multitable @columnfractions .20 .20 .20 .25
1698 @item Name                @tab Argument            @tab Return type       @tab Standard
1699 @item @code{DBESJN(N, X)} @tab @code{INTEGER N}    @tab @code{REAL(8)}    @tab GNU extension
1700 @item                     @tab @code{REAL(8) X}    @tab                   @tab
1701 @end multitable
1702 @end table
1703
1704
1705
1706 @node BESSEL_Y0
1707 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1708 @fnindex BESSEL_Y0
1709 @fnindex BESY0
1710 @fnindex DBESY0
1711 @cindex Bessel function, second kind
1712
1713 @table @asis
1714 @item @emph{Description}:
1715 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1716 order 0 of @var{X}. This function is available under the name
1717 @code{BESY0} as a GNU extension.
1718
1719 @item @emph{Standard}:
1720 Fortran 2008 and later
1721
1722 @item @emph{Class}:
1723 Elemental function
1724
1725 @item @emph{Syntax}:
1726 @code{RESULT = BESSEL_Y0(X)}
1727
1728 @item @emph{Arguments}:
1729 @multitable @columnfractions .15 .70
1730 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1731 @end multitable
1732
1733 @item @emph{Return value}:
1734 The return value is a scalar of type @code{REAL}. It has the same
1735 kind as @var{X}.
1736
1737 @item @emph{Example}:
1738 @smallexample
1739 program test_besy0
1740   real(8) :: x = 0.0_8
1741   x = bessel_y0(x)
1742 end program test_besy0
1743 @end smallexample
1744
1745 @item @emph{Specific names}:
1746 @multitable @columnfractions .20 .20 .20 .25
1747 @item Name            @tab Argument          @tab Return type       @tab Standard
1748 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1749 @end multitable
1750 @end table
1751
1752
1753
1754 @node BESSEL_Y1
1755 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1756 @fnindex BESSEL_Y1
1757 @fnindex BESY1
1758 @fnindex DBESY1
1759 @cindex Bessel function, second kind
1760
1761 @table @asis
1762 @item @emph{Description}:
1763 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1764 order 1 of @var{X}. This function is available under the name
1765 @code{BESY1} as a GNU extension.
1766
1767 @item @emph{Standard}:
1768 Fortran 2008 and later
1769
1770 @item @emph{Class}:
1771 Elemental function
1772
1773 @item @emph{Syntax}:
1774 @code{RESULT = BESSEL_Y1(X)}
1775
1776 @item @emph{Arguments}:
1777 @multitable @columnfractions .15 .70
1778 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1779 @end multitable
1780
1781 @item @emph{Return value}:
1782 The return value is a scalar of type @code{REAL}. It has the same
1783 kind as @var{X}.
1784
1785 @item @emph{Example}:
1786 @smallexample
1787 program test_besy1
1788   real(8) :: x = 1.0_8
1789   x = bessel_y1(x)
1790 end program test_besy1
1791 @end smallexample
1792
1793 @item @emph{Specific names}:
1794 @multitable @columnfractions .20 .20 .20 .25
1795 @item Name            @tab Argument          @tab Return type       @tab Standard
1796 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1797 @end multitable
1798 @end table
1799
1800
1801
1802 @node BESSEL_YN
1803 @section @code{BESSEL_YN} --- Bessel function of the second kind
1804 @fnindex BESSEL_YN
1805 @fnindex BESYN
1806 @fnindex DBESYN
1807 @cindex Bessel function, second kind
1808
1809 @table @asis
1810 @item @emph{Description}:
1811 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1812 order @var{N} of @var{X}. This function is available under the name
1813 @code{BESYN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1814 their ranks and shapes shall conform.
1815
1816 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1817 of the first kind of the orders @var{N1} to @var{N2}.
1818
1819 @item @emph{Standard}:
1820 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1821
1822 @item @emph{Class}:
1823 Elemental function, except for the tranformational function
1824 @code{BESSEL_YN(N1, N2, X)}
1825
1826 @item @emph{Syntax}:
1827 @code{RESULT = BESSEL_YN(N, X)}
1828 @code{RESULT = BESSEL_YN(N1, N2, X)}
1829
1830 @item @emph{Arguments}:
1831 @multitable @columnfractions .15 .70
1832 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER} .
1833 @item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1834 @item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1835 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1836 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1837 @end multitable
1838
1839 @item @emph{Return value}:
1840 The return value is a scalar of type @code{REAL}. It has the same
1841 kind as @var{X}.
1842
1843 @item @emph{Note}:
1844 The transformational function uses a recurrence algorithm which might,
1845 for some values of @var{X}, lead to different results than calls to
1846 the elemental function.
1847
1848 @item @emph{Example}:
1849 @smallexample
1850 program test_besyn
1851   real(8) :: x = 1.0_8
1852   x = bessel_yn(5,x)
1853 end program test_besyn
1854 @end smallexample
1855
1856 @item @emph{Specific names}:
1857 @multitable @columnfractions .20 .20 .20 .25
1858 @item Name               @tab Argument            @tab Return type     @tab Standard
1859 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1860 @item                    @tab @code{REAL(8) X} @tab                 @tab
1861 @end multitable
1862 @end table
1863
1864
1865
1866 @node BGE
1867 @section @code{BGE} --- Bitwise greater than or equal to
1868 @fnindex BGE
1869 @cindex bitwise comparison
1870
1871 @table @asis
1872 @item @emph{Description}:
1873 Determines whether an integral is a bitwise greater than or equal to
1874 another.
1875
1876 @item @emph{Standard}:
1877 Fortran 2008 and later
1878
1879 @item @emph{Class}:
1880 Elemental function
1881
1882 @item @emph{Syntax}:
1883 @code{RESULT = BGE(I, J)}
1884
1885 @item @emph{Arguments}:
1886 @multitable @columnfractions .15 .70
1887 @item @var{I} @tab Shall be of @code{INTEGER} type.
1888 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1889 as @var{I}.
1890 @end multitable
1891
1892 @item @emph{Return value}:
1893 The return value is of type @code{LOGICAL} and of the default kind.
1894
1895 @item @emph{See also}:
1896 @ref{BGT}, @ref{BLE}, @ref{BLT}
1897 @end table
1898
1899
1900
1901 @node BGT
1902 @section @code{BGT} --- Bitwise greater than
1903 @fnindex BGT
1904 @cindex bitwise comparison
1905
1906 @table @asis
1907 @item @emph{Description}:
1908 Determines whether an integral is a bitwise greater than another.
1909
1910 @item @emph{Standard}:
1911 Fortran 2008 and later
1912
1913 @item @emph{Class}:
1914 Elemental function
1915
1916 @item @emph{Syntax}:
1917 @code{RESULT = BGT(I, J)}
1918
1919 @item @emph{Arguments}:
1920 @multitable @columnfractions .15 .70
1921 @item @var{I} @tab Shall be of @code{INTEGER} type.
1922 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1923 as @var{I}.
1924 @end multitable
1925
1926 @item @emph{Return value}:
1927 The return value is of type @code{LOGICAL} and of the default kind.
1928
1929 @item @emph{See also}:
1930 @ref{BGE}, @ref{BLE}, @ref{BLT}
1931 @end table
1932
1933
1934
1935 @node BIT_SIZE
1936 @section @code{BIT_SIZE} --- Bit size inquiry function
1937 @fnindex BIT_SIZE
1938 @cindex bits, number of
1939 @cindex size of a variable, in bits
1940
1941 @table @asis
1942 @item @emph{Description}:
1943 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1944 represented by the type of @var{I}.  The result of @code{BIT_SIZE(I)} is
1945 independent of the actual value of @var{I}.
1946
1947 @item @emph{Standard}:
1948 Fortran 95 and later
1949
1950 @item @emph{Class}:
1951 Inquiry function
1952
1953 @item @emph{Syntax}:
1954 @code{RESULT = BIT_SIZE(I)}
1955
1956 @item @emph{Arguments}:
1957 @multitable @columnfractions .15 .70
1958 @item @var{I} @tab The type shall be @code{INTEGER}.
1959 @end multitable
1960
1961 @item @emph{Return value}:
1962 The return value is of type @code{INTEGER}
1963
1964 @item @emph{Example}:
1965 @smallexample
1966 program test_bit_size
1967     integer :: i = 123
1968     integer :: size
1969     size = bit_size(i)
1970     print *, size
1971 end program test_bit_size
1972 @end smallexample
1973 @end table
1974
1975
1976
1977 @node BLE
1978 @section @code{BLE} --- Bitwise less than or equal to
1979 @fnindex BLE
1980 @cindex bitwise comparison
1981
1982 @table @asis
1983 @item @emph{Description}:
1984 Determines whether an integral is a bitwise less than or equal to
1985 another.
1986
1987 @item @emph{Standard}:
1988 Fortran 2008 and later
1989
1990 @item @emph{Class}:
1991 Elemental function
1992
1993 @item @emph{Syntax}:
1994 @code{RESULT = BLE(I, J)}
1995
1996 @item @emph{Arguments}:
1997 @multitable @columnfractions .15 .70
1998 @item @var{I} @tab Shall be of @code{INTEGER} type.
1999 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2000 as @var{I}.
2001 @end multitable
2002
2003 @item @emph{Return value}:
2004 The return value is of type @code{LOGICAL} and of the default kind.
2005
2006 @item @emph{See also}:
2007 @ref{BGT}, @ref{BGE}, @ref{BLT}
2008 @end table
2009
2010
2011
2012 @node BLT
2013 @section @code{BLT} --- Bitwise less than
2014 @fnindex BLT
2015 @cindex bitwise comparison
2016
2017 @table @asis
2018 @item @emph{Description}:
2019 Determines whether an integral is a bitwise less than another.
2020
2021 @item @emph{Standard}:
2022 Fortran 2008 and later
2023
2024 @item @emph{Class}:
2025 Elemental function
2026
2027 @item @emph{Syntax}:
2028 @code{RESULT = BLT(I, J)}
2029
2030 @item @emph{Arguments}:
2031 @multitable @columnfractions .15 .70
2032 @item @var{I} @tab Shall be of @code{INTEGER} type.
2033 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2034 as @var{I}.
2035 @end multitable
2036
2037 @item @emph{Return value}:
2038 The return value is of type @code{LOGICAL} and of the default kind.
2039
2040 @item @emph{See also}:
2041 @ref{BGE}, @ref{BGT}, @ref{BLE}
2042 @end table
2043
2044
2045
2046 @node BTEST
2047 @section @code{BTEST} --- Bit test function
2048 @fnindex BTEST
2049 @cindex bits, testing
2050
2051 @table @asis
2052 @item @emph{Description}:
2053 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2054 in @var{I} is set.  The counting of the bits starts at 0.
2055
2056 @item @emph{Standard}:
2057 Fortran 95 and later
2058
2059 @item @emph{Class}:
2060 Elemental function
2061
2062 @item @emph{Syntax}:
2063 @code{RESULT = BTEST(I, POS)}
2064
2065 @item @emph{Arguments}:
2066 @multitable @columnfractions .15 .70
2067 @item @var{I} @tab The type shall be @code{INTEGER}.
2068 @item @var{POS} @tab The type shall be @code{INTEGER}.
2069 @end multitable
2070
2071 @item @emph{Return value}:
2072 The return value is of type @code{LOGICAL}
2073
2074 @item @emph{Example}:
2075 @smallexample
2076 program test_btest
2077     integer :: i = 32768 + 1024 + 64
2078     integer :: pos
2079     logical :: bool
2080     do pos=0,16
2081         bool = btest(i, pos)
2082         print *, pos, bool
2083     end do
2084 end program test_btest
2085 @end smallexample
2086 @end table
2087
2088
2089 @node C_ASSOCIATED
2090 @section @code{C_ASSOCIATED} --- Status of a C pointer
2091 @fnindex C_ASSOCIATED
2092 @cindex association status, C pointer
2093 @cindex pointer, C association status
2094
2095 @table @asis
2096 @item @emph{Description}:
2097 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2098 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2099
2100 @item @emph{Standard}:
2101 Fortran 2003 and later
2102
2103 @item @emph{Class}:
2104 Inquiry function
2105
2106 @item @emph{Syntax}:
2107 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2108
2109 @item @emph{Arguments}:
2110 @multitable @columnfractions .15 .70
2111 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2112 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2113 @end multitable
2114
2115 @item @emph{Return value}:
2116 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2117 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2118 point to different addresses.
2119
2120 @item @emph{Example}:
2121 @smallexample
2122 subroutine association_test(a,b)
2123   use iso_c_binding, only: c_associated, c_loc, c_ptr
2124   implicit none
2125   real, pointer :: a
2126   type(c_ptr) :: b
2127   if(c_associated(b, c_loc(a))) &
2128      stop 'b and a do not point to same target'
2129 end subroutine association_test
2130 @end smallexample
2131
2132 @item @emph{See also}:
2133 @ref{C_LOC}, @ref{C_FUNLOC}
2134 @end table
2135
2136
2137 @node C_FUNLOC
2138 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2139 @fnindex C_FUNLOC
2140 @cindex pointer, C address of procedures
2141
2142 @table @asis
2143 @item @emph{Description}:
2144 @code{C_FUNLOC(x)} determines the C address of the argument.
2145
2146 @item @emph{Standard}:
2147 Fortran 2003 and later
2148
2149 @item @emph{Class}:
2150 Inquiry function
2151
2152 @item @emph{Syntax}:
2153 @code{RESULT = C_FUNLOC(x)}
2154
2155 @item @emph{Arguments}:
2156 @multitable @columnfractions .15 .70
2157 @item @var{x} @tab Interoperable function or pointer to such function.
2158 @end multitable
2159
2160 @item @emph{Return value}:
2161 The return value is of type @code{C_FUNPTR} and contains the C address
2162 of the argument.
2163
2164 @item @emph{Example}:
2165 @smallexample
2166 module x
2167   use iso_c_binding
2168   implicit none
2169 contains
2170   subroutine sub(a) bind(c)
2171     real(c_float) :: a
2172     a = sqrt(a)+5.0
2173   end subroutine sub
2174 end module x
2175 program main
2176   use iso_c_binding
2177   use x
2178   implicit none
2179   interface
2180     subroutine my_routine(p) bind(c,name='myC_func')
2181       import :: c_funptr
2182       type(c_funptr), intent(in) :: p
2183     end subroutine
2184   end interface
2185   call my_routine(c_funloc(sub))
2186 end program main
2187 @end smallexample
2188
2189 @item @emph{See also}:
2190 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2191 @end table
2192
2193
2194 @node C_F_PROCPOINTER
2195 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2196 @fnindex C_F_PROCPOINTER
2197 @cindex pointer, C address of pointers
2198
2199 @table @asis
2200 @item @emph{Description}:
2201 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2202 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2203
2204 @item @emph{Standard}:
2205 Fortran 2003 and later
2206
2207 @item @emph{Class}:
2208 Subroutine
2209
2210 @item @emph{Syntax}:
2211 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2212
2213 @item @emph{Arguments}:
2214 @multitable @columnfractions .15 .70
2215 @item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2216 @code{INTENT(IN)}.
2217 @item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2218 @code{INTENT(OUT)}.
2219 @end multitable
2220
2221 @item @emph{Example}:
2222 @smallexample
2223 program main
2224   use iso_c_binding
2225   implicit none
2226   abstract interface
2227     function func(a)
2228       import :: c_float
2229       real(c_float), intent(in) :: a
2230       real(c_float) :: func
2231     end function
2232   end interface
2233   interface
2234      function getIterFunc() bind(c,name="getIterFunc")
2235        import :: c_funptr
2236        type(c_funptr) :: getIterFunc
2237      end function
2238   end interface
2239   type(c_funptr) :: cfunptr
2240   procedure(func), pointer :: myFunc
2241   cfunptr = getIterFunc()
2242   call c_f_procpointer(cfunptr, myFunc)
2243 end program main
2244 @end smallexample
2245
2246 @item @emph{See also}:
2247 @ref{C_LOC}, @ref{C_F_POINTER}
2248 @end table
2249
2250
2251 @node C_F_POINTER
2252 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2253 @fnindex C_F_POINTER
2254 @cindex pointer, convert C to Fortran
2255
2256 @table @asis
2257 @item @emph{Description}:
2258 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2259 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2260 shape.
2261
2262 @item @emph{Standard}:
2263 Fortran 2003 and later
2264
2265 @item @emph{Class}:
2266 Subroutine
2267
2268 @item @emph{Syntax}:
2269 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2270
2271 @item @emph{Arguments}:
2272 @multitable @columnfractions .15 .70
2273 @item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2274 @code{INTENT(IN)}.
2275 @item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2276 @code{INTENT(OUT)}.
2277 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2278 with @code{INTENT(IN)}. It shall be present
2279 if and only if @var{fptr} is an array. The size
2280 must be equal to the rank of @var{fptr}.
2281 @end multitable
2282
2283 @item @emph{Example}:
2284 @smallexample
2285 program main
2286   use iso_c_binding
2287   implicit none
2288   interface
2289     subroutine my_routine(p) bind(c,name='myC_func')
2290       import :: c_ptr
2291       type(c_ptr), intent(out) :: p
2292     end subroutine
2293   end interface
2294   type(c_ptr) :: cptr
2295   real,pointer :: a(:)
2296   call my_routine(cptr)
2297   call c_f_pointer(cptr, a, [12])
2298 end program main
2299 @end smallexample
2300
2301 @item @emph{See also}:
2302 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2303 @end table
2304
2305
2306 @node C_LOC
2307 @section @code{C_LOC} --- Obtain the C address of an object
2308 @fnindex C_LOC
2309 @cindex procedure pointer, convert C to Fortran
2310
2311 @table @asis
2312 @item @emph{Description}:
2313 @code{C_LOC(X)} determines the C address of the argument.
2314
2315 @item @emph{Standard}:
2316 Fortran 2003 and later
2317
2318 @item @emph{Class}:
2319 Inquiry function
2320
2321 @item @emph{Syntax}:
2322 @code{RESULT = C_LOC(X)}
2323
2324 @item @emph{Arguments}:
2325 @multitable @columnfractions .10 .75
2326 @item @var{X} @tab  Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.
2327
2328 @end multitable
2329
2330 @item @emph{Return value}:
2331 The return value is of type @code{C_PTR} and contains the C address
2332 of the argument.
2333
2334 @item @emph{Example}:
2335 @smallexample
2336 subroutine association_test(a,b)
2337   use iso_c_binding, only: c_associated, c_loc, c_ptr
2338   implicit none
2339   real, pointer :: a
2340   type(c_ptr) :: b
2341   if(c_associated(b, c_loc(a))) &
2342      stop 'b and a do not point to same target'
2343 end subroutine association_test
2344 @end smallexample
2345
2346 @item @emph{See also}:
2347 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2348 @end table
2349
2350
2351 @node C_SIZEOF
2352 @section @code{C_SIZEOF} --- Size in bytes of an expression
2353 @fnindex C_SIZEOF
2354 @cindex expression size
2355 @cindex size of an expression
2356
2357 @table @asis
2358 @item @emph{Description}:
2359 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2360 expression @code{X} occupies.
2361
2362 @item @emph{Standard}:
2363 Fortran 2008
2364
2365 @item @emph{Class}:
2366 Intrinsic function
2367
2368 @item @emph{Syntax}:
2369 @code{N = C_SIZEOF(X)}
2370
2371 @item @emph{Arguments}:
2372 @multitable @columnfractions .15 .70
2373 @item @var{X} @tab The argument shall be an interoperable data entity.
2374 @end multitable
2375
2376 @item @emph{Return value}:
2377 The return value is of type integer and of the system-dependent kind
2378 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2379 number of bytes occupied by the argument.  If the argument has the
2380 @code{POINTER} attribute, the number of bytes of the storage area pointed
2381 to is returned.  If the argument is of a derived type with @code{POINTER}
2382 or @code{ALLOCATABLE} components, the return value doesn't account for
2383 the sizes of the data pointed to by these components.
2384
2385 @item @emph{Example}:
2386 @smallexample
2387    use iso_c_binding
2388    integer(c_int) :: i
2389    real(c_float) :: r, s(5)
2390    print *, (c_sizeof(s)/c_sizeof(r) == 5)
2391    end
2392 @end smallexample
2393 The example will print @code{.TRUE.} unless you are using a platform
2394 where default @code{REAL} variables are unusually padded.
2395
2396 @item @emph{See also}:
2397 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2398 @end table
2399
2400
2401 @node CEILING
2402 @section @code{CEILING} --- Integer ceiling function
2403 @fnindex CEILING
2404 @cindex ceiling
2405 @cindex rounding, ceiling
2406
2407 @table @asis
2408 @item @emph{Description}:
2409 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2410
2411 @item @emph{Standard}:
2412 Fortran 95 and later
2413
2414 @item @emph{Class}:
2415 Elemental function
2416
2417 @item @emph{Syntax}:
2418 @code{RESULT = CEILING(A [, KIND])}
2419
2420 @item @emph{Arguments}:
2421 @multitable @columnfractions .15 .70
2422 @item @var{A} @tab The type shall be @code{REAL}.
2423 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2424 expression indicating the kind parameter of the result.
2425 @end multitable
2426
2427 @item @emph{Return value}:
2428 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2429 and a default-kind @code{INTEGER} otherwise.
2430
2431 @item @emph{Example}:
2432 @smallexample
2433 program test_ceiling
2434     real :: x = 63.29
2435     real :: y = -63.59
2436     print *, ceiling(x) ! returns 64
2437     print *, ceiling(y) ! returns -63
2438 end program test_ceiling
2439 @end smallexample
2440
2441 @item @emph{See also}:
2442 @ref{FLOOR}, @ref{NINT}
2443
2444 @end table
2445
2446
2447
2448 @node CHAR
2449 @section @code{CHAR} --- Character conversion function
2450 @fnindex CHAR
2451 @cindex conversion, to character
2452
2453 @table @asis
2454 @item @emph{Description}:
2455 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2456
2457 @item @emph{Standard}:
2458 Fortran 77 and later
2459
2460 @item @emph{Class}:
2461 Elemental function
2462
2463 @item @emph{Syntax}:
2464 @code{RESULT = CHAR(I [, KIND])}
2465
2466 @item @emph{Arguments}:
2467 @multitable @columnfractions .15 .70
2468 @item @var{I} @tab The type shall be @code{INTEGER}.
2469 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2470 expression indicating the kind parameter of the result.
2471 @end multitable
2472
2473 @item @emph{Return value}:
2474 The return value is of type @code{CHARACTER(1)}
2475
2476 @item @emph{Example}:
2477 @smallexample
2478 program test_char
2479     integer :: i = 74
2480     character(1) :: c
2481     c = char(i)
2482     print *, i, c ! returns 'J'
2483 end program test_char
2484 @end smallexample
2485
2486 @item @emph{Specific names}:
2487 @multitable @columnfractions .20 .20 .20 .25
2488 @item Name           @tab Argument         @tab Return type             @tab Standard
2489 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2490 @end multitable
2491
2492 @item @emph{Note}:
2493 See @ref{ICHAR} for a discussion of converting between numerical values
2494 and formatted string representations.
2495
2496 @item @emph{See also}:
2497 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2498
2499 @end table
2500
2501
2502
2503 @node CHDIR
2504 @section @code{CHDIR} --- Change working directory
2505 @fnindex CHDIR
2506 @cindex system, working directory
2507
2508 @table @asis
2509 @item @emph{Description}:
2510 Change current working directory to a specified path.
2511
2512 This intrinsic is provided in both subroutine and function forms; however,
2513 only one form can be used in any given program unit.
2514
2515 @item @emph{Standard}:
2516 GNU extension
2517
2518 @item @emph{Class}:
2519 Subroutine, function
2520
2521 @item @emph{Syntax}:
2522 @multitable @columnfractions .80
2523 @item @code{CALL CHDIR(NAME [, STATUS])}
2524 @item @code{STATUS = CHDIR(NAME)}
2525 @end multitable
2526
2527 @item @emph{Arguments}:
2528 @multitable @columnfractions .15 .70
2529 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2530 kind and shall specify a valid path within the file system.
2531 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2532 kind.  Returns 0 on success, and a system specific and nonzero error code
2533 otherwise.
2534 @end multitable
2535
2536 @item @emph{Example}:
2537 @smallexample
2538 PROGRAM test_chdir
2539   CHARACTER(len=255) :: path
2540   CALL getcwd(path)
2541   WRITE(*,*) TRIM(path)
2542   CALL chdir("/tmp")
2543   CALL getcwd(path)
2544   WRITE(*,*) TRIM(path)
2545 END PROGRAM
2546 @end smallexample
2547
2548 @item @emph{See also}:
2549 @ref{GETCWD}
2550 @end table
2551
2552
2553
2554 @node CHMOD
2555 @section @code{CHMOD} --- Change access permissions of files
2556 @fnindex CHMOD
2557 @cindex file system, change access mode
2558
2559 @table @asis
2560 @item @emph{Description}:
2561 @code{CHMOD} changes the permissions of a file. This function invokes
2562 @code{/bin/chmod} and might therefore not work on all platforms.
2563
2564 This intrinsic is provided in both subroutine and function forms; however,
2565 only one form can be used in any given program unit.
2566
2567 @item @emph{Standard}:
2568 GNU extension
2569
2570 @item @emph{Class}:
2571 Subroutine, function
2572
2573 @item @emph{Syntax}:
2574 @multitable @columnfractions .80
2575 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2576 @item @code{STATUS = CHMOD(NAME, MODE)}
2577 @end multitable
2578
2579 @item @emph{Arguments}:
2580 @multitable @columnfractions .15 .70
2581
2582 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2583 file name. Trailing blanks are ignored unless the character
2584 @code{achar(0)} is present, then all characters up to and excluding
2585 @code{achar(0)} are used as the file name.
2586
2587 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2588 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2589 argument of @code{/bin/chmod}.
2590
2591 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2592 @code{0} on success and nonzero otherwise.
2593 @end multitable
2594
2595 @item @emph{Return value}:
2596 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2597 otherwise.
2598
2599 @item @emph{Example}:
2600 @code{CHMOD} as subroutine
2601 @smallexample
2602 program chmod_test
2603   implicit none
2604   integer :: status
2605   call chmod('test.dat','u+x',status)
2606   print *, 'Status: ', status
2607 end program chmod_test
2608 @end smallexample
2609 @code{CHMOD} as function:
2610 @smallexample
2611 program chmod_test
2612   implicit none
2613   integer :: status
2614   status = chmod('test.dat','u+x')
2615   print *, 'Status: ', status
2616 end program chmod_test
2617 @end smallexample
2618
2619 @end table
2620
2621
2622
2623 @node CMPLX
2624 @section @code{CMPLX} --- Complex conversion function
2625 @fnindex CMPLX
2626 @cindex complex numbers, conversion to
2627 @cindex conversion, to complex
2628
2629 @table @asis
2630 @item @emph{Description}:
2631 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2632 the real component.  If @var{Y} is present it is converted to the imaginary
2633 component.  If @var{Y} is not present then the imaginary component is set to
2634 0.0.  If @var{X} is complex then @var{Y} must not be present.
2635
2636 @item @emph{Standard}:
2637 Fortran 77 and later
2638
2639 @item @emph{Class}:
2640 Elemental function
2641
2642 @item @emph{Syntax}:
2643 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2644
2645 @item @emph{Arguments}:
2646 @multitable @columnfractions .15 .70
2647 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2648 or @code{COMPLEX}.
2649 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2650 @code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
2651 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2652 expression indicating the kind parameter of the result.
2653 @end multitable
2654
2655 @item @emph{Return value}:
2656 The return value is of @code{COMPLEX} type, with a kind equal to
2657 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2658 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2659 @var{X} and @var{Y}.
2660
2661 @item @emph{Example}:
2662 @smallexample
2663 program test_cmplx
2664     integer :: i = 42
2665     real :: x = 3.14
2666     complex :: z
2667     z = cmplx(i, x)
2668     print *, z, cmplx(x)
2669 end program test_cmplx
2670 @end smallexample
2671
2672 @item @emph{See also}:
2673 @ref{COMPLEX}
2674 @end table
2675
2676
2677
2678 @node COMMAND_ARGUMENT_COUNT
2679 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2680 @fnindex COMMAND_ARGUMENT_COUNT
2681 @cindex command-line arguments
2682 @cindex command-line arguments, number of
2683 @cindex arguments, to program
2684
2685 @table @asis
2686 @item @emph{Description}:
2687 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2688 command line when the containing program was invoked.
2689
2690 @item @emph{Standard}:
2691 Fortran 2003 and later
2692
2693 @item @emph{Class}:
2694 Inquiry function
2695
2696 @item @emph{Syntax}:
2697 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2698
2699 @item @emph{Arguments}:
2700 @multitable @columnfractions .15 .70
2701 @item None
2702 @end multitable
2703
2704 @item @emph{Return value}:
2705 The return value is an @code{INTEGER} of default kind.
2706
2707 @item @emph{Example}:
2708 @smallexample
2709 program test_command_argument_count
2710     integer :: count
2711     count = command_argument_count()
2712     print *, count
2713 end program test_command_argument_count
2714 @end smallexample
2715
2716 @item @emph{See also}:
2717 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2718 @end table
2719
2720
2721
2722 @node COMPLEX
2723 @section @code{COMPLEX} --- Complex conversion function
2724 @fnindex COMPLEX
2725 @cindex complex numbers, conversion to
2726 @cindex conversion, to complex
2727
2728 @table @asis
2729 @item @emph{Description}:
2730 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2731 to the real component and @var{Y} is converted to the imaginary
2732 component.
2733
2734 @item @emph{Standard}:
2735 GNU extension
2736
2737 @item @emph{Class}:
2738 Elemental function
2739
2740 @item @emph{Syntax}:
2741 @code{RESULT = COMPLEX(X, Y)}
2742
2743 @item @emph{Arguments}:
2744 @multitable @columnfractions .15 .70
2745 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2746 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2747 @end multitable
2748
2749 @item @emph{Return value}:
2750 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2751 value is of default @code{COMPLEX} type.
2752
2753 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2754 type and one is of @code{INTEGER} type, then the return value is of
2755 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2756 argument with the highest precision.
2757
2758 @item @emph{Example}:
2759 @smallexample
2760 program test_complex
2761     integer :: i = 42
2762     real :: x = 3.14
2763     print *, complex(i, x)
2764 end program test_complex
2765 @end smallexample
2766
2767 @item @emph{See also}:
2768 @ref{CMPLX}
2769 @end table
2770
2771
2772
2773 @node CONJG
2774 @section @code{CONJG} --- Complex conjugate function
2775 @fnindex CONJG
2776 @fnindex DCONJG
2777 @cindex complex conjugate
2778
2779 @table @asis
2780 @item @emph{Description}:
2781 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2782 then the result is @code{(x, -y)}
2783
2784 @item @emph{Standard}:
2785 Fortran 77 and later, has overloads that are GNU extensions
2786
2787 @item @emph{Class}:
2788 Elemental function
2789
2790 @item @emph{Syntax}:
2791 @code{Z = CONJG(Z)}
2792
2793 @item @emph{Arguments}:
2794 @multitable @columnfractions .15 .70
2795 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2796 @end multitable
2797
2798 @item @emph{Return value}:
2799 The return value is of type @code{COMPLEX}.
2800
2801 @item @emph{Example}:
2802 @smallexample
2803 program test_conjg
2804     complex :: z = (2.0, 3.0)
2805     complex(8) :: dz = (2.71_8, -3.14_8)
2806     z= conjg(z)
2807     print *, z
2808     dz = dconjg(dz)
2809     print *, dz
2810 end program test_conjg
2811 @end smallexample
2812
2813 @item @emph{Specific names}:
2814 @multitable @columnfractions .20 .20 .20 .25
2815 @item Name             @tab Argument             @tab Return type       @tab Standard
2816 @item @code{CONJG(Z)}  @tab @code{COMPLEX Z}     @tab @code{COMPLEX}    @tab GNU extension
2817 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)} @tab GNU extension
2818 @end multitable
2819 @end table
2820
2821
2822
2823 @node COS
2824 @section @code{COS} --- Cosine function
2825 @fnindex COS
2826 @fnindex DCOS
2827 @fnindex CCOS
2828 @fnindex ZCOS
2829 @fnindex CDCOS
2830 @cindex trigonometric function, cosine
2831 @cindex cosine
2832
2833 @table @asis
2834 @item @emph{Description}:
2835 @code{COS(X)} computes the cosine of @var{X}.
2836
2837 @item @emph{Standard}:
2838 Fortran 77 and later, has overloads that are GNU extensions
2839
2840 @item @emph{Class}:
2841 Elemental function
2842
2843 @item @emph{Syntax}:
2844 @code{RESULT = COS(X)}
2845
2846 @item @emph{Arguments}:
2847 @multitable @columnfractions .15 .70
2848 @item @var{X} @tab The type shall be @code{REAL} or
2849 @code{COMPLEX}.
2850 @end multitable
2851
2852 @item @emph{Return value}:
2853 The return value is of the same type and kind as @var{X}. The real part
2854 of the result is in radians. If @var{X} is of the type @code{REAL},
2855 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2856
2857 @item @emph{Example}:
2858 @smallexample
2859 program test_cos
2860   real :: x = 0.0
2861   x = cos(x)
2862 end program test_cos
2863 @end smallexample
2864
2865 @item @emph{Specific names}:
2866 @multitable @columnfractions .20 .20 .20 .25
2867 @item Name            @tab Argument            @tab Return type       @tab Standard
2868 @item @code{COS(X)}   @tab @code{REAL(4) X}    @tab @code{REAL(4)}    @tab Fortran 77 and later
2869 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
2870 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2871 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2872 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2873 @end multitable
2874
2875 @item @emph{See also}:
2876 Inverse function: @ref{ACOS}
2877
2878 @end table
2879
2880
2881
2882 @node COSH
2883 @section @code{COSH} --- Hyperbolic cosine function
2884 @fnindex COSH
2885 @fnindex DCOSH
2886 @cindex hyperbolic cosine
2887 @cindex hyperbolic function, cosine
2888 @cindex cosine, hyperbolic
2889
2890 @table @asis
2891 @item @emph{Description}:
2892 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2893
2894 @item @emph{Standard}:
2895 Fortran 77 and later, for a complex argument Fortran 2008 or later
2896
2897 @item @emph{Class}:
2898 Elemental function
2899
2900 @item @emph{Syntax}:
2901 @code{X = COSH(X)}
2902
2903 @item @emph{Arguments}:
2904 @multitable @columnfractions .15 .70
2905 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2906 @end multitable
2907
2908 @item @emph{Return value}:
2909 The return value has same type and kind as @var{X}. If @var{X} is
2910 complex, the imaginary part of the result is in radians. If @var{X}
2911 is @code{REAL}, the return value has a lower bound of one,
2912 @math{\cosh (x) \geq 1}.
2913
2914 @item @emph{Example}:
2915 @smallexample
2916 program test_cosh
2917   real(8) :: x = 1.0_8
2918   x = cosh(x)
2919 end program test_cosh
2920 @end smallexample
2921
2922 @item @emph{Specific names}:
2923 @multitable @columnfractions .20 .20 .20 .25
2924 @item Name            @tab Argument          @tab Return type       @tab Standard
2925 @item @code{COSH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
2926 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
2927 @end multitable
2928
2929 @item @emph{See also}:
2930 Inverse function: @ref{ACOSH}
2931
2932 @end table
2933
2934
2935
2936 @node COUNT
2937 @section @code{COUNT} --- Count function
2938 @fnindex COUNT
2939 @cindex array, conditionally count elements
2940 @cindex array, element counting
2941 @cindex array, number of elements
2942
2943 @table @asis
2944 @item @emph{Description}:
2945
2946 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2947 or, if the @var{DIM} argument is supplied, counts the number of
2948 elements along each row of the array in the @var{DIM} direction.
2949 If the array has zero size, or all of the elements of @var{MASK} are
2950 @code{.FALSE.}, then the result is @code{0}.
2951
2952 @item @emph{Standard}:
2953 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2954
2955 @item @emph{Class}:
2956 Transformational function
2957
2958 @item @emph{Syntax}:
2959 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2960
2961 @item @emph{Arguments}:
2962 @multitable @columnfractions .15 .70
2963 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2964 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
2965 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2966 expression indicating the kind parameter of the result.
2967 @end multitable
2968
2969 @item @emph{Return value}:
2970 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2971 @var{KIND} is absent, the return value is of default integer kind.
2972 If @var{DIM} is present, the result is an array with a rank one less
2973 than the rank of @var{ARRAY}, and a size corresponding to the shape
2974 of @var{ARRAY} with the @var{DIM} dimension removed.
2975
2976 @item @emph{Example}:
2977 @smallexample
2978 program test_count
2979     integer, dimension(2,3) :: a, b
2980     logical, dimension(2,3) :: mask
2981     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2982     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2983     print '(3i3)', a(1,:)
2984     print '(3i3)', a(2,:)
2985     print *
2986     print '(3i3)', b(1,:)
2987     print '(3i3)', b(2,:)
2988     print *
2989     mask = a.ne.b
2990     print '(3l3)', mask(1,:)
2991     print '(3l3)', mask(2,:)
2992     print *
2993     print '(3i3)', count(mask)
2994     print *
2995     print '(3i3)', count(mask, 1)
2996     print *
2997     print '(3i3)', count(mask, 2)
2998 end program test_count
2999 @end smallexample
3000 @end table
3001
3002
3003
3004 @node CPU_TIME
3005 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3006 @fnindex CPU_TIME
3007 @cindex time, elapsed
3008
3009 @table @asis
3010 @item @emph{Description}:
3011 Returns a @code{REAL} value representing the elapsed CPU time in
3012 seconds.  This is useful for testing segments of code to determine
3013 execution time.
3014
3015 If a time source is available, time will be reported with microsecond
3016 resolution. If no time source is available, @var{TIME} is set to
3017 @code{-1.0}.
3018
3019 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3020 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3021 value is meaningless, only differences between subsequent calls to
3022 this subroutine, as shown in the example below, should be used.
3023
3024
3025 @item @emph{Standard}:
3026 Fortran 95 and later
3027
3028 @item @emph{Class}:
3029 Subroutine
3030
3031 @item @emph{Syntax}:
3032 @code{CALL CPU_TIME(TIME)}
3033
3034 @item @emph{Arguments}:
3035 @multitable @columnfractions .15 .70
3036 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3037 @end multitable
3038
3039 @item @emph{Return value}:
3040 None
3041
3042 @item @emph{Example}:
3043 @smallexample
3044 program test_cpu_time
3045     real :: start, finish
3046     call cpu_time(start)
3047         ! put code to test here
3048     call cpu_time(finish)
3049     print '("Time = ",f6.3," seconds.")',finish-start
3050 end program test_cpu_time
3051 @end smallexample
3052
3053 @item @emph{See also}:
3054 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3055 @end table
3056
3057
3058
3059 @node CSHIFT
3060 @section @code{CSHIFT} --- Circular shift elements of an array
3061 @fnindex CSHIFT
3062 @cindex array, shift circularly
3063 @cindex array, permutation
3064 @cindex array, rotate
3065
3066 @table @asis
3067 @item @emph{Description}:
3068 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3069 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
3070 taken to be @code{1}.  @var{DIM} is a scalar of type @code{INTEGER} in the
3071 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3072 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3073 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
3074 sections of @var{ARRAY} along the given dimension are shifted.  Elements
3075 shifted out one end of each rank one section are shifted back in the other end.
3076
3077 @item @emph{Standard}:
3078 Fortran 95 and later
3079
3080 @item @emph{Class}:
3081 Transformational function
3082
3083 @item @emph{Syntax}:
3084 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3085
3086 @item @emph{Arguments}:
3087 @multitable @columnfractions .15 .70
3088 @item @var{ARRAY}  @tab Shall be an array of any type.
3089 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3090 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3091 @end multitable
3092
3093 @item @emph{Return value}:
3094 Returns an array of same type and rank as the @var{ARRAY} argument.
3095
3096 @item @emph{Example}:
3097 @smallexample
3098 program test_cshift
3099     integer, dimension(3,3) :: a
3100     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3101     print '(3i3)', a(1,:)
3102     print '(3i3)', a(2,:)
3103     print '(3i3)', a(3,:)
3104     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3105     print *
3106     print '(3i3)', a(1,:)
3107     print '(3i3)', a(2,:)
3108     print '(3i3)', a(3,:)
3109 end program test_cshift
3110 @end smallexample
3111 @end table
3112
3113
3114
3115 @node CTIME
3116 @section @code{CTIME} --- Convert a time into a string
3117 @fnindex CTIME
3118 @cindex time, conversion to string
3119 @cindex conversion, to string
3120
3121 @table @asis
3122 @item @emph{Description}:
3123 @code{CTIME} converts a system time value, such as returned by
3124 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
3125
3126 This intrinsic is provided in both subroutine and function forms; however,
3127 only one form can be used in any given program unit.
3128
3129 @item @emph{Standard}:
3130 GNU extension
3131
3132 @item @emph{Class}:
3133 Subroutine, function
3134
3135 @item @emph{Syntax}:
3136 @multitable @columnfractions .80
3137 @item @code{CALL CTIME(TIME, RESULT)}.
3138 @item @code{RESULT = CTIME(TIME)}, (not recommended).
3139 @end multitable
3140
3141 @item @emph{Arguments}:
3142 @multitable @columnfractions .15 .70
3143 @item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
3144 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
3145 of default kind.
3146 @end multitable
3147
3148 @item @emph{Return value}:
3149 The converted date and time as a string.
3150
3151 @item @emph{Example}:
3152 @smallexample
3153 program test_ctime
3154     integer(8) :: i
3155     character(len=30) :: date
3156     i = time8()
3157
3158     ! Do something, main part of the program
3159
3160     call ctime(i,date)
3161     print *, 'Program was started on ', date
3162 end program test_ctime
3163 @end smallexample
3164
3165 @item @emph{See Also}:
3166 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3167 @end table
3168
3169
3170
3171 @node DATE_AND_TIME
3172 @section @code{DATE_AND_TIME} --- Date and time subroutine
3173 @fnindex DATE_AND_TIME
3174 @cindex date, current
3175 @cindex current date
3176 @cindex time, current
3177 @cindex current time
3178
3179 @table @asis
3180 @item @emph{Description}:
3181 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3182 time information from the real-time system clock.  @var{DATE} is
3183 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
3184 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3185 representing the difference with respect to Coordinated Universal Time (UTC).
3186 Unavailable time and date parameters return blanks.
3187
3188 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3189
3190 @multitable @columnfractions .15 .30 .40
3191 @item @tab @code{VALUE(1)}: @tab The year
3192 @item @tab @code{VALUE(2)}: @tab The month
3193 @item @tab @code{VALUE(3)}: @tab The day of the month
3194 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3195 @item @tab @code{VALUE(5)}: @tab The hour of the day
3196 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3197 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3198 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3199 @end multitable
3200
3201 @item @emph{Standard}:
3202 Fortran 95 and later
3203
3204 @item @emph{Class}:
3205 Subroutine
3206
3207 @item @emph{Syntax}:
3208 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3209
3210 @item @emph{Arguments}:
3211 @multitable @columnfractions .15 .70
3212 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3213 or larger, and of default kind.
3214 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3215 or larger, and of default kind.
3216 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3217 or larger, and of default kind.
3218 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3219 @end multitable
3220
3221 @item @emph{Return value}:
3222 None
3223
3224 @item @emph{Example}:
3225 @smallexample
3226 program test_time_and_date
3227     character(8)  :: date
3228     character(10) :: time
3229     character(5)  :: zone
3230     integer,dimension(8) :: values
3231     ! using keyword arguments
3232     call date_and_time(date,time,zone,values)
3233     call date_and_time(DATE=date,ZONE=zone)
3234     call date_and_time(TIME=time)
3235     call date_and_time(VALUES=values)
3236     print '(a,2x,a,2x,a)', date, time, zone
3237     print '(8i5))', values
3238 end program test_time_and_date
3239 @end smallexample
3240
3241 @item @emph{See also}:
3242 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3243 @end table
3244
3245
3246
3247 @node DBLE
3248 @section @code{DBLE} --- Double conversion function
3249 @fnindex DBLE
3250 @cindex conversion, to real
3251
3252 @table @asis
3253 @item @emph{Description}:
3254 @code{DBLE(A)} Converts @var{A} to double precision real type.
3255
3256 @item @emph{Standard}:
3257 Fortran 77 and later
3258
3259 @item @emph{Class}:
3260 Elemental function
3261
3262 @item @emph{Syntax}:
3263 @code{RESULT = DBLE(A)}
3264
3265 @item @emph{Arguments}:
3266 @multitable @columnfractions .15 .70
3267 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3268 or @code{COMPLEX}.
3269 @end multitable
3270
3271 @item @emph{Return value}:
3272 The return value is of type double precision real.
3273
3274 @item @emph{Example}:
3275 @smallexample
3276 program test_dble
3277     real    :: x = 2.18
3278     integer :: i = 5
3279     complex :: z = (2.3,1.14)
3280     print *, dble(x), dble(i), dble(z)
3281 end program test_dble
3282 @end smallexample
3283
3284 @item @emph{See also}:
3285 @ref{REAL}
3286 @end table
3287
3288
3289
3290 @node DCMPLX
3291 @section @code{DCMPLX} --- Double complex conversion function
3292 @fnindex DCMPLX
3293 @cindex complex numbers, conversion to
3294 @cindex conversion, to complex
3295
3296 @table @asis
3297 @item @emph{Description}:
3298 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3299 converted to the real component.  If @var{Y} is present it is converted to the
3300 imaginary component.  If @var{Y} is not present then the imaginary component is
3301 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3302
3303 @item @emph{Standard}:
3304 GNU extension
3305
3306 @item @emph{Class}:
3307 Elemental function
3308
3309 @item @emph{Syntax}:
3310 @code{RESULT = DCMPLX(X [, Y])}
3311
3312 @item @emph{Arguments}:
3313 @multitable @columnfractions .15 .70
3314 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3315 or @code{COMPLEX}.
3316 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3317 @code{INTEGER} or @code{REAL}.
3318 @end multitable
3319
3320 @item @emph{Return value}:
3321 The return value is of type @code{COMPLEX(8)}
3322
3323 @item @emph{Example}:
3324 @smallexample
3325 program test_dcmplx
3326     integer :: i = 42
3327     real :: x = 3.14
3328     complex :: z
3329     z = cmplx(i, x)
3330     print *, dcmplx(i)
3331     print *, dcmplx(x)
3332     print *, dcmplx(z)
3333     print *, dcmplx(x,i)
3334 end program test_dcmplx
3335 @end smallexample
3336 @end table
3337
3338
3339 @node DIGITS
3340 @section @code{DIGITS} --- Significant binary digits function
3341 @fnindex DIGITS
3342 @cindex model representation, significant digits
3343
3344 @table @asis
3345 @item @emph{Description}:
3346 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3347 model representation of @var{X}.  For example, on a system using a 32-bit
3348 floating point representation, a default real number would likely return 24.
3349
3350 @item @emph{Standard}:
3351 Fortran 95 and later
3352
3353 @item @emph{Class}:
3354 Inquiry function
3355
3356 @item @emph{Syntax}:
3357 @code{RESULT = DIGITS(X)}
3358
3359 @item @emph{Arguments}:
3360 @multitable @columnfractions .15 .70
3361 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3362 @end multitable
3363
3364 @item @emph{Return value}:
3365 The return value is of type @code{INTEGER}.
3366
3367 @item @emph{Example}:
3368 @smallexample
3369 program test_digits
3370     integer :: i = 12345
3371     real :: x = 3.143
3372     real(8) :: y = 2.33
3373     print *, digits(i)
3374     print *, digits(x)
3375     print *, digits(y)
3376 end program test_digits
3377 @end smallexample
3378 @end table
3379
3380
3381
3382 @node DIM
3383 @section @code{DIM} --- Positive difference
3384 @fnindex DIM
3385 @fnindex IDIM
3386 @fnindex DDIM
3387 @cindex positive difference
3388
3389 @table @asis
3390 @item @emph{Description}:
3391 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3392 otherwise returns zero.
3393
3394 @item @emph{Standard}:
3395 Fortran 77 and later
3396
3397 @item @emph{Class}:
3398 Elemental function
3399
3400 @item @emph{Syntax}:
3401 @code{RESULT = DIM(X, Y)}
3402
3403 @item @emph{Arguments}:
3404 @multitable @columnfractions .15 .70
3405 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3406 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3407 @end multitable
3408
3409 @item @emph{Return value}:
3410 The return value is of type @code{INTEGER} or @code{REAL}.
3411
3412 @item @emph{Example}:
3413 @smallexample
3414 program test_dim
3415     integer :: i
3416     real(8) :: x
3417     i = dim(4, 15)
3418     x = dim(4.345_8, 2.111_8)
3419     print *, i
3420     print *, x
3421 end program test_dim
3422 @end smallexample
3423
3424 @item @emph{Specific names}:
3425 @multitable @columnfractions .20 .20 .20 .25
3426 @item Name             @tab Argument               @tab Return type       @tab Standard
3427 @item @code{DIM(X,Y)}  @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3428 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3429 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3430 @end multitable
3431 @end table
3432
3433
3434
3435 @node DOT_PRODUCT
3436 @section @code{DOT_PRODUCT} --- Dot product function
3437 @fnindex DOT_PRODUCT
3438 @cindex dot product
3439 @cindex vector product
3440 @cindex product, vector
3441
3442 @table @asis
3443 @item @emph{Description}:
3444 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3445 of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3446 either numeric or logical and must be arrays of rank one and of equal size. If
3447 the vectors are @code{INTEGER} or @code{REAL}, the result is
3448 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3449 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3450 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3451
3452 @item @emph{Standard}:
3453 Fortran 95 and later
3454
3455 @item @emph{Class}:
3456 Transformational function
3457
3458 @item @emph{Syntax}:
3459 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3460
3461 @item @emph{Arguments}:
3462 @multitable @columnfractions .15 .70
3463 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3464 @item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
3465 @end multitable
3466
3467 @item @emph{Return value}:
3468 If the arguments are numeric, the return value is a scalar of numeric type,
3469 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3470 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3471
3472 @item @emph{Example}:
3473 @smallexample
3474 program test_dot_prod
3475     integer, dimension(3) :: a, b
3476     a = (/ 1, 2, 3 /)
3477     b = (/ 4, 5, 6 /)
3478     print '(3i3)', a
3479     print *
3480     print '(3i3)', b
3481     print *
3482     print *, dot_product(a,b)
3483 end program test_dot_prod
3484 @end smallexample
3485 @end table
3486
3487
3488
3489 @node DPROD
3490 @section @code{DPROD} --- Double product function
3491 @fnindex DPROD
3492 @cindex product, double-precision
3493
3494 @table @asis
3495 @item @emph{Description}:
3496 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3497
3498 @item @emph{Standard}:
3499 Fortran 77 and later
3500
3501 @item @emph{Class}:
3502 Elemental function
3503
3504 @item @emph{Syntax}:
3505 @code{RESULT = DPROD(X, Y)}
3506
3507 @item @emph{Arguments}:
3508 @multitable @columnfractions .15 .70
3509 @item @var{X} @tab The type shall be @code{REAL}.
3510 @item @var{Y} @tab The type shall be @code{REAL}.
3511 @end multitable
3512
3513 @item @emph{Return value}:
3514 The return value is of type @code{REAL(8)}.
3515
3516 @item @emph{Example}:
3517 @smallexample
3518 program test_dprod
3519     real :: x = 5.2
3520     real :: y = 2.3
3521     real(8) :: d
3522     d = dprod(x,y)
3523     print *, d
3524 end program test_dprod
3525 @end smallexample
3526
3527 @item @emph{Specific names}:
3528 @multitable @columnfractions .20 .20 .20 .25
3529 @item Name              @tab Argument               @tab Return type       @tab Standard
3530 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3531 @end multitable
3532
3533 @end table
3534
3535
3536 @node DREAL
3537 @section @code{DREAL} --- Double real part function
3538 @fnindex DREAL
3539 @cindex complex numbers, real part
3540
3541 @table @asis
3542 @item @emph{Description}:
3543 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3544
3545 @item @emph{Standard}:
3546 GNU extension
3547
3548 @item @emph{Class}:
3549 Elemental function
3550
3551 @item @emph{Syntax}:
3552 @code{RESULT = DREAL(A)}
3553
3554 @item @emph{Arguments}:
3555 @multitable @columnfractions .15 .70
3556 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3557 @end multitable
3558
3559 @item @emph{Return value}:
3560 The return value is of type @code{REAL(8)}.
3561
3562 @item @emph{Example}:
3563 @smallexample
3564 program test_dreal
3565     complex(8) :: z = (1.3_8,7.2_8)
3566     print *, dreal(z)
3567 end program test_dreal
3568 @end smallexample
3569
3570 @item @emph{See also}:
3571 @ref{AIMAG}
3572
3573 @end table
3574
3575
3576
3577 @node DSHIFTL
3578 @section @code{DSHIFTL} --- Combined left shift
3579 @fnindex DSHIFTL
3580 @cindex left shift, combined
3581 @cindex shift, left
3582
3583 @table @asis
3584 @item @emph{Description}:
3585 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3586 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3587 bits of @var{J}, and the remaining bits are the rightmost bits of
3588 @var{I}.
3589
3590 @item @emph{Standard}:
3591 Fortran 2008 and later
3592
3593 @item @emph{Class}:
3594 Elemental function
3595
3596 @item @emph{Syntax}:
3597 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3598
3599 @item @emph{Arguments}:
3600 @multitable @columnfractions .15 .70
3601 @item @var{I} @tab Shall be of type @code{INTEGER}.
3602 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3603 as @var{I}.
3604 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3605 @end multitable
3606
3607 @item @emph{Return value}:
3608 The return value has same type and kind as @var{I}.
3609
3610 @item @emph{See also}:
3611 @ref{DSHIFTR}
3612
3613 @end table
3614
3615
3616
3617 @node DSHIFTR
3618 @section @code{DSHIFTR} --- Combined right shift
3619 @fnindex DSHIFTR
3620 @cindex right shift, combined
3621 @cindex shift, right
3622
3623 @table @asis
3624 @item @emph{Description}:
3625 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3626 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3627 bits of @var{I}, and the remaining bits are the leftmost bits of
3628 @var{J}.
3629
3630 @item @emph{Standard}:
3631 Fortran 2008 and later
3632
3633 @item @emph{Class}:
3634 Elemental function
3635
3636 @item @emph{Syntax}:
3637 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3638
3639 @item @emph{Arguments}:
3640 @multitable @columnfractions .15 .70
3641 @item @var{I} @tab Shall be of type @code{INTEGER}.
3642 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3643 as @var{I}.
3644 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3645 @end multitable
3646
3647 @item @emph{Return value}:
3648 The return value has same type and kind as @var{I}.
3649
3650 @item @emph{See also}:
3651 @ref{DSHIFTL}
3652
3653 @end table
3654
3655
3656
3657 @node DTIME
3658 @section @code{DTIME} --- Execution time subroutine (or function)
3659 @fnindex DTIME
3660 @cindex time, elapsed
3661 @cindex elapsed time
3662
3663 @table @asis
3664 @item @emph{Description}:
3665 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3666 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3667 returns the user and system components of this time in @code{VALUES(1)} and
3668 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3669 VALUES(2)}.
3670
3671 Subsequent invocations of @code{DTIME} return values accumulated since the
3672 previous invocation.
3673
3674 On some systems, the underlying timings are represented using types with
3675 sufficiently small limits that overflows (wrap around) are possible, such as
3676 32-bit types. Therefore, the values returned by this intrinsic might be, or
3677 become, negative, or numerically less than previous values, during a single
3678 run of the compiled program.
3679
3680 Please note, that this implementation is thread safe if used within OpenMP
3681 directives, i.e., its state will be consistent while called from multiple
3682 threads. However, if @code{DTIME} is called from multiple threads, the result
3683 is still the time since the last invocation. This may not give the intended
3684 results. If possible, use @code{CPU_TIME} instead.
3685
3686 This intrinsic is provided in both subroutine and function forms; however,
3687 only one form can be used in any given program unit.
3688
3689 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3690
3691 @multitable @columnfractions .15 .30 .40
3692 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3693 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3694 @item @tab @code{TIME}: @tab Run time since start in seconds.
3695 @end multitable
3696