1@ignore 2Copyright (C) 2005-2018 Free Software Foundation, Inc. 3This is part of the GNU Fortran manual. 4For copying conditions, see the file gfortran.texi. 5 6Permission is granted to copy, distribute and/or modify this document 7under the terms of the GNU Free Documentation License, Version 1.3 or 8any later version published by the Free Software Foundation; with the 9Invariant Sections being ``Funding Free Software'', the Front-Cover 10Texts being (a) (see below), and with the Back-Cover Texts being (b) 11(see below). A copy of the license is included in the gfdl(7) man page. 12 13 14Some basic guidelines for editing this document: 15 16 (1) The intrinsic procedures are to be listed in alphabetical order. 17 (2) The generic name is to be used. 18 (3) The specific names are included in the function index and in a 19 table at the end of the node (See ABS entry). 20 (4) Try to maintain the same style for each entry. 21 22 23@end ignore 24 25@tex 26\gdef\acosd{\mathop{\rm acosd}\nolimits} 27\gdef\asind{\mathop{\rm asind}\nolimits} 28\gdef\atand{\mathop{\rm atand}\nolimits} 29\gdef\acos{\mathop{\rm acos}\nolimits} 30\gdef\asin{\mathop{\rm asin}\nolimits} 31\gdef\atan{\mathop{\rm atan}\nolimits} 32\gdef\acosh{\mathop{\rm acosh}\nolimits} 33\gdef\asinh{\mathop{\rm asinh}\nolimits} 34\gdef\atanh{\mathop{\rm atanh}\nolimits} 35\gdef\cosd{\mathop{\rm cosd}\nolimits} 36@end tex 37 38 39@node Intrinsic Procedures 40@chapter Intrinsic Procedures 41@cindex intrinsic procedures 42 43@menu 44* Introduction: Introduction to Intrinsics 45* @code{ABORT}: ABORT, Abort the program 46* @code{ABS}: ABS, Absolute value 47* @code{ACCESS}: ACCESS, Checks file access modes 48* @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence 49* @code{ACOS}: ACOS, Arccosine function 50* @code{ACOSD}: ACOSD, Arccosine function, degrees 51* @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function 52* @code{ADJUSTL}: ADJUSTL, Left adjust a string 53* @code{ADJUSTR}: ADJUSTR, Right adjust a string 54* @code{AIMAG}: AIMAG, Imaginary part of complex number 55* @code{AINT}: AINT, Truncate to a whole number 56* @code{ALARM}: ALARM, Set an alarm clock 57* @code{ALL}: ALL, Determine if all values are true 58* @code{ALLOCATED}: ALLOCATED, Status of allocatable entity 59* @code{AND}: AND, Bitwise logical AND 60* @code{ANINT}: ANINT, Nearest whole number 61* @code{ANY}: ANY, Determine if any values are true 62* @code{ASIN}: ASIN, Arcsine function 63* @code{ASIND}: ASIND, Arcsine function, degrees 64* @code{ASINH}: ASINH, Inverse hyperbolic sine function 65* @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair 66* @code{ATAN}: ATAN, Arctangent function 67* @code{ATAND}: ATAND, Arctangent function, degrees 68* @code{ATAN2}: ATAN2, Arctangent function 69* @code{ATAN2D}: ATAN2D, Arctangent function, degrees 70* @code{ATANH}: ATANH, Inverse hyperbolic tangent function 71* @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation 72* @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation 73* @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap 74* @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically 75* @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch 76* @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch 77* @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch 78* @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch 79* @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation 80* @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically 81* @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation 82* @code{BACKTRACE}: BACKTRACE, Show a backtrace 83* @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0 84* @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1 85* @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind 86* @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0 87* @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1 88* @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind 89* @code{BGE}: BGE, Bitwise greater than or equal to 90* @code{BGT}: BGT, Bitwise greater than 91* @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function 92* @code{BLE}: BLE, Bitwise less than or equal to 93* @code{BLT}: BLT, Bitwise less than 94* @code{BTEST}: BTEST, Bit test function 95* @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer 96* @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer 97* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer 98* @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure 99* @code{C_LOC}: C_LOC, Obtain the C address of an object 100* @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression 101* @code{CEILING}: CEILING, Integer ceiling function 102* @code{CHAR}: CHAR, Integer-to-character conversion function 103* @code{CHDIR}: CHDIR, Change working directory 104* @code{CHMOD}: CHMOD, Change access permissions of files 105* @code{CMPLX}: CMPLX, Complex conversion function 106* @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images 107* @code{CO_MAX}: CO_MAX, Maximal value on the current set of images 108* @code{CO_MIN}: CO_MIN, Minimal value on the current set of images 109* @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images 110* @code{CO_SUM}: CO_SUM, Sum of values on the current set of images 111* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments 112* @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler 113* @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string 114* @code{COMPLEX}: COMPLEX, Complex conversion function 115* @code{CONJG}: CONJG, Complex conjugate function 116* @code{COS}: COS, Cosine function 117* @code{COSD}: COSD, Cosine function, degrees 118* @code{COSH}: COSH, Hyperbolic cosine function 119* @code{COTAN}: COTAN, Cotangent function 120* @code{COTAND}: COTAND, Cotangent function, degrees 121* @code{COUNT}: COUNT, Count occurrences of TRUE in an array 122* @code{CPU_TIME}: CPU_TIME, CPU time subroutine 123* @code{CSHIFT}: CSHIFT, Circular shift elements of an array 124* @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string 125* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine 126* @code{DBLE}: DBLE, Double precision conversion function 127* @code{DCMPLX}: DCMPLX, Double complex conversion function 128* @code{DIGITS}: DIGITS, Significant digits function 129* @code{DIM}: DIM, Positive difference 130* @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function 131* @code{DPROD}: DPROD, Double product function 132* @code{DREAL}: DREAL, Double real part function 133* @code{DSHIFTL}: DSHIFTL, Combined left shift 134* @code{DSHIFTR}: DSHIFTR, Combined right shift 135* @code{DTIME}: DTIME, Execution time subroutine (or function) 136* @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array 137* @code{EPSILON}: EPSILON, Epsilon function 138* @code{ERF}: ERF, Error function 139* @code{ERFC}: ERFC, Complementary error function 140* @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function 141* @code{ETIME}: ETIME, Execution time subroutine (or function) 142* @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred 143* @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command 144* @code{EXIT}: EXIT, Exit the program with status. 145* @code{EXP}: EXP, Exponential function 146* @code{EXPONENT}: EXPONENT, Exponent function 147* @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension 148* @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string 149* @code{FGET}: FGET, Read a single character in stream mode from stdin 150* @code{FGETC}: FGETC, Read a single character in stream mode 151* @code{FLOOR}: FLOOR, Integer floor function 152* @code{FLUSH}: FLUSH, Flush I/O unit(s) 153* @code{FNUM}: FNUM, File number function 154* @code{FPUT}: FPUT, Write a single character in stream mode to stdout 155* @code{FPUTC}: FPUTC, Write a single character in stream mode 156* @code{FRACTION}: FRACTION, Fractional part of the model representation 157* @code{FREE}: FREE, Memory de-allocation subroutine 158* @code{FSEEK}: FSEEK, Low level file positioning subroutine 159* @code{FSTAT}: FSTAT, Get file status 160* @code{FTELL}: FTELL, Current stream position 161* @code{GAMMA}: GAMMA, Gamma function 162* @code{GERROR}: GERROR, Get last system error message 163* @code{GETARG}: GETARG, Get command line arguments 164* @code{GET_COMMAND}: GET_COMMAND, Get the entire command line 165* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments 166* @code{GETCWD}: GETCWD, Get current working directory 167* @code{GETENV}: GETENV, Get an environmental variable 168* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable 169* @code{GETGID}: GETGID, Group ID function 170* @code{GETLOG}: GETLOG, Get login name 171* @code{GETPID}: GETPID, Process ID function 172* @code{GETUID}: GETUID, User ID function 173* @code{GMTIME}: GMTIME, Convert time to GMT info 174* @code{HOSTNM}: HOSTNM, Get system host name 175* @code{HUGE}: HUGE, Largest number of a kind 176* @code{HYPOT}: HYPOT, Euclidean distance function 177* @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence 178* @code{IALL}: IALL, Bitwise AND of array elements 179* @code{IAND}: IAND, Bitwise logical and 180* @code{IANY}: IANY, Bitwise OR of array elements 181* @code{IARGC}: IARGC, Get the number of command line arguments 182* @code{IBCLR}: IBCLR, Clear bit 183* @code{IBITS}: IBITS, Bit extraction 184* @code{IBSET}: IBSET, Set bit 185* @code{ICHAR}: ICHAR, Character-to-integer conversion function 186* @code{IDATE}: IDATE, Current local time (day/month/year) 187* @code{IEOR}: IEOR, Bitwise logical exclusive or 188* @code{IERRNO}: IERRNO, Function to get the last system error number 189* @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion 190* @code{INDEX}: INDEX intrinsic, Position of a substring within a string 191* @code{INT}: INT, Convert to integer type 192* @code{INT2}: INT2, Convert to 16-bit integer type 193* @code{INT8}: INT8, Convert to 64-bit integer type 194* @code{IOR}: IOR, Bitwise logical or 195* @code{IPARITY}: IPARITY, Bitwise XOR of array elements 196* @code{IRAND}: IRAND, Integer pseudo-random number 197* @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value 198* @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value 199* @code{ISATTY}: ISATTY, Whether a unit is a terminal device 200* @code{ISHFT}: ISHFT, Shift bits 201* @code{ISHFTC}: ISHFTC, Shift bits circularly 202* @code{ISNAN}: ISNAN, Tests for a NaN 203* @code{ITIME}: ITIME, Current local time (hour/minutes/seconds) 204* @code{KILL}: KILL, Send a signal to a process 205* @code{KIND}: KIND, Kind of an entity 206* @code{LBOUND}: LBOUND, Lower dimension bounds of an array 207* @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array 208* @code{LEADZ}: LEADZ, Number of leading zero bits of an integer 209* @code{LEN}: LEN, Length of a character entity 210* @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters 211* @code{LGE}: LGE, Lexical greater than or equal 212* @code{LGT}: LGT, Lexical greater than 213* @code{LINK}: LINK, Create a hard link 214* @code{LLE}: LLE, Lexical less than or equal 215* @code{LLT}: LLT, Lexical less than 216* @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string 217* @code{LOC}: LOC, Returns the address of a variable 218* @code{LOG}: LOG, Logarithm function 219* @code{LOG10}: LOG10, Base 10 logarithm function 220* @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function 221* @code{LOGICAL}: LOGICAL, Convert to logical type 222* @code{LONG}: LONG, Convert to integer type 223* @code{LSHIFT}: LSHIFT, Left shift bits 224* @code{LSTAT}: LSTAT, Get file status 225* @code{LTIME}: LTIME, Convert time to local time info 226* @code{MALLOC}: MALLOC, Dynamic memory allocation function 227* @code{MASKL}: MASKL, Left justified mask 228* @code{MASKR}: MASKR, Right justified mask 229* @code{MATMUL}: MATMUL, matrix multiplication 230* @code{MAX}: MAX, Maximum value of an argument list 231* @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind 232* @code{MAXLOC}: MAXLOC, Location of the maximum value within an array 233* @code{MAXVAL}: MAXVAL, Maximum value of an array 234* @code{MCLOCK}: MCLOCK, Time function 235* @code{MCLOCK8}: MCLOCK8, Time function (64-bit) 236* @code{MERGE}: MERGE, Merge arrays 237* @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask 238* @code{MIN}: MIN, Minimum value of an argument list 239* @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind 240* @code{MINLOC}: MINLOC, Location of the minimum value within an array 241* @code{MINVAL}: MINVAL, Minimum value of an array 242* @code{MOD}: MOD, Remainder function 243* @code{MODULO}: MODULO, Modulo function 244* @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another 245* @code{MVBITS}: MVBITS, Move bits from one integer to another 246* @code{NEAREST}: NEAREST, Nearest representable number 247* @code{NEW_LINE}: NEW_LINE, New line character 248* @code{NINT}: NINT, Nearest whole number 249* @code{NORM2}: NORM2, Euclidean vector norm 250* @code{NOT}: NOT, Logical negation 251* @code{NULL}: NULL, Function that returns an disassociated pointer 252* @code{NUM_IMAGES}: NUM_IMAGES, Number of images 253* @code{OR}: OR, Bitwise logical OR 254* @code{PACK}: PACK, Pack an array into an array of rank one 255* @code{PARITY}: PARITY, Reduction with exclusive OR 256* @code{PERROR}: PERROR, Print system error message 257* @code{POPCNT}: POPCNT, Number of bits set 258* @code{POPPAR}: POPPAR, Parity of the number of bits set 259* @code{PRECISION}: PRECISION, Decimal precision of a real kind 260* @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified 261* @code{PRODUCT}: PRODUCT, Product of array elements 262* @code{RADIX}: RADIX, Base of a data model 263* @code{RAN}: RAN, Real pseudo-random number 264* @code{RAND}: RAND, Real pseudo-random number 265* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number 266* @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence 267* @code{RANGE}: RANGE, Decimal exponent range 268* @code{RANK} : RANK, Rank of a data object 269* @code{REAL}: REAL, Convert to real type 270* @code{RENAME}: RENAME, Rename a file 271* @code{REPEAT}: REPEAT, Repeated string concatenation 272* @code{RESHAPE}: RESHAPE, Function to reshape an array 273* @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing 274* @code{RSHIFT}: RSHIFT, Right shift bits 275* @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality 276* @code{SCALE}: SCALE, Scale a real value 277* @code{SCAN}: SCAN, Scan a string for the presence of a set of characters 278* @code{SECNDS}: SECNDS, Time function 279* @code{SECOND}: SECOND, CPU time function 280* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind 281* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind 282* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind 283* @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model 284* @code{SHAPE}: SHAPE, Determine the shape of an array 285* @code{SHIFTA}: SHIFTA, Right shift with fill 286* @code{SHIFTL}: SHIFTL, Left shift 287* @code{SHIFTR}: SHIFTR, Right shift 288* @code{SIGN}: SIGN, Sign copying function 289* @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function) 290* @code{SIN}: SIN, Sine function 291* @code{SIND}: SIND, Sine function, degrees 292* @code{SINH}: SINH, Hyperbolic sine function 293* @code{SIZE}: SIZE, Function to determine the size of an array 294* @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression 295* @code{SLEEP}: SLEEP, Sleep for the specified number of seconds 296* @code{SPACING}: SPACING, Smallest distance between two numbers of a given type 297* @code{SPREAD}: SPREAD, Add a dimension to an array 298* @code{SQRT}: SQRT, Square-root function 299* @code{SRAND}: SRAND, Reinitialize the random number generator 300* @code{STAT}: STAT, Get file status 301* @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits 302* @code{SUM}: SUM, Sum of array elements 303* @code{SYMLNK}: SYMLNK, Create a symbolic link 304* @code{SYSTEM}: SYSTEM, Execute a shell command 305* @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function 306* @code{TAN}: TAN, Tangent function 307* @code{TAND}: TAND, Tangent function, degrees 308* @code{TANH}: TANH, Hyperbolic tangent function 309* @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image 310* @code{TIME}: TIME, Time function 311* @code{TIME8}: TIME8, Time function (64-bit) 312* @code{TINY}: TINY, Smallest positive number of a real kind 313* @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer 314* @code{TRANSFER}: TRANSFER, Transfer bit patterns 315* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two 316* @code{TRIM}: TRIM, Remove trailing blank characters of a string 317* @code{TTYNAM}: TTYNAM, Get the name of a terminal device. 318* @code{UBOUND}: UBOUND, Upper dimension bounds of an array 319* @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array 320* @code{UMASK}: UMASK, Set the file creation mask 321* @code{UNLINK}: UNLINK, Remove a file from the file system 322* @code{UNPACK}: UNPACK, Unpack an array of rank one into an array 323* @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters 324* @code{XOR}: XOR, Bitwise logical exclusive or 325@end menu 326 327@node Introduction to Intrinsics 328@section Introduction to intrinsic procedures 329 330The intrinsic procedures provided by GNU Fortran include all of the 331intrinsic procedures required by the Fortran 95 standard, a set of 332intrinsic procedures for backwards compatibility with G77, and a 333selection of intrinsic procedures from the Fortran 2003 and Fortran 2008 334standards. Any conflict between a description here and a description in 335either the Fortran 95 standard, the Fortran 2003 standard or the Fortran 3362008 standard is unintentional, and the standard(s) should be considered 337authoritative. 338 339The enumeration of the @code{KIND} type parameter is processor defined in 340the Fortran 95 standard. GNU Fortran defines the default integer type and 341default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)}, 342respectively. The standard mandates that both data types shall have 343another kind, which have more precision. On typical target architectures 344supported by @command{gfortran}, this kind type parameter is @code{KIND=8}. 345Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent. 346In the description of generic intrinsic procedures, the kind type parameter 347will be specified by @code{KIND=*}, and in the description of specific 348names for an intrinsic procedure the kind type parameter will be explicitly 349given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for 350brevity the optional @code{KIND=} syntax will be omitted. 351 352Many of the intrinsic procedures take one or more optional arguments. 353This document follows the convention used in the Fortran 95 standard, 354and denotes such arguments by square brackets. 355 356GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options, 357which can be used to restrict the set of intrinsic procedures to a 358given standard. By default, @command{gfortran} sets the @option{-std=gnu} 359option, and so all intrinsic procedures described here are accepted. There 360is one caveat. For a select group of intrinsic procedures, @command{g77} 361implemented both a function and a subroutine. Both classes 362have been implemented in @command{gfortran} for backwards compatibility 363with @command{g77}. It is noted here that these functions and subroutines 364cannot be intermixed in a given subprogram. In the descriptions that follow, 365the applicable standard for each intrinsic procedure is noted. 366 367 368 369@node ABORT 370@section @code{ABORT} --- Abort the program 371@fnindex ABORT 372@cindex program termination, with core dump 373@cindex terminate program, with core dump 374@cindex core, dump 375 376@table @asis 377@item @emph{Description}: 378@code{ABORT} causes immediate termination of the program. On operating 379systems that support a core dump, @code{ABORT} will produce a core dump. 380It will also print a backtrace, unless @code{-fno-backtrace} is given. 381 382@item @emph{Standard}: 383GNU extension 384 385@item @emph{Class}: 386Subroutine 387 388@item @emph{Syntax}: 389@code{CALL ABORT} 390 391@item @emph{Return value}: 392Does not return. 393 394@item @emph{Example}: 395@smallexample 396program test_abort 397 integer :: i = 1, j = 2 398 if (i /= j) call abort 399end program test_abort 400@end smallexample 401 402@item @emph{See also}: 403@ref{EXIT}, @ref{KILL}, @ref{BACKTRACE} 404 405@end table 406 407 408 409@node ABS 410@section @code{ABS} --- Absolute value 411@fnindex ABS 412@fnindex CABS 413@fnindex DABS 414@fnindex IABS 415@fnindex ZABS 416@fnindex CDABS 417@fnindex BABS 418@fnindex IIABS 419@fnindex JIABS 420@fnindex KIABS 421@cindex absolute value 422 423@table @asis 424@item @emph{Description}: 425@code{ABS(A)} computes the absolute value of @code{A}. 426 427@item @emph{Standard}: 428Fortran 77 and later, has overloads that are GNU extensions 429 430@item @emph{Class}: 431Elemental function 432 433@item @emph{Syntax}: 434@code{RESULT = ABS(A)} 435 436@item @emph{Arguments}: 437@multitable @columnfractions .15 .70 438@item @var{A} @tab The type of the argument shall be an @code{INTEGER}, 439@code{REAL}, or @code{COMPLEX}. 440@end multitable 441 442@item @emph{Return value}: 443The return value is of the same type and 444kind as the argument except the return value is @code{REAL} for a 445@code{COMPLEX} argument. 446 447@item @emph{Example}: 448@smallexample 449program test_abs 450 integer :: i = -1 451 real :: x = -1.e0 452 complex :: z = (-1.e0,0.e0) 453 i = abs(i) 454 x = abs(x) 455 x = abs(z) 456end program test_abs 457@end smallexample 458 459@item @emph{Specific names}: 460@multitable @columnfractions .20 .20 .20 .25 461@item Name @tab Argument @tab Return type @tab Standard 462@item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 463@item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 464@item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 465@item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later 466@item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 467@item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 468@item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 469@item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 470@item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension 471@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension 472@end multitable 473@end table 474 475 476 477@node ACCESS 478@section @code{ACCESS} --- Checks file access modes 479@fnindex ACCESS 480@cindex file system, access mode 481 482@table @asis 483@item @emph{Description}: 484@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 485exists, is readable, writable or executable. Except for the 486executable check, @code{ACCESS} can be replaced by 487Fortran 95's @code{INQUIRE}. 488 489@item @emph{Standard}: 490GNU extension 491 492@item @emph{Class}: 493Inquiry function 494 495@item @emph{Syntax}: 496@code{RESULT = ACCESS(NAME, MODE)} 497 498@item @emph{Arguments}: 499@multitable @columnfractions .15 .70 500@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 501file name. Tailing blank are ignored unless the character @code{achar(0)} 502is present, then all characters up to and excluding @code{achar(0)} are 503used as file name. 504@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the 505file access mode, may be any concatenation of @code{"r"} (readable), 506@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check 507for existence. 508@end multitable 509 510@item @emph{Return value}: 511Returns a scalar @code{INTEGER}, which is @code{0} if the file is 512accessible in the given mode; otherwise or if an invalid argument 513has been given for @code{MODE} the value @code{1} is returned. 514 515@item @emph{Example}: 516@smallexample 517program access_test 518 implicit none 519 character(len=*), parameter :: file = 'test.dat' 520 character(len=*), parameter :: file2 = 'test.dat '//achar(0) 521 if(access(file,' ') == 0) print *, trim(file),' is exists' 522 if(access(file,'r') == 0) print *, trim(file),' is readable' 523 if(access(file,'w') == 0) print *, trim(file),' is writable' 524 if(access(file,'x') == 0) print *, trim(file),' is executable' 525 if(access(file2,'rwx') == 0) & 526 print *, trim(file2),' is readable, writable and executable' 527end program access_test 528@end smallexample 529@item @emph{Specific names}: 530@item @emph{See also}: 531 532@end table 533 534 535 536@node ACHAR 537@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 538@fnindex ACHAR 539@cindex @acronym{ASCII} collating sequence 540@cindex collating sequence, @acronym{ASCII} 541 542@table @asis 543@item @emph{Description}: 544@code{ACHAR(I)} returns the character located at position @code{I} 545in the @acronym{ASCII} collating sequence. 546 547@item @emph{Standard}: 548Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 549 550@item @emph{Class}: 551Elemental function 552 553@item @emph{Syntax}: 554@code{RESULT = ACHAR(I [, KIND])} 555 556@item @emph{Arguments}: 557@multitable @columnfractions .15 .70 558@item @var{I} @tab The type shall be @code{INTEGER}. 559@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 560expression indicating the kind parameter of the result. 561@end multitable 562 563@item @emph{Return value}: 564The return value is of type @code{CHARACTER} with a length of one. 565If the @var{KIND} argument is present, the return value is of the 566specified kind and of the default kind otherwise. 567 568@item @emph{Example}: 569@smallexample 570program test_achar 571 character c 572 c = achar(32) 573end program test_achar 574@end smallexample 575 576@item @emph{Note}: 577See @ref{ICHAR} for a discussion of converting between numerical values 578and formatted string representations. 579 580@item @emph{See also}: 581@ref{CHAR}, @ref{IACHAR}, @ref{ICHAR} 582 583@end table 584 585 586 587@node ACOS 588@section @code{ACOS} --- Arccosine function 589@fnindex ACOS 590@fnindex DACOS 591@cindex trigonometric function, cosine, inverse 592@cindex cosine, inverse 593 594@table @asis 595@item @emph{Description}: 596@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}). 597 598@item @emph{Standard}: 599Fortran 77 and later, for a complex argument Fortran 2008 or later 600 601@item @emph{Class}: 602Elemental function 603 604@item @emph{Syntax}: 605@code{RESULT = ACOS(X)} 606 607@item @emph{Arguments}: 608@multitable @columnfractions .15 .70 609@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 610less than or equal to one - or the type shall be @code{COMPLEX}. 611@end multitable 612 613@item @emph{Return value}: 614The return value is of the same type and kind as @var{X}. 615The real part of the result is in radians and lies in the range 616@math{0 \leq \Re \acos(x) \leq \pi}. 617 618@item @emph{Example}: 619@smallexample 620program test_acos 621 real(8) :: x = 0.866_8 622 x = acos(x) 623end program test_acos 624@end smallexample 625 626@item @emph{Specific names}: 627@multitable @columnfractions .20 .20 .20 .25 628@item Name @tab Argument @tab Return type @tab Standard 629@item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 630@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 631@end multitable 632 633@item @emph{See also}: 634Inverse function: @ref{COS} 635Degrees function: @ref{ACOSD} 636 637@end table 638 639 640 641@node ACOSD 642@section @code{ACOSD} --- Arccosine function, degrees 643@fnindex ACOSD 644@fnindex DACOSD 645@cindex trigonometric function, cosine, inverse, degrees 646@cindex cosine, inverse, degrees 647 648@table @asis 649@item @emph{Description}: 650@code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of 651@code{COSD(X)}). 652 653This function is for compatibility only and should be avoided in favor of 654standard constructs wherever possible. 655 656@item @emph{Standard}: 657GNU Extension, enabled with @option{-fdec-math} 658 659@item @emph{Class}: 660Elemental function 661 662@item @emph{Syntax}: 663@code{RESULT = ACOSD(X)} 664 665@item @emph{Arguments}: 666@multitable @columnfractions .15 .70 667@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 668less than or equal to one - or the type shall be @code{COMPLEX}. 669@end multitable 670 671@item @emph{Return value}: 672The return value is of the same type and kind as @var{X}. 673The real part of the result is in degrees and lies in the range 674@math{0 \leq \Re \acos(x) \leq 180}. 675 676@item @emph{Example}: 677@smallexample 678program test_acosd 679 real(8) :: x = 0.866_8 680 x = acosd(x) 681end program test_acosd 682@end smallexample 683 684@item @emph{Specific names}: 685@multitable @columnfractions .20 .20 .20 .25 686@item Name @tab Argument @tab Return type @tab Standard 687@item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 688@item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 689@end multitable 690 691@item @emph{See also}: 692Inverse function: @ref{COSD} 693Radians function: @ref{ACOS} 694 695@end table 696 697 698 699@node ACOSH 700@section @code{ACOSH} --- Inverse hyperbolic cosine function 701@fnindex ACOSH 702@fnindex DACOSH 703@cindex area hyperbolic cosine 704@cindex inverse hyperbolic cosine 705@cindex hyperbolic function, cosine, inverse 706@cindex cosine, hyperbolic, inverse 707 708@table @asis 709@item @emph{Description}: 710@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}. 711 712@item @emph{Standard}: 713Fortran 2008 and later 714 715@item @emph{Class}: 716Elemental function 717 718@item @emph{Syntax}: 719@code{RESULT = ACOSH(X)} 720 721@item @emph{Arguments}: 722@multitable @columnfractions .15 .70 723@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 724@end multitable 725 726@item @emph{Return value}: 727The return value has the same type and kind as @var{X}. If @var{X} is 728complex, the imaginary part of the result is in radians and lies between 729@math{ 0 \leq \Im \acosh(x) \leq \pi}. 730 731@item @emph{Example}: 732@smallexample 733PROGRAM test_acosh 734 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) 735 WRITE (*,*) ACOSH(x) 736END PROGRAM 737@end smallexample 738 739@item @emph{Specific names}: 740@multitable @columnfractions .20 .20 .20 .25 741@item Name @tab Argument @tab Return type @tab Standard 742@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 743@end multitable 744 745@item @emph{See also}: 746Inverse function: @ref{COSH} 747@end table 748 749 750 751@node ADJUSTL 752@section @code{ADJUSTL} --- Left adjust a string 753@fnindex ADJUSTL 754@cindex string, adjust left 755@cindex adjust string 756 757@table @asis 758@item @emph{Description}: 759@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces. 760Spaces are inserted at the end of the string as needed. 761 762@item @emph{Standard}: 763Fortran 90 and later 764 765@item @emph{Class}: 766Elemental function 767 768@item @emph{Syntax}: 769@code{RESULT = ADJUSTL(STRING)} 770 771@item @emph{Arguments}: 772@multitable @columnfractions .15 .70 773@item @var{STRING} @tab The type shall be @code{CHARACTER}. 774@end multitable 775 776@item @emph{Return value}: 777The return value is of type @code{CHARACTER} and of the same kind as 778@var{STRING} where leading spaces are removed and the same number of 779spaces are inserted on the end of @var{STRING}. 780 781@item @emph{Example}: 782@smallexample 783program test_adjustl 784 character(len=20) :: str = ' gfortran' 785 str = adjustl(str) 786 print *, str 787end program test_adjustl 788@end smallexample 789 790@item @emph{See also}: 791@ref{ADJUSTR}, @ref{TRIM} 792@end table 793 794 795 796@node ADJUSTR 797@section @code{ADJUSTR} --- Right adjust a string 798@fnindex ADJUSTR 799@cindex string, adjust right 800@cindex adjust string 801 802@table @asis 803@item @emph{Description}: 804@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces. 805Spaces are inserted at the start of the string as needed. 806 807@item @emph{Standard}: 808Fortran 95 and later 809 810@item @emph{Class}: 811Elemental function 812 813@item @emph{Syntax}: 814@code{RESULT = ADJUSTR(STRING)} 815 816@item @emph{Arguments}: 817@multitable @columnfractions .15 .70 818@item @var{STR} @tab The type shall be @code{CHARACTER}. 819@end multitable 820 821@item @emph{Return value}: 822The return value is of type @code{CHARACTER} and of the same kind as 823@var{STRING} where trailing spaces are removed and the same number of 824spaces are inserted at the start of @var{STRING}. 825 826@item @emph{Example}: 827@smallexample 828program test_adjustr 829 character(len=20) :: str = 'gfortran' 830 str = adjustr(str) 831 print *, str 832end program test_adjustr 833@end smallexample 834 835@item @emph{See also}: 836@ref{ADJUSTL}, @ref{TRIM} 837@end table 838 839 840 841@node AIMAG 842@section @code{AIMAG} --- Imaginary part of complex number 843@fnindex AIMAG 844@fnindex DIMAG 845@fnindex IMAG 846@fnindex IMAGPART 847@cindex complex numbers, imaginary part 848 849@table @asis 850@item @emph{Description}: 851@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}. 852The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided 853for compatibility with @command{g77}, and their use in new code is 854strongly discouraged. 855 856@item @emph{Standard}: 857Fortran 77 and later, has overloads that are GNU extensions 858 859@item @emph{Class}: 860Elemental function 861 862@item @emph{Syntax}: 863@code{RESULT = AIMAG(Z)} 864 865@item @emph{Arguments}: 866@multitable @columnfractions .15 .70 867@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}. 868@end multitable 869 870@item @emph{Return value}: 871The return value is of type @code{REAL} with the 872kind type parameter of the argument. 873 874@item @emph{Example}: 875@smallexample 876program test_aimag 877 complex(4) z4 878 complex(8) z8 879 z4 = cmplx(1.e0_4, 0.e0_4) 880 z8 = cmplx(0.e0_8, 1.e0_8) 881 print *, aimag(z4), dimag(z8) 882end program test_aimag 883@end smallexample 884 885@item @emph{Specific names}: 886@multitable @columnfractions .20 .20 .20 .25 887@item Name @tab Argument @tab Return type @tab Standard 888@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 889@item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension 890@item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 891@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 892@end multitable 893@end table 894 895 896 897@node AINT 898@section @code{AINT} --- Truncate to a whole number 899@fnindex AINT 900@fnindex DINT 901@cindex floor 902@cindex rounding, floor 903 904@table @asis 905@item @emph{Description}: 906@code{AINT(A [, KIND])} truncates its argument to a whole number. 907 908@item @emph{Standard}: 909Fortran 77 and later 910 911@item @emph{Class}: 912Elemental function 913 914@item @emph{Syntax}: 915@code{RESULT = AINT(A [, KIND])} 916 917@item @emph{Arguments}: 918@multitable @columnfractions .15 .70 919@item @var{A} @tab The type of the argument shall be @code{REAL}. 920@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 921expression indicating the kind parameter of the result. 922@end multitable 923 924@item @emph{Return value}: 925The return value is of type @code{REAL} with the kind type parameter of the 926argument if the optional @var{KIND} is absent; otherwise, the kind 927type parameter will be given by @var{KIND}. If the magnitude of 928@var{X} is less than one, @code{AINT(X)} returns zero. If the 929magnitude is equal to or greater than one then it returns the largest 930whole number that does not exceed its magnitude. The sign is the same 931as the sign of @var{X}. 932 933@item @emph{Example}: 934@smallexample 935program test_aint 936 real(4) x4 937 real(8) x8 938 x4 = 1.234E0_4 939 x8 = 4.321_8 940 print *, aint(x4), dint(x8) 941 x8 = aint(x4,8) 942end program test_aint 943@end smallexample 944 945@item @emph{Specific names}: 946@multitable @columnfractions .20 .20 .20 .25 947@item Name @tab Argument @tab Return type @tab Standard 948@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 949@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 950@end multitable 951@end table 952 953 954 955@node ALARM 956@section @code{ALARM} --- Execute a routine after a given delay 957@fnindex ALARM 958@cindex delayed execution 959 960@table @asis 961@item @emph{Description}: 962@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} 963to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to 964set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is 965supplied, it will be returned with the number of seconds remaining until 966any previously scheduled alarm was due to be delivered, or zero if there 967was no previously scheduled alarm. 968 969@item @emph{Standard}: 970GNU extension 971 972@item @emph{Class}: 973Subroutine 974 975@item @emph{Syntax}: 976@code{CALL ALARM(SECONDS, HANDLER [, STATUS])} 977 978@item @emph{Arguments}: 979@multitable @columnfractions .15 .70 980@item @var{SECONDS} @tab The type of the argument shall be a scalar 981@code{INTEGER}. It is @code{INTENT(IN)}. 982@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or 983@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 984values may be either @code{SIG_IGN=1} to ignore the alarm generated 985or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}. 986@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 987variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}. 988@end multitable 989 990@item @emph{Example}: 991@smallexample 992program test_alarm 993 external handler_print 994 integer i 995 call alarm (3, handler_print, i) 996 print *, i 997 call sleep(10) 998end program test_alarm 999@end smallexample 1000This will cause the external routine @var{handler_print} to be called 1001after 3 seconds. 1002@end table 1003 1004 1005 1006@node ALL 1007@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 1008@fnindex ALL 1009@cindex array, apply condition 1010@cindex array, condition testing 1011 1012@table @asis 1013@item @emph{Description}: 1014@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK} 1015in the array along dimension @var{DIM}. 1016 1017@item @emph{Standard}: 1018Fortran 95 and later 1019 1020@item @emph{Class}: 1021Transformational function 1022 1023@item @emph{Syntax}: 1024@code{RESULT = ALL(MASK [, DIM])} 1025 1026@item @emph{Arguments}: 1027@multitable @columnfractions .15 .70 1028@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1029it shall not be scalar. 1030@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1031with a value that lies between one and the rank of @var{MASK}. 1032@end multitable 1033 1034@item @emph{Return value}: 1035@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where 1036the kind type parameter is the same as the kind type parameter of 1037@var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns 1038an array with the rank of @var{MASK} minus 1. The shape is determined from 1039the shape of @var{MASK} where the @var{DIM} dimension is elided. 1040 1041@table @asis 1042@item (A) 1043@code{ALL(MASK)} is true if all elements of @var{MASK} are true. 1044It also is true if @var{MASK} has zero size; otherwise, it is false. 1045@item (B) 1046If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent 1047to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)} 1048is determined by applying @code{ALL} to the array sections. 1049@end table 1050 1051@item @emph{Example}: 1052@smallexample 1053program test_all 1054 logical l 1055 l = all((/.true., .true., .true./)) 1056 print *, l 1057 call section 1058 contains 1059 subroutine section 1060 integer a(2,3), b(2,3) 1061 a = 1 1062 b = 1 1063 b(2,2) = 2 1064 print *, all(a .eq. b, 1) 1065 print *, all(a .eq. b, 2) 1066 end subroutine section 1067end program test_all 1068@end smallexample 1069@end table 1070 1071 1072 1073@node ALLOCATED 1074@section @code{ALLOCATED} --- Status of an allocatable entity 1075@fnindex ALLOCATED 1076@cindex allocation, status 1077 1078@table @asis 1079@item @emph{Description}: 1080@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation 1081status of @var{ARRAY} and @var{SCALAR}, respectively. 1082 1083@item @emph{Standard}: 1084Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable 1085scalar entities are available in Fortran 2003 and later. 1086 1087@item @emph{Class}: 1088Inquiry function 1089 1090@item @emph{Syntax}: 1091@multitable @columnfractions .80 1092@item @code{RESULT = ALLOCATED(ARRAY)} 1093@item @code{RESULT = ALLOCATED(SCALAR)} 1094@end multitable 1095 1096@item @emph{Arguments}: 1097@multitable @columnfractions .15 .70 1098@item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array. 1099@item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar. 1100@end multitable 1101 1102@item @emph{Return value}: 1103The return value is a scalar @code{LOGICAL} with the default logical 1104kind type parameter. If the argument is allocated, then the result is 1105@code{.TRUE.}; otherwise, it returns @code{.FALSE.} 1106 1107@item @emph{Example}: 1108@smallexample 1109program test_allocated 1110 integer :: i = 4 1111 real(4), allocatable :: x(:) 1112 if (.not. allocated(x)) allocate(x(i)) 1113end program test_allocated 1114@end smallexample 1115@end table 1116 1117 1118 1119@node AND 1120@section @code{AND} --- Bitwise logical AND 1121@fnindex AND 1122@cindex bitwise logical and 1123@cindex logical and, bitwise 1124 1125@table @asis 1126@item @emph{Description}: 1127Bitwise logical @code{AND}. 1128 1129This intrinsic routine is provided for backwards compatibility with 1130GNU Fortran 77. For integer arguments, programmers should consider 1131the use of the @ref{IAND} intrinsic defined by the Fortran standard. 1132 1133@item @emph{Standard}: 1134GNU extension 1135 1136@item @emph{Class}: 1137Function 1138 1139@item @emph{Syntax}: 1140@code{RESULT = AND(I, J)} 1141 1142@item @emph{Arguments}: 1143@multitable @columnfractions .15 .70 1144@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 1145type or a scalar @code{LOGICAL} type. 1146@item @var{J} @tab The type shall be the same as the type of @var{I}. 1147@end multitable 1148 1149@item @emph{Return value}: 1150The return type is either a scalar @code{INTEGER} or a scalar 1151@code{LOGICAL}. If the kind type parameters differ, then the 1152smaller kind type is implicitly converted to larger kind, and the 1153return has the larger kind. 1154 1155@item @emph{Example}: 1156@smallexample 1157PROGRAM test_and 1158 LOGICAL :: T = .TRUE., F = .FALSE. 1159 INTEGER :: a, b 1160 DATA a / Z'F' /, b / Z'3' / 1161 1162 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F) 1163 WRITE (*,*) AND(a, b) 1164END PROGRAM 1165@end smallexample 1166 1167@item @emph{See also}: 1168Fortran 95 elemental function: @ref{IAND} 1169@end table 1170 1171 1172 1173@node ANINT 1174@section @code{ANINT} --- Nearest whole number 1175@fnindex ANINT 1176@fnindex DNINT 1177@cindex ceiling 1178@cindex rounding, ceiling 1179 1180@table @asis 1181@item @emph{Description}: 1182@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number. 1183 1184@item @emph{Standard}: 1185Fortran 77 and later 1186 1187@item @emph{Class}: 1188Elemental function 1189 1190@item @emph{Syntax}: 1191@code{RESULT = ANINT(A [, KIND])} 1192 1193@item @emph{Arguments}: 1194@multitable @columnfractions .15 .70 1195@item @var{A} @tab The type of the argument shall be @code{REAL}. 1196@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 1197expression indicating the kind parameter of the result. 1198@end multitable 1199 1200@item @emph{Return value}: 1201The return value is of type real with the kind type parameter of the 1202argument if the optional @var{KIND} is absent; otherwise, the kind 1203type parameter will be given by @var{KIND}. If @var{A} is greater than 1204zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is 1205less than or equal to zero then it returns @code{AINT(X-0.5)}. 1206 1207@item @emph{Example}: 1208@smallexample 1209program test_anint 1210 real(4) x4 1211 real(8) x8 1212 x4 = 1.234E0_4 1213 x8 = 4.321_8 1214 print *, anint(x4), dnint(x8) 1215 x8 = anint(x4,8) 1216end program test_anint 1217@end smallexample 1218 1219@item @emph{Specific names}: 1220@multitable @columnfractions .20 .20 .20 .25 1221@item Name @tab Argument @tab Return type @tab Standard 1222@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 1223@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 1224@end multitable 1225@end table 1226 1227 1228 1229@node ANY 1230@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 1231@fnindex ANY 1232@cindex array, apply condition 1233@cindex array, condition testing 1234 1235@table @asis 1236@item @emph{Description}: 1237@code{ANY(MASK [, DIM])} determines if any of the values in the logical array 1238@var{MASK} along dimension @var{DIM} are @code{.TRUE.}. 1239 1240@item @emph{Standard}: 1241Fortran 95 and later 1242 1243@item @emph{Class}: 1244Transformational function 1245 1246@item @emph{Syntax}: 1247@code{RESULT = ANY(MASK [, DIM])} 1248 1249@item @emph{Arguments}: 1250@multitable @columnfractions .15 .70 1251@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1252it shall not be scalar. 1253@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1254with a value that lies between one and the rank of @var{MASK}. 1255@end multitable 1256 1257@item @emph{Return value}: 1258@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where 1259the kind type parameter is the same as the kind type parameter of 1260@var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns 1261an array with the rank of @var{MASK} minus 1. The shape is determined from 1262the shape of @var{MASK} where the @var{DIM} dimension is elided. 1263 1264@table @asis 1265@item (A) 1266@code{ANY(MASK)} is true if any element of @var{MASK} is true; 1267otherwise, it is false. It also is false if @var{MASK} has zero size. 1268@item (B) 1269If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent 1270to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)} 1271is determined by applying @code{ANY} to the array sections. 1272@end table 1273 1274@item @emph{Example}: 1275@smallexample 1276program test_any 1277 logical l 1278 l = any((/.true., .true., .true./)) 1279 print *, l 1280 call section 1281 contains 1282 subroutine section 1283 integer a(2,3), b(2,3) 1284 a = 1 1285 b = 1 1286 b(2,2) = 2 1287 print *, any(a .eq. b, 1) 1288 print *, any(a .eq. b, 2) 1289 end subroutine section 1290end program test_any 1291@end smallexample 1292@end table 1293 1294 1295 1296@node ASIN 1297@section @code{ASIN} --- Arcsine function 1298@fnindex ASIN 1299@fnindex DASIN 1300@cindex trigonometric function, sine, inverse 1301@cindex sine, inverse 1302 1303@table @asis 1304@item @emph{Description}: 1305@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}). 1306 1307@item @emph{Standard}: 1308Fortran 77 and later, for a complex argument Fortran 2008 or later 1309 1310@item @emph{Class}: 1311Elemental function 1312 1313@item @emph{Syntax}: 1314@code{RESULT = ASIN(X)} 1315 1316@item @emph{Arguments}: 1317@multitable @columnfractions .15 .70 1318@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1319less than or equal to one - or be @code{COMPLEX}. 1320@end multitable 1321 1322@item @emph{Return value}: 1323The return value is of the same type and kind as @var{X}. 1324The real part of the result is in radians and lies in the range 1325@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}. 1326 1327@item @emph{Example}: 1328@smallexample 1329program test_asin 1330 real(8) :: x = 0.866_8 1331 x = asin(x) 1332end program test_asin 1333@end smallexample 1334 1335@item @emph{Specific names}: 1336@multitable @columnfractions .20 .20 .20 .25 1337@item Name @tab Argument @tab Return type @tab Standard 1338@item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1339@item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1340@end multitable 1341 1342@item @emph{See also}: 1343Inverse function: @ref{SIN} 1344Degrees function: @ref{ASIND} 1345 1346@end table 1347 1348 1349 1350@node ASIND 1351@section @code{ASIND} --- Arcsine function, degrees 1352@fnindex ASIND 1353@fnindex DASIND 1354@cindex trigonometric function, sine, inverse, degrees 1355@cindex sine, inverse, degrees 1356 1357@table @asis 1358@item @emph{Description}: 1359@code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of 1360@code{SIND(X)}). 1361 1362This function is for compatibility only and should be avoided in favor of 1363standard constructs wherever possible. 1364 1365@item @emph{Standard}: 1366GNU Extension, enabled with @option{-fdec-math}. 1367 1368@item @emph{Class}: 1369Elemental function 1370 1371@item @emph{Syntax}: 1372@code{RESULT = ASIND(X)} 1373 1374@item @emph{Arguments}: 1375@multitable @columnfractions .15 .70 1376@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1377less than or equal to one - or be @code{COMPLEX}. 1378@end multitable 1379 1380@item @emph{Return value}: 1381The return value is of the same type and kind as @var{X}. 1382The real part of the result is in degrees and lies in the range 1383@math{-90 \leq \Re \asin(x) \leq 90}. 1384 1385@item @emph{Example}: 1386@smallexample 1387program test_asind 1388 real(8) :: x = 0.866_8 1389 x = asind(x) 1390end program test_asind 1391@end smallexample 1392 1393@item @emph{Specific names}: 1394@multitable @columnfractions .20 .20 .20 .25 1395@item Name @tab Argument @tab Return type @tab Standard 1396@item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 1397@item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 1398@end multitable 1399 1400@item @emph{See also}: 1401Inverse function: @ref{SIND} 1402Radians function: @ref{ASIN} 1403 1404@end table 1405 1406 1407 1408@node ASINH 1409@section @code{ASINH} --- Inverse hyperbolic sine function 1410@fnindex ASINH 1411@fnindex DASINH 1412@cindex area hyperbolic sine 1413@cindex inverse hyperbolic sine 1414@cindex hyperbolic function, sine, inverse 1415@cindex sine, hyperbolic, inverse 1416 1417@table @asis 1418@item @emph{Description}: 1419@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}. 1420 1421@item @emph{Standard}: 1422Fortran 2008 and later 1423 1424@item @emph{Class}: 1425Elemental function 1426 1427@item @emph{Syntax}: 1428@code{RESULT = ASINH(X)} 1429 1430@item @emph{Arguments}: 1431@multitable @columnfractions .15 .70 1432@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1433@end multitable 1434 1435@item @emph{Return value}: 1436The return value is of the same type and kind as @var{X}. If @var{X} is 1437complex, the imaginary part of the result is in radians and lies between 1438@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}. 1439 1440@item @emph{Example}: 1441@smallexample 1442PROGRAM test_asinh 1443 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1444 WRITE (*,*) ASINH(x) 1445END PROGRAM 1446@end smallexample 1447 1448@item @emph{Specific names}: 1449@multitable @columnfractions .20 .20 .20 .25 1450@item Name @tab Argument @tab Return type @tab Standard 1451@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension. 1452@end multitable 1453 1454@item @emph{See also}: 1455Inverse function: @ref{SINH} 1456@end table 1457 1458 1459 1460@node ASSOCIATED 1461@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 1462@fnindex ASSOCIATED 1463@cindex pointer, status 1464@cindex association status 1465 1466@table @asis 1467@item @emph{Description}: 1468@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer 1469@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}. 1470 1471@item @emph{Standard}: 1472Fortran 95 and later 1473 1474@item @emph{Class}: 1475Inquiry function 1476 1477@item @emph{Syntax}: 1478@code{RESULT = ASSOCIATED(POINTER [, TARGET])} 1479 1480@item @emph{Arguments}: 1481@multitable @columnfractions .15 .70 1482@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute 1483and it can be of any type. 1484@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or 1485a target. It must have the same type, kind type parameter, and 1486array rank as @var{POINTER}. 1487@end multitable 1488The association status of neither @var{POINTER} nor @var{TARGET} shall be 1489undefined. 1490 1491@item @emph{Return value}: 1492@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}. 1493There are several cases: 1494@table @asis 1495@item (A) When the optional @var{TARGET} is not present then 1496@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false. 1497@item (B) If @var{TARGET} is present and a scalar target, the result is true if 1498@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 1499disassociated, the result is false. 1500@item (C) If @var{TARGET} is present and an array target, the result is true if 1501@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays, 1502are arrays whose elements are not zero-sized storage sequences, and 1503@var{TARGET} and @var{POINTER} occupy the same storage units in array element 1504order. 1505As in case(B), the result is false, if @var{POINTER} is disassociated. 1506@item (D) If @var{TARGET} is present and an scalar pointer, the result is true 1507if @var{TARGET} is associated with @var{POINTER}, the target associated with 1508@var{TARGET} are not zero-sized storage sequences and occupy the same storage 1509units. 1510The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1511@item (E) If @var{TARGET} is present and an array pointer, the result is true if 1512target associated with @var{POINTER} and the target associated with @var{TARGET} 1513have the same shape, are not zero-sized arrays, are arrays whose elements are 1514not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy 1515the same storage units in array element order. 1516The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1517@end table 1518 1519@item @emph{Example}: 1520@smallexample 1521program test_associated 1522 implicit none 1523 real, target :: tgt(2) = (/1., 2./) 1524 real, pointer :: ptr(:) 1525 ptr => tgt 1526 if (associated(ptr) .eqv. .false.) call abort 1527 if (associated(ptr,tgt) .eqv. .false.) call abort 1528end program test_associated 1529@end smallexample 1530 1531@item @emph{See also}: 1532@ref{NULL} 1533@end table 1534 1535 1536 1537@node ATAN 1538@section @code{ATAN} --- Arctangent function 1539@fnindex ATAN 1540@fnindex DATAN 1541@cindex trigonometric function, tangent, inverse 1542@cindex tangent, inverse 1543 1544@table @asis 1545@item @emph{Description}: 1546@code{ATAN(X)} computes the arctangent of @var{X}. 1547 1548@item @emph{Standard}: 1549Fortran 77 and later, for a complex argument and for two arguments 1550Fortran 2008 or later 1551 1552@item @emph{Class}: 1553Elemental function 1554 1555@item @emph{Syntax}: 1556@multitable @columnfractions .80 1557@item @code{RESULT = ATAN(X)} 1558@item @code{RESULT = ATAN(Y, X)} 1559@end multitable 1560 1561@item @emph{Arguments}: 1562@multitable @columnfractions .15 .70 1563@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1564if @var{Y} is present, @var{X} shall be REAL. 1565@item @var{Y} shall be of the same type and kind as @var{X}. 1566@end multitable 1567 1568@item @emph{Return value}: 1569The return value is of the same type and kind as @var{X}. 1570If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}. 1571Otherwise, it the arcus tangent of @var{X}, where the real part of 1572the result is in radians and lies in the range 1573@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}. 1574 1575@item @emph{Example}: 1576@smallexample 1577program test_atan 1578 real(8) :: x = 2.866_8 1579 x = atan(x) 1580end program test_atan 1581@end smallexample 1582 1583@item @emph{Specific names}: 1584@multitable @columnfractions .20 .20 .20 .25 1585@item Name @tab Argument @tab Return type @tab Standard 1586@item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1587@item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1588@end multitable 1589 1590@item @emph{See also}: 1591Inverse function: @ref{TAN} 1592Degrees function: @ref{ATAND} 1593 1594@end table 1595 1596 1597 1598@node ATAND 1599@section @code{ATAND} --- Arctangent function, degrees 1600@fnindex ATAND 1601@fnindex DATAND 1602@cindex trigonometric function, tangent, inverse, degrees 1603@cindex tangent, inverse, degrees 1604 1605@table @asis 1606@item @emph{Description}: 1607@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of 1608@ref{TAND}). 1609 1610This function is for compatibility only and should be avoided in favor of 1611standard constructs wherever possible. 1612 1613@item @emph{Standard}: 1614GNU Extension, enabled with @option{-fdec-math}. 1615 1616@item @emph{Class}: 1617Elemental function 1618 1619@item @emph{Syntax}: 1620@multitable @columnfractions .80 1621@item @code{RESULT = ATAND(X)} 1622@item @code{RESULT = ATAND(Y, X)} 1623@end multitable 1624 1625@item @emph{Arguments}: 1626@multitable @columnfractions .15 .70 1627@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1628if @var{Y} is present, @var{X} shall be REAL. 1629@item @var{Y} shall be of the same type and kind as @var{X}. 1630@end multitable 1631 1632@item @emph{Return value}: 1633The return value is of the same type and kind as @var{X}. 1634If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}. 1635Otherwise, it is the arcus tangent of @var{X}, where the real part of 1636the result is in degrees and lies in the range 1637@math{-90 \leq \Re \atand(x) \leq 90}. 1638 1639@item @emph{Example}: 1640@smallexample 1641program test_atand 1642 real(8) :: x = 2.866_8 1643 x = atand(x) 1644end program test_atand 1645@end smallexample 1646 1647@item @emph{Specific names}: 1648@multitable @columnfractions .20 .20 .20 .25 1649@item Name @tab Argument @tab Return type @tab Standard 1650@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 1651@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 1652@end multitable 1653 1654@item @emph{See also}: 1655Inverse function: @ref{TAND} 1656Radians function: @ref{ATAN} 1657 1658@end table 1659 1660 1661 1662@node ATAN2 1663@section @code{ATAN2} --- Arctangent function 1664@fnindex ATAN2 1665@fnindex DATAN2 1666@cindex trigonometric function, tangent, inverse 1667@cindex tangent, inverse 1668 1669@table @asis 1670@item @emph{Description}: 1671@code{ATAN2(Y, X)} computes the principal value of the argument 1672function of the complex number @math{X + i Y}. This function can 1673be used to transform from Cartesian into polar coordinates and 1674allows to determine the angle in the correct quadrant. 1675 1676@item @emph{Standard}: 1677Fortran 77 and later 1678 1679@item @emph{Class}: 1680Elemental function 1681 1682@item @emph{Syntax}: 1683@code{RESULT = ATAN2(Y, X)} 1684 1685@item @emph{Arguments}: 1686@multitable @columnfractions .15 .70 1687@item @var{Y} @tab The type shall be @code{REAL}. 1688@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1689If @var{Y} is zero, then @var{X} must be nonzero. 1690@end multitable 1691 1692@item @emph{Return value}: 1693The return value has the same type and kind type parameter as @var{Y}. It 1694is the principal value of the complex number @math{X + i Y}. If @var{X} 1695is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}. 1696The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1697the return value is zero if @var{X} is strictly positive, @math{\pi} if 1698@var{X} is negative and @var{Y} is positive zero (or the processor does 1699not handle signed zeros), and @math{-\pi} if @var{X} is negative and 1700@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1701magnitude of the result is @math{\pi/2}. 1702 1703@item @emph{Example}: 1704@smallexample 1705program test_atan2 1706 real(4) :: x = 1.e0_4, y = 0.5e0_4 1707 x = atan2(y,x) 1708end program test_atan2 1709@end smallexample 1710 1711@item @emph{Specific names}: 1712@multitable @columnfractions .20 .20 .20 .25 1713@item Name @tab Argument @tab Return type @tab Standard 1714@item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 1715@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 1716@end multitable 1717 1718@item @emph{See also}: 1719Alias: @ref{ATAN} 1720Degrees function: @ref{ATAN2D} 1721 1722@end table 1723 1724 1725 1726@node ATAN2D 1727@section @code{ATAN2D} --- Arctangent function, degrees 1728@fnindex ATAN2D 1729@fnindex DATAN2D 1730@cindex trigonometric function, tangent, inverse, degrees 1731@cindex tangent, inverse, degrees 1732 1733@table @asis 1734@item @emph{Description}: 1735@code{ATAN2D(Y, X)} computes the principal value of the argument 1736function of the complex number @math{X + i Y} in degrees. This function can 1737be used to transform from Cartesian into polar coordinates and 1738allows to determine the angle in the correct quadrant. 1739 1740This function is for compatibility only and should be avoided in favor of 1741standard constructs wherever possible. 1742 1743@item @emph{Standard}: 1744GNU Extension, enabled with @option{-fdec-math}. 1745 1746@item @emph{Class}: 1747Elemental function 1748 1749@item @emph{Syntax}: 1750@code{RESULT = ATAN2D(Y, X)} 1751 1752@item @emph{Arguments}: 1753@multitable @columnfractions .15 .70 1754@item @var{Y} @tab The type shall be @code{REAL}. 1755@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1756If @var{Y} is zero, then @var{X} must be nonzero. 1757@end multitable 1758 1759@item @emph{Return value}: 1760The return value has the same type and kind type parameter as @var{Y}. It 1761is the principal value of the complex number @math{X + i Y}. If @var{X} 1762is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}. 1763The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1764the return value is zero if @var{X} is strictly positive, @math{180} if 1765@var{X} is negative and @var{Y} is positive zero (or the processor does 1766not handle signed zeros), and @math{-180} if @var{X} is negative and 1767@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1768magnitude of the result is @math{90}. 1769 1770@item @emph{Example}: 1771@smallexample 1772program test_atan2d 1773 real(4) :: x = 1.e0_4, y = 0.5e0_4 1774 x = atan2d(y,x) 1775end program test_atan2d 1776@end smallexample 1777 1778@item @emph{Specific names}: 1779@multitable @columnfractions .20 .20 .20 .25 1780@item Name @tab Argument @tab Return type @tab Standard 1781@item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension 1782@item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension 1783@end multitable 1784 1785@item @emph{See also}: 1786Alias: @ref{ATAND} 1787Radians function: @ref{ATAN2} 1788 1789@end table 1790 1791 1792 1793@node ATANH 1794@section @code{ATANH} --- Inverse hyperbolic tangent function 1795@fnindex ATANH 1796@fnindex DATANH 1797@cindex area hyperbolic tangent 1798@cindex inverse hyperbolic tangent 1799@cindex hyperbolic function, tangent, inverse 1800@cindex tangent, hyperbolic, inverse 1801 1802@table @asis 1803@item @emph{Description}: 1804@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}. 1805 1806@item @emph{Standard}: 1807Fortran 2008 and later 1808 1809@item @emph{Class}: 1810Elemental function 1811 1812@item @emph{Syntax}: 1813@code{RESULT = ATANH(X)} 1814 1815@item @emph{Arguments}: 1816@multitable @columnfractions .15 .70 1817@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1818@end multitable 1819 1820@item @emph{Return value}: 1821The return value has same type and kind as @var{X}. If @var{X} is 1822complex, the imaginary part of the result is in radians and lies between 1823@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}. 1824 1825@item @emph{Example}: 1826@smallexample 1827PROGRAM test_atanh 1828 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1829 WRITE (*,*) ATANH(x) 1830END PROGRAM 1831@end smallexample 1832 1833@item @emph{Specific names}: 1834@multitable @columnfractions .20 .20 .20 .25 1835@item Name @tab Argument @tab Return type @tab Standard 1836@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1837@end multitable 1838 1839@item @emph{See also}: 1840Inverse function: @ref{TANH} 1841@end table 1842 1843 1844 1845@node ATOMIC_ADD 1846@section @code{ATOMIC_ADD} --- Atomic ADD operation 1847@fnindex ATOMIC_ADD 1848@cindex Atomic subroutine, add 1849 1850@table @asis 1851@item @emph{Description}: 1852@code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the 1853variable @var{ATOM}. When @var{STAT} is present and the invocation was 1854successful, it is assigned the value 0. If it is present and the invocation 1855has failed, it is assigned a positive value; in particular, for a coindexed 1856@var{ATOM}, if the remote image has stopped, it is assigned the value of 1857@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1858failed, the value @code{STAT_FAILED_IMAGE}. 1859 1860@item @emph{Standard}: 1861TS 18508 or later 1862 1863@item @emph{Class}: 1864Atomic subroutine 1865 1866@item @emph{Syntax}: 1867@code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])} 1868 1869@item @emph{Arguments}: 1870@multitable @columnfractions .15 .70 1871@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1872type with @code{ATOMIC_INT_KIND} kind. 1873@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1874is different, the value is converted to the kind of @var{ATOM}. 1875@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1876@end multitable 1877 1878@item @emph{Example}: 1879@smallexample 1880program atomic 1881 use iso_fortran_env 1882 integer(atomic_int_kind) :: atom[*] 1883 call atomic_add (atom[1], this_image()) 1884end program atomic 1885@end smallexample 1886 1887@item @emph{See also}: 1888@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV}, 1889@ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 1890@end table 1891 1892 1893 1894 1895@node ATOMIC_AND 1896@section @code{ATOMIC_AND} --- Atomic bitwise AND operation 1897@fnindex ATOMIC_AND 1898@cindex Atomic subroutine, AND 1899 1900@table @asis 1901@item @emph{Description}: 1902@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 1903AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 1904and the invocation was successful, it is assigned the value 0. If it is present 1905and the invocation has failed, it is assigned a positive value; in particular, 1906for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 1907value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 1908image has failed, the value @code{STAT_FAILED_IMAGE}. 1909 1910@item @emph{Standard}: 1911TS 18508 or later 1912 1913@item @emph{Class}: 1914Atomic subroutine 1915 1916@item @emph{Syntax}: 1917@code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])} 1918 1919@item @emph{Arguments}: 1920@multitable @columnfractions .15 .70 1921@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1922type with @code{ATOMIC_INT_KIND} kind. 1923@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1924is different, the value is converted to the kind of @var{ATOM}. 1925@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1926@end multitable 1927 1928@item @emph{Example}: 1929@smallexample 1930program atomic 1931 use iso_fortran_env 1932 integer(atomic_int_kind) :: atom[*] 1933 call atomic_and (atom[1], int(b'10100011101')) 1934end program atomic 1935@end smallexample 1936 1937@item @emph{See also}: 1938@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV}, 1939@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 1940@end table 1941 1942 1943 1944@node ATOMIC_CAS 1945@section @code{ATOMIC_CAS} --- Atomic compare and swap 1946@fnindex ATOMIC_DEFINE 1947@cindex Atomic subroutine, compare and swap 1948 1949@table @asis 1950@item @emph{Description}: 1951@code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of 1952@var{COMPARE}; if the value is the same, @var{ATOM} is set to the value 1953of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM} 1954that was used for the comparison. When @var{STAT} is present and the invocation 1955was successful, it is assigned the value 0. If it is present and the invocation 1956has failed, it is assigned a positive value; in particular, for a coindexed 1957@var{ATOM}, if the remote image has stopped, it is assigned the value of 1958@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1959failed, the value @code{STAT_FAILED_IMAGE}. 1960 1961@item @emph{Standard}: 1962TS 18508 or later 1963 1964@item @emph{Class}: 1965Atomic subroutine 1966 1967@item @emph{Syntax}: 1968@code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])} 1969 1970@item @emph{Arguments}: 1971@multitable @columnfractions .15 .70 1972@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 1973type with @code{ATOMIC_INT_KIND} kind or logical type with 1974@code{ATOMIC_LOGICAL_KIND} kind. 1975@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 1976@item @var{COMPARE} @tab Scalar variable of the same type and kind as 1977@var{ATOM}. 1978@item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind 1979is different, the value is converted to the kind of @var{ATOM}. 1980@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1981@end multitable 1982 1983@item @emph{Example}: 1984@smallexample 1985program atomic 1986 use iso_fortran_env 1987 logical(atomic_logical_kind) :: atom[*], prev 1988 call atomic_cas (atom[1], prev, .false., .true.)) 1989end program atomic 1990@end smallexample 1991 1992@item @emph{See also}: 1993@ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV} 1994@end table 1995 1996 1997 1998@node ATOMIC_DEFINE 1999@section @code{ATOMIC_DEFINE} --- Setting a variable atomically 2000@fnindex ATOMIC_DEFINE 2001@cindex Atomic subroutine, define 2002 2003@table @asis 2004@item @emph{Description}: 2005@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value 2006@var{VALUE} atomically. When @var{STAT} is present and the invocation was 2007successful, it is assigned the value 0. If it is present and the invocation 2008has failed, it is assigned a positive value; in particular, for a coindexed 2009@var{ATOM}, if the remote image has stopped, it is assigned the value of 2010@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2011failed, the value @code{STAT_FAILED_IMAGE}. 2012 2013@item @emph{Standard}: 2014Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2015 2016@item @emph{Class}: 2017Atomic subroutine 2018 2019@item @emph{Syntax}: 2020@code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])} 2021 2022@item @emph{Arguments}: 2023@multitable @columnfractions .15 .70 2024@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2025type with @code{ATOMIC_INT_KIND} kind or logical type with 2026@code{ATOMIC_LOGICAL_KIND} kind. 2027 2028@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2029is different, the value is converted to the kind of @var{ATOM}. 2030@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2031@end multitable 2032 2033@item @emph{Example}: 2034@smallexample 2035program atomic 2036 use iso_fortran_env 2037 integer(atomic_int_kind) :: atom[*] 2038 call atomic_define (atom[1], this_image()) 2039end program atomic 2040@end smallexample 2041 2042@item @emph{See also}: 2043@ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV}, 2044@ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 2045@end table 2046 2047 2048 2049@node ATOMIC_FETCH_ADD 2050@section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch 2051@fnindex ATOMIC_FETCH_ADD 2052@cindex Atomic subroutine, ADD with fetch 2053 2054@table @asis 2055@item @emph{Description}: 2056@code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of 2057@var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the 2058variable @var{ATOM}. When @var{STAT} is present and the invocation was 2059successful, it is assigned the value 0. If it is present and the invocation 2060has failed, it is assigned a positive value; in particular, for a coindexed 2061@var{ATOM}, if the remote image has stopped, it is assigned the value of 2062@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2063failed, the value @code{STAT_FAILED_IMAGE}. 2064 2065@item @emph{Standard}: 2066TS 18508 or later 2067 2068@item @emph{Class}: 2069Atomic subroutine 2070 2071@item @emph{Syntax}: 2072@code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])} 2073 2074@item @emph{Arguments}: 2075@multitable @columnfractions .15 .70 2076@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2077type with @code{ATOMIC_INT_KIND} kind. 2078@code{ATOMIC_LOGICAL_KIND} kind. 2079 2080@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2081is different, the value is converted to the kind of @var{ATOM}. 2082@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2083@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2084@end multitable 2085 2086@item @emph{Example}: 2087@smallexample 2088program atomic 2089 use iso_fortran_env 2090 integer(atomic_int_kind) :: atom[*], old 2091 call atomic_add (atom[1], this_image(), old) 2092end program atomic 2093@end smallexample 2094 2095@item @emph{See also}: 2096@ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV}, 2097@ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} 2098@end table 2099 2100 2101 2102@node ATOMIC_FETCH_AND 2103@section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch 2104@fnindex ATOMIC_FETCH_AND 2105@cindex Atomic subroutine, AND with fetch 2106 2107@table @asis 2108@item @emph{Description}: 2109@code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2110@var{OLD} and defines @var{ATOM} with the bitwise AND between the values of 2111@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2112successful, it is assigned the value 0. If it is present and the invocation has 2113failed, it is assigned a positive value; in particular, for a coindexed 2114@var{ATOM}, if the remote image has stopped, it is assigned the value of 2115@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2116failed, the value @code{STAT_FAILED_IMAGE}. 2117 2118@item @emph{Standard}: 2119TS 18508 or later 2120 2121@item @emph{Class}: 2122Atomic subroutine 2123 2124@item @emph{Syntax}: 2125@code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])} 2126 2127@item @emph{Arguments}: 2128@multitable @columnfractions .15 .70 2129@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2130type with @code{ATOMIC_INT_KIND} kind. 2131@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2132is different, the value is converted to the kind of @var{ATOM}. 2133@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2134@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2135@end multitable 2136 2137@item @emph{Example}: 2138@smallexample 2139program atomic 2140 use iso_fortran_env 2141 integer(atomic_int_kind) :: atom[*], old 2142 call atomic_fetch_and (atom[1], int(b'10100011101'), old) 2143end program atomic 2144@end smallexample 2145 2146@item @emph{See also}: 2147@ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV}, 2148@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} 2149@end table 2150 2151 2152 2153@node ATOMIC_FETCH_OR 2154@section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch 2155@fnindex ATOMIC_FETCH_OR 2156@cindex Atomic subroutine, OR with fetch 2157 2158@table @asis 2159@item @emph{Description}: 2160@code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2161@var{OLD} and defines @var{ATOM} with the bitwise OR between the values of 2162@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2163successful, it is assigned the value 0. If it is present and the invocation has 2164failed, it is assigned a positive value; in particular, for a coindexed 2165@var{ATOM}, if the remote image has stopped, it is assigned the value of 2166@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2167failed, the value @code{STAT_FAILED_IMAGE}. 2168 2169@item @emph{Standard}: 2170TS 18508 or later 2171 2172@item @emph{Class}: 2173Atomic subroutine 2174 2175@item @emph{Syntax}: 2176@code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])} 2177 2178@item @emph{Arguments}: 2179@multitable @columnfractions .15 .70 2180@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2181type with @code{ATOMIC_INT_KIND} kind. 2182@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2183is different, the value is converted to the kind of @var{ATOM}. 2184@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2185@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2186@end multitable 2187 2188@item @emph{Example}: 2189@smallexample 2190program atomic 2191 use iso_fortran_env 2192 integer(atomic_int_kind) :: atom[*], old 2193 call atomic_fetch_or (atom[1], int(b'10100011101'), old) 2194end program atomic 2195@end smallexample 2196 2197@item @emph{See also}: 2198@ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV}, 2199@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR} 2200@end table 2201 2202 2203 2204@node ATOMIC_FETCH_XOR 2205@section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch 2206@fnindex ATOMIC_FETCH_XOR 2207@cindex Atomic subroutine, XOR with fetch 2208 2209@table @asis 2210@item @emph{Description}: 2211@code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2212@var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of 2213@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2214successful, it is assigned the value 0. If it is present and the invocation has 2215failed, it is assigned a positive value; in particular, for a coindexed 2216@var{ATOM}, if the remote image has stopped, it is assigned the value of 2217@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2218failed, the value @code{STAT_FAILED_IMAGE}. 2219 2220@item @emph{Standard}: 2221TS 18508 or later 2222 2223@item @emph{Class}: 2224Atomic subroutine 2225 2226@item @emph{Syntax}: 2227@code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])} 2228 2229@item @emph{Arguments}: 2230@multitable @columnfractions .15 .70 2231@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2232type with @code{ATOMIC_INT_KIND} kind. 2233@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2234is different, the value is converted to the kind of @var{ATOM}. 2235@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2236@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2237@end multitable 2238 2239@item @emph{Example}: 2240@smallexample 2241program atomic 2242 use iso_fortran_env 2243 integer(atomic_int_kind) :: atom[*], old 2244 call atomic_fetch_xor (atom[1], int(b'10100011101'), old) 2245end program atomic 2246@end smallexample 2247 2248@item @emph{See also}: 2249@ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV}, 2250@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR} 2251@end table 2252 2253 2254 2255@node ATOMIC_OR 2256@section @code{ATOMIC_OR} --- Atomic bitwise OR operation 2257@fnindex ATOMIC_OR 2258@cindex Atomic subroutine, OR 2259 2260@table @asis 2261@item @emph{Description}: 2262@code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2263AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2264and the invocation was successful, it is assigned the value 0. If it is present 2265and the invocation has failed, it is assigned a positive value; in particular, 2266for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2267value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2268image has failed, the value @code{STAT_FAILED_IMAGE}. 2269 2270@item @emph{Standard}: 2271TS 18508 or later 2272 2273@item @emph{Class}: 2274Atomic subroutine 2275 2276@item @emph{Syntax}: 2277@code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])} 2278 2279@item @emph{Arguments}: 2280@multitable @columnfractions .15 .70 2281@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2282type with @code{ATOMIC_INT_KIND} kind. 2283@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2284is different, the value is converted to the kind of @var{ATOM}. 2285@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2286@end multitable 2287 2288@item @emph{Example}: 2289@smallexample 2290program atomic 2291 use iso_fortran_env 2292 integer(atomic_int_kind) :: atom[*] 2293 call atomic_or (atom[1], int(b'10100011101')) 2294end program atomic 2295@end smallexample 2296 2297@item @emph{See also}: 2298@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV}, 2299@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 2300@end table 2301 2302 2303 2304@node ATOMIC_REF 2305@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically 2306@fnindex ATOMIC_REF 2307@cindex Atomic subroutine, reference 2308 2309@table @asis 2310@item @emph{Description}: 2311@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the 2312variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the 2313invocation was successful, it is assigned the value 0. If it is present and the 2314invocation has failed, it is assigned a positive value; in particular, for a 2315coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value 2316of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image 2317has failed, the value @code{STAT_FAILED_IMAGE}. 2318 2319 2320@item @emph{Standard}: 2321Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2322 2323@item @emph{Class}: 2324Atomic subroutine 2325 2326@item @emph{Syntax}: 2327@code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])} 2328 2329@item @emph{Arguments}: 2330@multitable @columnfractions .15 .70 2331@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2332is different, the value is converted to the kind of @var{ATOM}. 2333@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2334type with @code{ATOMIC_INT_KIND} kind or logical type with 2335@code{ATOMIC_LOGICAL_KIND} kind. 2336@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2337@end multitable 2338 2339@item @emph{Example}: 2340@smallexample 2341program atomic 2342 use iso_fortran_env 2343 logical(atomic_logical_kind) :: atom[*] 2344 logical :: val 2345 call atomic_ref (atom, .false.) 2346 ! ... 2347 call atomic_ref (atom, val) 2348 if (val) then 2349 print *, "Obtained" 2350 end if 2351end program atomic 2352@end smallexample 2353 2354@item @emph{See also}: 2355@ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV}, 2356@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, 2357@ref{ATOMIC_FETCH_XOR} 2358@end table 2359 2360 2361@node ATOMIC_XOR 2362@section @code{ATOMIC_XOR} --- Atomic bitwise OR operation 2363@fnindex ATOMIC_XOR 2364@cindex Atomic subroutine, XOR 2365 2366@table @asis 2367@item @emph{Description}: 2368@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2369XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2370and the invocation was successful, it is assigned the value 0. If it is present 2371and the invocation has failed, it is assigned a positive value; in particular, 2372for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2373value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2374image has failed, the value @code{STAT_FAILED_IMAGE}. 2375 2376@item @emph{Standard}: 2377TS 18508 or later 2378 2379@item @emph{Class}: 2380Atomic subroutine 2381 2382@item @emph{Syntax}: 2383@code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])} 2384 2385@item @emph{Arguments}: 2386@multitable @columnfractions .15 .70 2387@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2388type with @code{ATOMIC_INT_KIND} kind. 2389@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2390is different, the value is converted to the kind of @var{ATOM}. 2391@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2392@end multitable 2393 2394@item @emph{Example}: 2395@smallexample 2396program atomic 2397 use iso_fortran_env 2398 integer(atomic_int_kind) :: atom[*] 2399 call atomic_xor (atom[1], int(b'10100011101')) 2400end program atomic 2401@end smallexample 2402 2403@item @emph{See also}: 2404@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV}, 2405@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 2406@end table 2407 2408 2409@node BACKTRACE 2410@section @code{BACKTRACE} --- Show a backtrace 2411@fnindex BACKTRACE 2412@cindex backtrace 2413 2414@table @asis 2415@item @emph{Description}: 2416@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program 2417execution continues normally afterwards. The backtrace information is printed 2418to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}. 2419 2420@item @emph{Standard}: 2421GNU Extension 2422 2423@item @emph{Class}: 2424Subroutine 2425 2426@item @emph{Syntax}: 2427@code{CALL BACKTRACE} 2428 2429@item @emph{Arguments}: 2430None 2431 2432@item @emph{See also}: 2433@ref{ABORT} 2434@end table 2435 2436 2437 2438@node BESSEL_J0 2439@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0 2440@fnindex BESSEL_J0 2441@fnindex BESJ0 2442@fnindex DBESJ0 2443@cindex Bessel function, first kind 2444 2445@table @asis 2446@item @emph{Description}: 2447@code{BESSEL_J0(X)} computes the Bessel function of the first kind of 2448order 0 of @var{X}. This function is available under the name 2449@code{BESJ0} as a GNU extension. 2450 2451@item @emph{Standard}: 2452Fortran 2008 and later 2453 2454@item @emph{Class}: 2455Elemental function 2456 2457@item @emph{Syntax}: 2458@code{RESULT = BESSEL_J0(X)} 2459 2460@item @emph{Arguments}: 2461@multitable @columnfractions .15 .70 2462@item @var{X} @tab The type shall be @code{REAL}. 2463@end multitable 2464 2465@item @emph{Return value}: 2466The return value is of type @code{REAL} and lies in the 2467range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same 2468kind as @var{X}. 2469 2470@item @emph{Example}: 2471@smallexample 2472program test_besj0 2473 real(8) :: x = 0.0_8 2474 x = bessel_j0(x) 2475end program test_besj0 2476@end smallexample 2477 2478@item @emph{Specific names}: 2479@multitable @columnfractions .20 .20 .20 .25 2480@item Name @tab Argument @tab Return type @tab Standard 2481@item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2482@end multitable 2483@end table 2484 2485 2486 2487@node BESSEL_J1 2488@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1 2489@fnindex BESSEL_J1 2490@fnindex BESJ1 2491@fnindex DBESJ1 2492@cindex Bessel function, first kind 2493 2494@table @asis 2495@item @emph{Description}: 2496@code{BESSEL_J1(X)} computes the Bessel function of the first kind of 2497order 1 of @var{X}. This function is available under the name 2498@code{BESJ1} as a GNU extension. 2499 2500@item @emph{Standard}: 2501Fortran 2008 2502 2503@item @emph{Class}: 2504Elemental function 2505 2506@item @emph{Syntax}: 2507@code{RESULT = BESSEL_J1(X)} 2508 2509@item @emph{Arguments}: 2510@multitable @columnfractions .15 .70 2511@item @var{X} @tab The type shall be @code{REAL}. 2512@end multitable 2513 2514@item @emph{Return value}: 2515The return value is of type @code{REAL} and lies in the 2516range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same 2517kind as @var{X}. 2518 2519@item @emph{Example}: 2520@smallexample 2521program test_besj1 2522 real(8) :: x = 1.0_8 2523 x = bessel_j1(x) 2524end program test_besj1 2525@end smallexample 2526 2527@item @emph{Specific names}: 2528@multitable @columnfractions .20 .20 .20 .25 2529@item Name @tab Argument @tab Return type @tab Standard 2530@item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2531@end multitable 2532@end table 2533 2534 2535 2536@node BESSEL_JN 2537@section @code{BESSEL_JN} --- Bessel function of the first kind 2538@fnindex BESSEL_JN 2539@fnindex BESJN 2540@fnindex DBESJN 2541@cindex Bessel function, first kind 2542 2543@table @asis 2544@item @emph{Description}: 2545@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of 2546order @var{N} of @var{X}. This function is available under the name 2547@code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays, 2548their ranks and shapes shall conform. 2549 2550@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions 2551of the first kind of the orders @var{N1} to @var{N2}. 2552 2553@item @emph{Standard}: 2554Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2555 2556@item @emph{Class}: 2557Elemental function, except for the transformational function 2558@code{BESSEL_JN(N1, N2, X)} 2559 2560@item @emph{Syntax}: 2561@multitable @columnfractions .80 2562@item @code{RESULT = BESSEL_JN(N, X)} 2563@item @code{RESULT = BESSEL_JN(N1, N2, X)} 2564@end multitable 2565 2566@item @emph{Arguments}: 2567@multitable @columnfractions .15 .70 2568@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}. 2569@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2570@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2571@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2572for @code{BESSEL_JN(N1, N2, X)} it shall be scalar. 2573@end multitable 2574 2575@item @emph{Return value}: 2576The return value is a scalar of type @code{REAL}. It has the same 2577kind as @var{X}. 2578 2579@item @emph{Note}: 2580The transformational function uses a recurrence algorithm which might, 2581for some values of @var{X}, lead to different results than calls to 2582the elemental function. 2583 2584@item @emph{Example}: 2585@smallexample 2586program test_besjn 2587 real(8) :: x = 1.0_8 2588 x = bessel_jn(5,x) 2589end program test_besjn 2590@end smallexample 2591 2592@item @emph{Specific names}: 2593@multitable @columnfractions .20 .20 .20 .25 2594@item Name @tab Argument @tab Return type @tab Standard 2595@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2596@item @tab @code{REAL(8) X} @tab @tab 2597@end multitable 2598@end table 2599 2600 2601 2602@node BESSEL_Y0 2603@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0 2604@fnindex BESSEL_Y0 2605@fnindex BESY0 2606@fnindex DBESY0 2607@cindex Bessel function, second kind 2608 2609@table @asis 2610@item @emph{Description}: 2611@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of 2612order 0 of @var{X}. This function is available under the name 2613@code{BESY0} as a GNU extension. 2614 2615@item @emph{Standard}: 2616Fortran 2008 and later 2617 2618@item @emph{Class}: 2619Elemental function 2620 2621@item @emph{Syntax}: 2622@code{RESULT = BESSEL_Y0(X)} 2623 2624@item @emph{Arguments}: 2625@multitable @columnfractions .15 .70 2626@item @var{X} @tab The type shall be @code{REAL}. 2627@end multitable 2628 2629@item @emph{Return value}: 2630The return value is of type @code{REAL}. It has the same kind as @var{X}. 2631 2632@item @emph{Example}: 2633@smallexample 2634program test_besy0 2635 real(8) :: x = 0.0_8 2636 x = bessel_y0(x) 2637end program test_besy0 2638@end smallexample 2639 2640@item @emph{Specific names}: 2641@multitable @columnfractions .20 .20 .20 .25 2642@item Name @tab Argument @tab Return type @tab Standard 2643@item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2644@end multitable 2645@end table 2646 2647 2648 2649@node BESSEL_Y1 2650@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1 2651@fnindex BESSEL_Y1 2652@fnindex BESY1 2653@fnindex DBESY1 2654@cindex Bessel function, second kind 2655 2656@table @asis 2657@item @emph{Description}: 2658@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of 2659order 1 of @var{X}. This function is available under the name 2660@code{BESY1} as a GNU extension. 2661 2662@item @emph{Standard}: 2663Fortran 2008 and later 2664 2665@item @emph{Class}: 2666Elemental function 2667 2668@item @emph{Syntax}: 2669@code{RESULT = BESSEL_Y1(X)} 2670 2671@item @emph{Arguments}: 2672@multitable @columnfractions .15 .70 2673@item @var{X} @tab The type shall be @code{REAL}. 2674@end multitable 2675 2676@item @emph{Return value}: 2677The return value is of type @code{REAL}. It has the same kind as @var{X}. 2678 2679@item @emph{Example}: 2680@smallexample 2681program test_besy1 2682 real(8) :: x = 1.0_8 2683 x = bessel_y1(x) 2684end program test_besy1 2685@end smallexample 2686 2687@item @emph{Specific names}: 2688@multitable @columnfractions .20 .20 .20 .25 2689@item Name @tab Argument @tab Return type @tab Standard 2690@item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2691@end multitable 2692@end table 2693 2694 2695 2696@node BESSEL_YN 2697@section @code{BESSEL_YN} --- Bessel function of the second kind 2698@fnindex BESSEL_YN 2699@fnindex BESYN 2700@fnindex DBESYN 2701@cindex Bessel function, second kind 2702 2703@table @asis 2704@item @emph{Description}: 2705@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of 2706order @var{N} of @var{X}. This function is available under the name 2707@code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays, 2708their ranks and shapes shall conform. 2709 2710@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions 2711of the first kind of the orders @var{N1} to @var{N2}. 2712 2713@item @emph{Standard}: 2714Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2715 2716@item @emph{Class}: 2717Elemental function, except for the transformational function 2718@code{BESSEL_YN(N1, N2, X)} 2719 2720@item @emph{Syntax}: 2721@multitable @columnfractions .80 2722@item @code{RESULT = BESSEL_YN(N, X)} 2723@item @code{RESULT = BESSEL_YN(N1, N2, X)} 2724@end multitable 2725 2726@item @emph{Arguments}: 2727@multitable @columnfractions .15 .70 2728@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} . 2729@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2730@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2731@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2732for @code{BESSEL_YN(N1, N2, X)} it shall be scalar. 2733@end multitable 2734 2735@item @emph{Return value}: 2736The return value is a scalar of type @code{REAL}. It has the same 2737kind as @var{X}. 2738 2739@item @emph{Note}: 2740The transformational function uses a recurrence algorithm which might, 2741for some values of @var{X}, lead to different results than calls to 2742the elemental function. 2743 2744@item @emph{Example}: 2745@smallexample 2746program test_besyn 2747 real(8) :: x = 1.0_8 2748 x = bessel_yn(5,x) 2749end program test_besyn 2750@end smallexample 2751 2752@item @emph{Specific names}: 2753@multitable @columnfractions .20 .20 .20 .25 2754@item Name @tab Argument @tab Return type @tab Standard 2755@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2756@item @tab @code{REAL(8) X} @tab @tab 2757@end multitable 2758@end table 2759 2760 2761 2762@node BGE 2763@section @code{BGE} --- Bitwise greater than or equal to 2764@fnindex BGE 2765@cindex bitwise comparison 2766 2767@table @asis 2768@item @emph{Description}: 2769Determines whether an integral is a bitwise greater than or equal to 2770another. 2771 2772@item @emph{Standard}: 2773Fortran 2008 and later 2774 2775@item @emph{Class}: 2776Elemental function 2777 2778@item @emph{Syntax}: 2779@code{RESULT = BGE(I, J)} 2780 2781@item @emph{Arguments}: 2782@multitable @columnfractions .15 .70 2783@item @var{I} @tab Shall be of @code{INTEGER} type. 2784@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2785as @var{I}. 2786@end multitable 2787 2788@item @emph{Return value}: 2789The return value is of type @code{LOGICAL} and of the default kind. 2790 2791@item @emph{See also}: 2792@ref{BGT}, @ref{BLE}, @ref{BLT} 2793@end table 2794 2795 2796 2797@node BGT 2798@section @code{BGT} --- Bitwise greater than 2799@fnindex BGT 2800@cindex bitwise comparison 2801 2802@table @asis 2803@item @emph{Description}: 2804Determines whether an integral is a bitwise greater than another. 2805 2806@item @emph{Standard}: 2807Fortran 2008 and later 2808 2809@item @emph{Class}: 2810Elemental function 2811 2812@item @emph{Syntax}: 2813@code{RESULT = BGT(I, J)} 2814 2815@item @emph{Arguments}: 2816@multitable @columnfractions .15 .70 2817@item @var{I} @tab Shall be of @code{INTEGER} type. 2818@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2819as @var{I}. 2820@end multitable 2821 2822@item @emph{Return value}: 2823The return value is of type @code{LOGICAL} and of the default kind. 2824 2825@item @emph{See also}: 2826@ref{BGE}, @ref{BLE}, @ref{BLT} 2827@end table 2828 2829 2830 2831@node BIT_SIZE 2832@section @code{BIT_SIZE} --- Bit size inquiry function 2833@fnindex BIT_SIZE 2834@cindex bits, number of 2835@cindex size of a variable, in bits 2836 2837@table @asis 2838@item @emph{Description}: 2839@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) 2840represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is 2841independent of the actual value of @var{I}. 2842 2843@item @emph{Standard}: 2844Fortran 95 and later 2845 2846@item @emph{Class}: 2847Inquiry function 2848 2849@item @emph{Syntax}: 2850@code{RESULT = BIT_SIZE(I)} 2851 2852@item @emph{Arguments}: 2853@multitable @columnfractions .15 .70 2854@item @var{I} @tab The type shall be @code{INTEGER}. 2855@end multitable 2856 2857@item @emph{Return value}: 2858The return value is of type @code{INTEGER} 2859 2860@item @emph{Example}: 2861@smallexample 2862program test_bit_size 2863 integer :: i = 123 2864 integer :: size 2865 size = bit_size(i) 2866 print *, size 2867end program test_bit_size 2868@end smallexample 2869@end table 2870 2871 2872 2873@node BLE 2874@section @code{BLE} --- Bitwise less than or equal to 2875@fnindex BLE 2876@cindex bitwise comparison 2877 2878@table @asis 2879@item @emph{Description}: 2880Determines whether an integral is a bitwise less than or equal to 2881another. 2882 2883@item @emph{Standard}: 2884Fortran 2008 and later 2885 2886@item @emph{Class}: 2887Elemental function 2888 2889@item @emph{Syntax}: 2890@code{RESULT = BLE(I, J)} 2891 2892@item @emph{Arguments}: 2893@multitable @columnfractions .15 .70 2894@item @var{I} @tab Shall be of @code{INTEGER} type. 2895@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2896as @var{I}. 2897@end multitable 2898 2899@item @emph{Return value}: 2900The return value is of type @code{LOGICAL} and of the default kind. 2901 2902@item @emph{See also}: 2903@ref{BGT}, @ref{BGE}, @ref{BLT} 2904@end table 2905 2906 2907 2908@node BLT 2909@section @code{BLT} --- Bitwise less than 2910@fnindex BLT 2911@cindex bitwise comparison 2912 2913@table @asis 2914@item @emph{Description}: 2915Determines whether an integral is a bitwise less than another. 2916 2917@item @emph{Standard}: 2918Fortran 2008 and later 2919 2920@item @emph{Class}: 2921Elemental function 2922 2923@item @emph{Syntax}: 2924@code{RESULT = BLT(I, J)} 2925 2926@item @emph{Arguments}: 2927@multitable @columnfractions .15 .70 2928@item @var{I} @tab Shall be of @code{INTEGER} type. 2929@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2930as @var{I}. 2931@end multitable 2932 2933@item @emph{Return value}: 2934The return value is of type @code{LOGICAL} and of the default kind. 2935 2936@item @emph{See also}: 2937@ref{BGE}, @ref{BGT}, @ref{BLE} 2938@end table 2939 2940 2941 2942@node BTEST 2943@section @code{BTEST} --- Bit test function 2944@fnindex BTEST 2945@fnindex BBTEST 2946@fnindex BITEST 2947@fnindex BJTEST 2948@fnindex BKTEST 2949@cindex bits, testing 2950 2951@table @asis 2952@item @emph{Description}: 2953@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} 2954in @var{I} is set. The counting of the bits starts at 0. 2955 2956@item @emph{Standard}: 2957Fortran 95 and later, has overloads that are GNU extensions 2958 2959@item @emph{Class}: 2960Elemental function 2961 2962@item @emph{Syntax}: 2963@code{RESULT = BTEST(I, POS)} 2964 2965@item @emph{Arguments}: 2966@multitable @columnfractions .15 .70 2967@item @var{I} @tab The type shall be @code{INTEGER}. 2968@item @var{POS} @tab The type shall be @code{INTEGER}. 2969@end multitable 2970 2971@item @emph{Return value}: 2972The return value is of type @code{LOGICAL} 2973 2974@item @emph{Example}: 2975@smallexample 2976program test_btest 2977 integer :: i = 32768 + 1024 + 64 2978 integer :: pos 2979 logical :: bool 2980 do pos=0,16 2981 bool = btest(i, pos) 2982 print *, pos, bool 2983 end do 2984end program test_btest 2985@end smallexample 2986 2987@item @emph{Specific names}: 2988@multitable @columnfractions .20 .20 .20 .25 2989@item Name @tab Argument @tab Return type @tab Standard 2990@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later 2991@item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension 2992@item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension 2993@item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension 2994@item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension 2995@end multitable 2996@end table 2997 2998@node C_ASSOCIATED 2999@section @code{C_ASSOCIATED} --- Status of a C pointer 3000@fnindex C_ASSOCIATED 3001@cindex association status, C pointer 3002@cindex pointer, C association status 3003 3004@table @asis 3005@item @emph{Description}: 3006@code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer 3007@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}. 3008 3009@item @emph{Standard}: 3010Fortran 2003 and later 3011 3012@item @emph{Class}: 3013Inquiry function 3014 3015@item @emph{Syntax}: 3016@code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])} 3017 3018@item @emph{Arguments}: 3019@multitable @columnfractions .15 .70 3020@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}. 3021@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}. 3022@end multitable 3023 3024@item @emph{Return value}: 3025The return value is of type @code{LOGICAL}; it is @code{.false.} if either 3026@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2} 3027point to different addresses. 3028 3029@item @emph{Example}: 3030@smallexample 3031subroutine association_test(a,b) 3032 use iso_c_binding, only: c_associated, c_loc, c_ptr 3033 implicit none 3034 real, pointer :: a 3035 type(c_ptr) :: b 3036 if(c_associated(b, c_loc(a))) & 3037 stop 'b and a do not point to same target' 3038end subroutine association_test 3039@end smallexample 3040 3041@item @emph{See also}: 3042@ref{C_LOC}, @ref{C_FUNLOC} 3043@end table 3044 3045 3046@node C_F_POINTER 3047@section @code{C_F_POINTER} --- Convert C into Fortran pointer 3048@fnindex C_F_POINTER 3049@cindex pointer, convert C to Fortran 3050 3051@table @asis 3052@item @emph{Description}: 3053@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer 3054@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape. 3055 3056@item @emph{Standard}: 3057Fortran 2003 and later 3058 3059@item @emph{Class}: 3060Subroutine 3061 3062@item @emph{Syntax}: 3063@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])} 3064 3065@item @emph{Arguments}: 3066@multitable @columnfractions .15 .70 3067@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is 3068@code{INTENT(IN)}. 3069@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is 3070@code{INTENT(OUT)}. 3071@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER} 3072with @code{INTENT(IN)}. It shall be present 3073if and only if @var{fptr} is an array. The size 3074must be equal to the rank of @var{fptr}. 3075@end multitable 3076 3077@item @emph{Example}: 3078@smallexample 3079program main 3080 use iso_c_binding 3081 implicit none 3082 interface 3083 subroutine my_routine(p) bind(c,name='myC_func') 3084 import :: c_ptr 3085 type(c_ptr), intent(out) :: p 3086 end subroutine 3087 end interface 3088 type(c_ptr) :: cptr 3089 real,pointer :: a(:) 3090 call my_routine(cptr) 3091 call c_f_pointer(cptr, a, [12]) 3092end program main 3093@end smallexample 3094 3095@item @emph{See also}: 3096@ref{C_LOC}, @ref{C_F_PROCPOINTER} 3097@end table 3098 3099 3100@node C_F_PROCPOINTER 3101@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer 3102@fnindex C_F_PROCPOINTER 3103@cindex pointer, C address of pointers 3104 3105@table @asis 3106@item @emph{Description}: 3107@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer 3108@var{CPTR} to the Fortran procedure pointer @var{FPTR}. 3109 3110@item @emph{Standard}: 3111Fortran 2003 and later 3112 3113@item @emph{Class}: 3114Subroutine 3115 3116@item @emph{Syntax}: 3117@code{CALL C_F_PROCPOINTER(cptr, fptr)} 3118 3119@item @emph{Arguments}: 3120@multitable @columnfractions .15 .70 3121@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is 3122@code{INTENT(IN)}. 3123@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is 3124@code{INTENT(OUT)}. 3125@end multitable 3126 3127@item @emph{Example}: 3128@smallexample 3129program main 3130 use iso_c_binding 3131 implicit none 3132 abstract interface 3133 function func(a) 3134 import :: c_float 3135 real(c_float), intent(in) :: a 3136 real(c_float) :: func 3137 end function 3138 end interface 3139 interface 3140 function getIterFunc() bind(c,name="getIterFunc") 3141 import :: c_funptr 3142 type(c_funptr) :: getIterFunc 3143 end function 3144 end interface 3145 type(c_funptr) :: cfunptr 3146 procedure(func), pointer :: myFunc 3147 cfunptr = getIterFunc() 3148 call c_f_procpointer(cfunptr, myFunc) 3149end program main 3150@end smallexample 3151 3152@item @emph{See also}: 3153@ref{C_LOC}, @ref{C_F_POINTER} 3154@end table 3155 3156 3157@node C_FUNLOC 3158@section @code{C_FUNLOC} --- Obtain the C address of a procedure 3159@fnindex C_FUNLOC 3160@cindex pointer, C address of procedures 3161 3162@table @asis 3163@item @emph{Description}: 3164@code{C_FUNLOC(x)} determines the C address of the argument. 3165 3166@item @emph{Standard}: 3167Fortran 2003 and later 3168 3169@item @emph{Class}: 3170Inquiry function 3171 3172@item @emph{Syntax}: 3173@code{RESULT = C_FUNLOC(x)} 3174 3175@item @emph{Arguments}: 3176@multitable @columnfractions .15 .70 3177@item @var{x} @tab Interoperable function or pointer to such function. 3178@end multitable 3179 3180@item @emph{Return value}: 3181The return value is of type @code{C_FUNPTR} and contains the C address 3182of the argument. 3183 3184@item @emph{Example}: 3185@smallexample 3186module x 3187 use iso_c_binding 3188 implicit none 3189contains 3190 subroutine sub(a) bind(c) 3191 real(c_float) :: a 3192 a = sqrt(a)+5.0 3193 end subroutine sub 3194end module x 3195program main 3196 use iso_c_binding 3197 use x 3198 implicit none 3199 interface 3200 subroutine my_routine(p) bind(c,name='myC_func') 3201 import :: c_funptr 3202 type(c_funptr), intent(in) :: p 3203 end subroutine 3204 end interface 3205 call my_routine(c_funloc(sub)) 3206end program main 3207@end smallexample 3208 3209@item @emph{See also}: 3210@ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} 3211@end table 3212 3213 3214@node C_LOC 3215@section @code{C_LOC} --- Obtain the C address of an object 3216@fnindex C_LOC 3217@cindex procedure pointer, convert C to Fortran 3218 3219@table @asis 3220@item @emph{Description}: 3221@code{C_LOC(X)} determines the C address of the argument. 3222 3223@item @emph{Standard}: 3224Fortran 2003 and later 3225 3226@item @emph{Class}: 3227Inquiry function 3228 3229@item @emph{Syntax}: 3230@code{RESULT = C_LOC(X)} 3231 3232@item @emph{Arguments}: 3233@multitable @columnfractions .10 .75 3234@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. 3235 3236@end multitable 3237 3238@item @emph{Return value}: 3239The return value is of type @code{C_PTR} and contains the C address 3240of the argument. 3241 3242@item @emph{Example}: 3243@smallexample 3244subroutine association_test(a,b) 3245 use iso_c_binding, only: c_associated, c_loc, c_ptr 3246 implicit none 3247 real, pointer :: a 3248 type(c_ptr) :: b 3249 if(c_associated(b, c_loc(a))) & 3250 stop 'b and a do not point to same target' 3251end subroutine association_test 3252@end smallexample 3253 3254@item @emph{See also}: 3255@ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} 3256@end table 3257 3258 3259@node C_SIZEOF 3260@section @code{C_SIZEOF} --- Size in bytes of an expression 3261@fnindex C_SIZEOF 3262@cindex expression size 3263@cindex size of an expression 3264 3265@table @asis 3266@item @emph{Description}: 3267@code{C_SIZEOF(X)} calculates the number of bytes of storage the 3268expression @code{X} occupies. 3269 3270@item @emph{Standard}: 3271Fortran 2008 3272 3273@item @emph{Class}: 3274Inquiry function of the module @code{ISO_C_BINDING} 3275 3276@item @emph{Syntax}: 3277@code{N = C_SIZEOF(X)} 3278 3279@item @emph{Arguments}: 3280@multitable @columnfractions .15 .70 3281@item @var{X} @tab The argument shall be an interoperable data entity. 3282@end multitable 3283 3284@item @emph{Return value}: 3285The return value is of type integer and of the system-dependent kind 3286@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the 3287number of bytes occupied by the argument. If the argument has the 3288@code{POINTER} attribute, the number of bytes of the storage area pointed 3289to is returned. If the argument is of a derived type with @code{POINTER} 3290or @code{ALLOCATABLE} components, the return value does not account for 3291the sizes of the data pointed to by these components. 3292 3293@item @emph{Example}: 3294@smallexample 3295 use iso_c_binding 3296 integer(c_int) :: i 3297 real(c_float) :: r, s(5) 3298 print *, (c_sizeof(s)/c_sizeof(r) == 5) 3299 end 3300@end smallexample 3301The example will print @code{.TRUE.} unless you are using a platform 3302where default @code{REAL} variables are unusually padded. 3303 3304@item @emph{See also}: 3305@ref{SIZEOF}, @ref{STORAGE_SIZE} 3306@end table 3307 3308 3309@node CEILING 3310@section @code{CEILING} --- Integer ceiling function 3311@fnindex CEILING 3312@cindex ceiling 3313@cindex rounding, ceiling 3314 3315@table @asis 3316@item @emph{Description}: 3317@code{CEILING(A)} returns the least integer greater than or equal to @var{A}. 3318 3319@item @emph{Standard}: 3320Fortran 95 and later 3321 3322@item @emph{Class}: 3323Elemental function 3324 3325@item @emph{Syntax}: 3326@code{RESULT = CEILING(A [, KIND])} 3327 3328@item @emph{Arguments}: 3329@multitable @columnfractions .15 .70 3330@item @var{A} @tab The type shall be @code{REAL}. 3331@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3332expression indicating the kind parameter of the result. 3333@end multitable 3334 3335@item @emph{Return value}: 3336The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 3337and a default-kind @code{INTEGER} otherwise. 3338 3339@item @emph{Example}: 3340@smallexample 3341program test_ceiling 3342 real :: x = 63.29 3343 real :: y = -63.59 3344 print *, ceiling(x) ! returns 64 3345 print *, ceiling(y) ! returns -63 3346end program test_ceiling 3347@end smallexample 3348 3349@item @emph{See also}: 3350@ref{FLOOR}, @ref{NINT} 3351 3352@end table 3353 3354 3355 3356@node CHAR 3357@section @code{CHAR} --- Character conversion function 3358@fnindex CHAR 3359@cindex conversion, to character 3360 3361@table @asis 3362@item @emph{Description}: 3363@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}. 3364 3365@item @emph{Standard}: 3366Fortran 77 and later 3367 3368@item @emph{Class}: 3369Elemental function 3370 3371@item @emph{Syntax}: 3372@code{RESULT = CHAR(I [, KIND])} 3373 3374@item @emph{Arguments}: 3375@multitable @columnfractions .15 .70 3376@item @var{I} @tab The type shall be @code{INTEGER}. 3377@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3378expression indicating the kind parameter of the result. 3379@end multitable 3380 3381@item @emph{Return value}: 3382The return value is of type @code{CHARACTER(1)} 3383 3384@item @emph{Example}: 3385@smallexample 3386program test_char 3387 integer :: i = 74 3388 character(1) :: c 3389 c = char(i) 3390 print *, i, c ! returns 'J' 3391end program test_char 3392@end smallexample 3393 3394@item @emph{Specific names}: 3395@multitable @columnfractions .20 .20 .20 .25 3396@item Name @tab Argument @tab Return type @tab Standard 3397@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later 3398@end multitable 3399 3400@item @emph{Note}: 3401See @ref{ICHAR} for a discussion of converting between numerical values 3402and formatted string representations. 3403 3404@item @emph{See also}: 3405@ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR} 3406 3407@end table 3408 3409 3410 3411@node CHDIR 3412@section @code{CHDIR} --- Change working directory 3413@fnindex CHDIR 3414@cindex system, working directory 3415 3416@table @asis 3417@item @emph{Description}: 3418Change current working directory to a specified path. 3419 3420This intrinsic is provided in both subroutine and function forms; however, 3421only one form can be used in any given program unit. 3422 3423@item @emph{Standard}: 3424GNU extension 3425 3426@item @emph{Class}: 3427Subroutine, function 3428 3429@item @emph{Syntax}: 3430@multitable @columnfractions .80 3431@item @code{CALL CHDIR(NAME [, STATUS])} 3432@item @code{STATUS = CHDIR(NAME)} 3433@end multitable 3434 3435@item @emph{Arguments}: 3436@multitable @columnfractions .15 .70 3437@item @var{NAME} @tab The type shall be @code{CHARACTER} of default 3438kind and shall specify a valid path within the file system. 3439@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default 3440kind. Returns 0 on success, and a system specific and nonzero error code 3441otherwise. 3442@end multitable 3443 3444@item @emph{Example}: 3445@smallexample 3446PROGRAM test_chdir 3447 CHARACTER(len=255) :: path 3448 CALL getcwd(path) 3449 WRITE(*,*) TRIM(path) 3450 CALL chdir("/tmp") 3451 CALL getcwd(path) 3452 WRITE(*,*) TRIM(path) 3453END PROGRAM 3454@end smallexample 3455 3456@item @emph{See also}: 3457@ref{GETCWD} 3458@end table 3459 3460 3461 3462@node CHMOD 3463@section @code{CHMOD} --- Change access permissions of files 3464@fnindex CHMOD 3465@cindex file system, change access mode 3466 3467@table @asis 3468@item @emph{Description}: 3469@code{CHMOD} changes the permissions of a file. 3470 3471This intrinsic is provided in both subroutine and function forms; however, 3472only one form can be used in any given program unit. 3473 3474@item @emph{Standard}: 3475GNU extension 3476 3477@item @emph{Class}: 3478Subroutine, function 3479 3480@item @emph{Syntax}: 3481@multitable @columnfractions .80 3482@item @code{CALL CHMOD(NAME, MODE[, STATUS])} 3483@item @code{STATUS = CHMOD(NAME, MODE)} 3484@end multitable 3485 3486@item @emph{Arguments}: 3487@multitable @columnfractions .15 .70 3488 3489@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 3490file name. Trailing blanks are ignored unless the character 3491@code{achar(0)} is present, then all characters up to and excluding 3492@code{achar(0)} are used as the file name. 3493 3494@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the 3495file permission. @var{MODE} uses the same syntax as the @code{chmod} utility 3496as defined by the POSIX standard. The argument shall either be a string of 3497a nonnegative octal number or a symbolic mode. 3498 3499@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is 3500@code{0} on success and nonzero otherwise. 3501@end multitable 3502 3503@item @emph{Return value}: 3504In either syntax, @var{STATUS} is set to @code{0} on success and nonzero 3505otherwise. 3506 3507@item @emph{Example}: 3508@code{CHMOD} as subroutine 3509@smallexample 3510program chmod_test 3511 implicit none 3512 integer :: status 3513 call chmod('test.dat','u+x',status) 3514 print *, 'Status: ', status 3515end program chmod_test 3516@end smallexample 3517@code{CHMOD} as function: 3518@smallexample 3519program chmod_test 3520 implicit none 3521 integer :: status 3522 status = chmod('test.dat','u+x') 3523 print *, 'Status: ', status 3524end program chmod_test 3525@end smallexample 3526 3527@end table 3528 3529 3530 3531@node CMPLX 3532@section @code{CMPLX} --- Complex conversion function 3533@fnindex CMPLX 3534@cindex complex numbers, conversion to 3535@cindex conversion, to complex 3536 3537@table @asis 3538@item @emph{Description}: 3539@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to 3540the real component. If @var{Y} is present it is converted to the imaginary 3541component. If @var{Y} is not present then the imaginary component is set to 35420.0. If @var{X} is complex then @var{Y} must not be present. 3543 3544@item @emph{Standard}: 3545Fortran 77 and later 3546 3547@item @emph{Class}: 3548Elemental function 3549 3550@item @emph{Syntax}: 3551@code{RESULT = CMPLX(X [, Y [, KIND]])} 3552 3553@item @emph{Arguments}: 3554@multitable @columnfractions .15 .70 3555@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 3556or @code{COMPLEX}. 3557@item @var{Y} @tab (Optional; only allowed if @var{X} is not 3558@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. 3559@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3560expression indicating the kind parameter of the result. 3561@end multitable 3562 3563@item @emph{Return value}: 3564The return value is of @code{COMPLEX} type, with a kind equal to 3565@var{KIND} if it is specified. If @var{KIND} is not specified, the 3566result is of the default @code{COMPLEX} kind, regardless of the kinds of 3567@var{X} and @var{Y}. 3568 3569@item @emph{Example}: 3570@smallexample 3571program test_cmplx 3572 integer :: i = 42 3573 real :: x = 3.14 3574 complex :: z 3575 z = cmplx(i, x) 3576 print *, z, cmplx(x) 3577end program test_cmplx 3578@end smallexample 3579 3580@item @emph{See also}: 3581@ref{COMPLEX} 3582@end table 3583 3584 3585 3586@node CO_BROADCAST 3587@section @code{CO_BROADCAST} --- Copy a value to all images the current set of images 3588@fnindex CO_BROADCAST 3589@cindex Collectives, value broadcasting 3590 3591@table @asis 3592@item @emph{Description}: 3593@code{CO_BROADCAST} copies the value of argument @var{A} on the image with 3594image index @code{SOURCE_IMAGE} to all images in the current team. @var{A} 3595becomes defined as if by intrinsic assignment. If the execution was 3596successful and @var{STAT} is present, it is assigned the value zero. If the 3597execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3598@var{ERRMSG} gets assigned a value describing the occurred error. 3599 3600@item @emph{Standard}: 3601Technical Specification (TS) 18508 or later 3602 3603@item @emph{Class}: 3604Collective subroutine 3605 3606@item @emph{Syntax}: 3607@code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])} 3608 3609@item @emph{Arguments}: 3610@multitable @columnfractions .15 .70 3611@item @var{A} @tab INTENT(INOUT) argument; shall have the same 3612dynamic type and type paramters on all images of the current team. If it 3613is an array, it shall have the same shape on all images. 3614@item @var{SOURCE_IMAGE} @tab a scalar integer expression. 3615It shall have the same the same value on all images and refer to an 3616image of the current team. 3617@item @var{STAT} @tab (optional) a scalar integer variable 3618@item @var{ERRMSG} @tab (optional) a scalar character variable 3619@end multitable 3620 3621@item @emph{Example}: 3622@smallexample 3623program test 3624 integer :: val(3) 3625 if (this_image() == 1) then 3626 val = [1, 5, 3] 3627 end if 3628 call co_broadcast (val, source_image=1) 3629 print *, this_image, ":", val 3630end program test 3631@end smallexample 3632 3633@item @emph{See also}: 3634@ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE} 3635@end table 3636 3637 3638 3639@node CO_MAX 3640@section @code{CO_MAX} --- Maximal value on the current set of images 3641@fnindex CO_MAX 3642@cindex Collectives, maximal value 3643 3644@table @asis 3645@item @emph{Description}: 3646@code{CO_MAX} determines element-wise the maximal value of @var{A} on all 3647images of the current team. If @var{RESULT_IMAGE} is present, the maximum 3648values are returned in @var{A} on the specified image only and the value 3649of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3650not present, the value is returned on all images. If the execution was 3651successful and @var{STAT} is present, it is assigned the value zero. If the 3652execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3653@var{ERRMSG} gets assigned a value describing the occurred error. 3654 3655@item @emph{Standard}: 3656Technical Specification (TS) 18508 or later 3657 3658@item @emph{Class}: 3659Collective subroutine 3660 3661@item @emph{Syntax}: 3662@code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])} 3663 3664@item @emph{Arguments}: 3665@multitable @columnfractions .15 .70 3666@item @var{A} @tab shall be an integer, real or character variable, 3667which has the same type and type parameters on all images of the team. 3668@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3669present, it shall have the same the same value on all images and refer to an 3670image of the current team. 3671@item @var{STAT} @tab (optional) a scalar integer variable 3672@item @var{ERRMSG} @tab (optional) a scalar character variable 3673@end multitable 3674 3675@item @emph{Example}: 3676@smallexample 3677program test 3678 integer :: val 3679 val = this_image () 3680 call co_max (val, result_image=1) 3681 if (this_image() == 1) then 3682 write(*,*) "Maximal value", val ! prints num_images() 3683 end if 3684end program test 3685@end smallexample 3686 3687@item @emph{See also}: 3688@ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3689@end table 3690 3691 3692 3693@node CO_MIN 3694@section @code{CO_MIN} --- Minimal value on the current set of images 3695@fnindex CO_MIN 3696@cindex Collectives, minimal value 3697 3698@table @asis 3699@item @emph{Description}: 3700@code{CO_MIN} determines element-wise the minimal value of @var{A} on all 3701images of the current team. If @var{RESULT_IMAGE} is present, the minimal 3702values are returned in @var{A} on the specified image only and the value 3703of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3704not present, the value is returned on all images. If the execution was 3705successful and @var{STAT} is present, it is assigned the value zero. If the 3706execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3707@var{ERRMSG} gets assigned a value describing the occurred error. 3708 3709@item @emph{Standard}: 3710Technical Specification (TS) 18508 or later 3711 3712@item @emph{Class}: 3713Collective subroutine 3714 3715@item @emph{Syntax}: 3716@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3717 3718@item @emph{Arguments}: 3719@multitable @columnfractions .15 .70 3720@item @var{A} @tab shall be an integer, real or character variable, 3721which has the same type and type parameters on all images of the team. 3722@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3723present, it shall have the same the same value on all images and refer to an 3724image of the current team. 3725@item @var{STAT} @tab (optional) a scalar integer variable 3726@item @var{ERRMSG} @tab (optional) a scalar character variable 3727@end multitable 3728 3729@item @emph{Example}: 3730@smallexample 3731program test 3732 integer :: val 3733 val = this_image () 3734 call co_min (val, result_image=1) 3735 if (this_image() == 1) then 3736 write(*,*) "Minimal value", val ! prints 1 3737 end if 3738end program test 3739@end smallexample 3740 3741@item @emph{See also}: 3742@ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3743@end table 3744 3745 3746 3747@node CO_REDUCE 3748@section @code{CO_REDUCE} --- Reduction of values on the current set of images 3749@fnindex CO_REDUCE 3750@cindex Collectives, generic reduction 3751 3752@table @asis 3753@item @emph{Description}: 3754@code{CO_REDUCE} determines element-wise the reduction of the value of @var{A} 3755on all images of the current team. The pure function passed as @var{OPERATOR} 3756is used to pairwise reduce the values of @var{A} by passing either the value 3757of @var{A} of different images or the result values of such a reduction as 3758argument. If @var{A} is an array, the deduction is done element wise. If 3759@var{RESULT_IMAGE} is present, the result values are returned in @var{A} on 3760the specified image only and the value of @var{A} on the other images become 3761undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all 3762images. If the execution was successful and @var{STAT} is present, it is 3763assigned the value zero. If the execution failed, @var{STAT} gets assigned 3764a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing 3765the occurred error. 3766 3767@item @emph{Standard}: 3768Technical Specification (TS) 18508 or later 3769 3770@item @emph{Class}: 3771Collective subroutine 3772 3773@item @emph{Syntax}: 3774@code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])} 3775 3776@item @emph{Arguments}: 3777@multitable @columnfractions .15 .70 3778@item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be 3779nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, 3780it shall be associated. @var{A} shall have the same type and type parameters on 3781all images of the team; if it is an array, it shall have the same shape on all 3782images. 3783@item @var{OPERATOR} @tab pure function with two scalar nonallocatable 3784arguments, which shall be nonpolymorphic and have the same type and type 3785parameters as @var{A}. The function shall return a nonallocatable scalar of 3786the same type and type parameters as @var{A}. The function shall be the same on 3787all images and with regards to the arguments mathematically commutative and 3788associative. Note that @var{OPERATOR} may not be an elemental function, unless 3789it is an intrisic function. 3790@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3791present, it shall have the same the same value on all images and refer to an 3792image of the current team. 3793@item @var{STAT} @tab (optional) a scalar integer variable 3794@item @var{ERRMSG} @tab (optional) a scalar character variable 3795@end multitable 3796 3797@item @emph{Example}: 3798@smallexample 3799program test 3800 integer :: val 3801 val = this_image () 3802 call co_reduce (val, result_image=1, operator=myprod) 3803 if (this_image() == 1) then 3804 write(*,*) "Product value", val ! prints num_images() factorial 3805 end if 3806contains 3807 pure function myprod(a, b) 3808 integer, value :: a, b 3809 integer :: myprod 3810 myprod = a * b 3811 end function myprod 3812end program test 3813@end smallexample 3814 3815@item @emph{Note}: 3816While the rules permit in principle an intrinsic function, none of the 3817intrinsics in the standard fulfill the criteria of having a specific 3818function, which takes two arguments of the same type and returning that 3819type as result. 3820 3821@item @emph{See also}: 3822@ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST} 3823@end table 3824 3825 3826 3827@node CO_SUM 3828@section @code{CO_SUM} --- Sum of values on the current set of images 3829@fnindex CO_SUM 3830@cindex Collectives, sum of values 3831 3832@table @asis 3833@item @emph{Description}: 3834@code{CO_SUM} sums up the values of each element of @var{A} on all 3835images of the current team. If @var{RESULT_IMAGE} is present, the summed-up 3836values are returned in @var{A} on the specified image only and the value 3837of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3838not present, the value is returned on all images. If the execution was 3839successful and @var{STAT} is present, it is assigned the value zero. If the 3840execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3841@var{ERRMSG} gets assigned a value describing the occurred error. 3842 3843@item @emph{Standard}: 3844Technical Specification (TS) 18508 or later 3845 3846@item @emph{Class}: 3847Collective subroutine 3848 3849@item @emph{Syntax}: 3850@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3851 3852@item @emph{Arguments}: 3853@multitable @columnfractions .15 .70 3854@item @var{A} @tab shall be an integer, real or complex variable, 3855which has the same type and type parameters on all images of the team. 3856@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3857present, it shall have the same the same value on all images and refer to an 3858image of the current team. 3859@item @var{STAT} @tab (optional) a scalar integer variable 3860@item @var{ERRMSG} @tab (optional) a scalar character variable 3861@end multitable 3862 3863@item @emph{Example}: 3864@smallexample 3865program test 3866 integer :: val 3867 val = this_image () 3868 call co_sum (val, result_image=1) 3869 if (this_image() == 1) then 3870 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images() 3871 end if 3872end program test 3873@end smallexample 3874 3875@item @emph{See also}: 3876@ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3877@end table 3878 3879 3880 3881@node COMMAND_ARGUMENT_COUNT 3882@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments 3883@fnindex COMMAND_ARGUMENT_COUNT 3884@cindex command-line arguments 3885@cindex command-line arguments, number of 3886@cindex arguments, to program 3887 3888@table @asis 3889@item @emph{Description}: 3890@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the 3891command line when the containing program was invoked. 3892 3893@item @emph{Standard}: 3894Fortran 2003 and later 3895 3896@item @emph{Class}: 3897Inquiry function 3898 3899@item @emph{Syntax}: 3900@code{RESULT = COMMAND_ARGUMENT_COUNT()} 3901 3902@item @emph{Arguments}: 3903@multitable @columnfractions .15 .70 3904@item None 3905@end multitable 3906 3907@item @emph{Return value}: 3908The return value is an @code{INTEGER} of default kind. 3909 3910@item @emph{Example}: 3911@smallexample 3912program test_command_argument_count 3913 integer :: count 3914 count = command_argument_count() 3915 print *, count 3916end program test_command_argument_count 3917@end smallexample 3918 3919@item @emph{See also}: 3920@ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT} 3921@end table 3922 3923 3924 3925@node COMPILER_OPTIONS 3926@section @code{COMPILER_OPTIONS} --- Options passed to the compiler 3927@fnindex COMPILER_OPTIONS 3928@cindex flags inquiry function 3929@cindex options inquiry function 3930@cindex compiler flags inquiry function 3931 3932@table @asis 3933@item @emph{Description}: 3934@code{COMPILER_OPTIONS} returns a string with the options used for 3935compiling. 3936 3937@item @emph{Standard}: 3938Fortran 2008 3939 3940@item @emph{Class}: 3941Inquiry function of the module @code{ISO_FORTRAN_ENV} 3942 3943@item @emph{Syntax}: 3944@code{STR = COMPILER_OPTIONS()} 3945 3946@item @emph{Arguments}: 3947None. 3948 3949@item @emph{Return value}: 3950The return value is a default-kind string with system-dependent length. 3951It contains the compiler flags used to compile the file, which called 3952the @code{COMPILER_OPTIONS} intrinsic. 3953 3954@item @emph{Example}: 3955@smallexample 3956 use iso_fortran_env 3957 print '(4a)', 'This file was compiled by ', & 3958 compiler_version(), ' using the options ', & 3959 compiler_options() 3960 end 3961@end smallexample 3962 3963@item @emph{See also}: 3964@ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV} 3965@end table 3966 3967 3968 3969@node COMPILER_VERSION 3970@section @code{COMPILER_VERSION} --- Compiler version string 3971@fnindex COMPILER_VERSION 3972@cindex compiler, name and version 3973@cindex version of the compiler 3974 3975@table @asis 3976@item @emph{Description}: 3977@code{COMPILER_VERSION} returns a string with the name and the 3978version of the compiler. 3979 3980@item @emph{Standard}: 3981Fortran 2008 3982 3983@item @emph{Class}: 3984Inquiry function of the module @code{ISO_FORTRAN_ENV} 3985 3986@item @emph{Syntax}: 3987@code{STR = COMPILER_VERSION()} 3988 3989@item @emph{Arguments}: 3990None. 3991 3992@item @emph{Return value}: 3993The return value is a default-kind string with system-dependent length. 3994It contains the name of the compiler and its version number. 3995 3996@item @emph{Example}: 3997@smallexample 3998 use iso_fortran_env 3999 print '(4a)', 'This file was compiled by ', & 4000 compiler_version(), ' using the options ', & 4001 compiler_options() 4002 end 4003@end smallexample 4004 4005@item @emph{See also}: 4006@ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV} 4007@end table 4008 4009 4010 4011@node COMPLEX 4012@section @code{COMPLEX} --- Complex conversion function 4013@fnindex COMPLEX 4014@cindex complex numbers, conversion to 4015@cindex conversion, to complex 4016 4017@table @asis 4018@item @emph{Description}: 4019@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted 4020to the real component and @var{Y} is converted to the imaginary 4021component. 4022 4023@item @emph{Standard}: 4024GNU extension 4025 4026@item @emph{Class}: 4027Elemental function 4028 4029@item @emph{Syntax}: 4030@code{RESULT = COMPLEX(X, Y)} 4031 4032@item @emph{Arguments}: 4033@multitable @columnfractions .15 .70 4034@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4035@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}. 4036@end multitable 4037 4038@item @emph{Return value}: 4039If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return 4040value is of default @code{COMPLEX} type. 4041 4042If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL} 4043type and one is of @code{INTEGER} type, then the return value is of 4044@code{COMPLEX} type with a kind equal to that of the @code{REAL} 4045argument with the highest precision. 4046 4047@item @emph{Example}: 4048@smallexample 4049program test_complex 4050 integer :: i = 42 4051 real :: x = 3.14 4052 print *, complex(i, x) 4053end program test_complex 4054@end smallexample 4055 4056@item @emph{See also}: 4057@ref{CMPLX} 4058@end table 4059 4060 4061 4062@node CONJG 4063@section @code{CONJG} --- Complex conjugate function 4064@fnindex CONJG 4065@fnindex DCONJG 4066@cindex complex conjugate 4067 4068@table @asis 4069@item @emph{Description}: 4070@code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)} 4071then the result is @code{(x, -y)} 4072 4073@item @emph{Standard}: 4074Fortran 77 and later, has overloads that are GNU extensions 4075 4076@item @emph{Class}: 4077Elemental function 4078 4079@item @emph{Syntax}: 4080@code{Z = CONJG(Z)} 4081 4082@item @emph{Arguments}: 4083@multitable @columnfractions .15 .70 4084@item @var{Z} @tab The type shall be @code{COMPLEX}. 4085@end multitable 4086 4087@item @emph{Return value}: 4088The return value is of type @code{COMPLEX}. 4089 4090@item @emph{Example}: 4091@smallexample 4092program test_conjg 4093 complex :: z = (2.0, 3.0) 4094 complex(8) :: dz = (2.71_8, -3.14_8) 4095 z= conjg(z) 4096 print *, z 4097 dz = dconjg(dz) 4098 print *, dz 4099end program test_conjg 4100@end smallexample 4101 4102@item @emph{Specific names}: 4103@multitable @columnfractions .20 .20 .20 .25 4104@item Name @tab Argument @tab Return type @tab Standard 4105@item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension 4106@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension 4107@end multitable 4108@end table 4109 4110 4111 4112@node COS 4113@section @code{COS} --- Cosine function 4114@fnindex COS 4115@fnindex DCOS 4116@fnindex CCOS 4117@fnindex ZCOS 4118@fnindex CDCOS 4119@cindex trigonometric function, cosine 4120@cindex cosine 4121 4122@table @asis 4123@item @emph{Description}: 4124@code{COS(X)} computes the cosine of @var{X}. 4125 4126@item @emph{Standard}: 4127Fortran 77 and later, has overloads that are GNU extensions 4128 4129@item @emph{Class}: 4130Elemental function 4131 4132@item @emph{Syntax}: 4133@code{RESULT = COS(X)} 4134 4135@item @emph{Arguments}: 4136@multitable @columnfractions .15 .70 4137@item @var{X} @tab The type shall be @code{REAL} or 4138@code{COMPLEX}. 4139@end multitable 4140 4141@item @emph{Return value}: 4142The return value is of the same type and kind as @var{X}. The real part 4143of the result is in radians. If @var{X} is of the type @code{REAL}, 4144the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}. 4145 4146@item @emph{Example}: 4147@smallexample 4148program test_cos 4149 real :: x = 0.0 4150 x = cos(x) 4151end program test_cos 4152@end smallexample 4153 4154@item @emph{Specific names}: 4155@multitable @columnfractions .20 .20 .20 .25 4156@item Name @tab Argument @tab Return type @tab Standard 4157@item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4158@item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4159@item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 4160@item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4161@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4162@end multitable 4163 4164@item @emph{See also}: 4165Inverse function: @ref{ACOS} 4166Degrees function: @ref{COSD} 4167 4168@end table 4169 4170 4171 4172@node COSD 4173@section @code{COSD} --- Cosine function, degrees 4174@fnindex COSD 4175@fnindex DCOSD 4176@fnindex CCOSD 4177@fnindex ZCOSD 4178@fnindex CDCOSD 4179@cindex trigonometric function, cosine, degrees 4180@cindex cosine, degrees 4181 4182@table @asis 4183@item @emph{Description}: 4184@code{COSD(X)} computes the cosine of @var{X} in degrees. 4185 4186This function is for compatibility only and should be avoided in favor of 4187standard constructs wherever possible. 4188 4189@item @emph{Standard}: 4190GNU Extension, enabled with @option{-fdec-math}. 4191 4192@item @emph{Class}: 4193Elemental function 4194 4195@item @emph{Syntax}: 4196@code{RESULT = COSD(X)} 4197 4198@item @emph{Arguments}: 4199@multitable @columnfractions .15 .70 4200@item @var{X} @tab The type shall be @code{REAL} or 4201@code{COMPLEX}. 4202@end multitable 4203 4204@item @emph{Return value}: 4205The return value is of the same type and kind as @var{X}. The real part 4206of the result is in degrees. If @var{X} is of the type @code{REAL}, 4207the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}. 4208 4209@item @emph{Example}: 4210@smallexample 4211program test_cosd 4212 real :: x = 0.0 4213 x = cosd(x) 4214end program test_cosd 4215@end smallexample 4216 4217@item @emph{Specific names}: 4218@multitable @columnfractions .20 .20 .20 .25 4219@item Name @tab Argument @tab Return type @tab Standard 4220@item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 4221@item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 4222@item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension 4223@item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4224@item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4225@end multitable 4226 4227@item @emph{See also}: 4228Inverse function: @ref{ACOSD} 4229Radians function: @ref{COS} 4230 4231@end table 4232 4233 4234 4235@node COSH 4236@section @code{COSH} --- Hyperbolic cosine function 4237@fnindex COSH 4238@fnindex DCOSH 4239@cindex hyperbolic cosine 4240@cindex hyperbolic function, cosine 4241@cindex cosine, hyperbolic 4242 4243@table @asis 4244@item @emph{Description}: 4245@code{COSH(X)} computes the hyperbolic cosine of @var{X}. 4246 4247@item @emph{Standard}: 4248Fortran 77 and later, for a complex argument Fortran 2008 or later 4249 4250@item @emph{Class}: 4251Elemental function 4252 4253@item @emph{Syntax}: 4254@code{X = COSH(X)} 4255 4256@item @emph{Arguments}: 4257@multitable @columnfractions .15 .70 4258@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4259@end multitable 4260 4261@item @emph{Return value}: 4262The return value has same type and kind as @var{X}. If @var{X} is 4263complex, the imaginary part of the result is in radians. If @var{X} 4264is @code{REAL}, the return value has a lower bound of one, 4265@math{\cosh (x) \geq 1}. 4266 4267@item @emph{Example}: 4268@smallexample 4269program test_cosh 4270 real(8) :: x = 1.0_8 4271 x = cosh(x) 4272end program test_cosh 4273@end smallexample 4274 4275@item @emph{Specific names}: 4276@multitable @columnfractions .20 .20 .20 .25 4277@item Name @tab Argument @tab Return type @tab Standard 4278@item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4279@item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4280@end multitable 4281 4282@item @emph{See also}: 4283Inverse function: @ref{ACOSH} 4284 4285@end table 4286 4287 4288 4289@node COTAN 4290@section @code{COTAN} --- Cotangent function 4291@fnindex COTAN 4292@fnindex DCOTAN 4293@cindex trigonometric function, cotangent 4294@cindex cotangent 4295 4296@table @asis 4297@item @emph{Description}: 4298@code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)} 4299divided by @code{SIN(x)}, or @code{1 / TAN(x)}. 4300 4301This function is for compatibility only and should be avoided in favor of 4302standard constructs wherever possible. 4303 4304@item @emph{Standard}: 4305GNU Extension, enabled with @option{-fdec-math}. 4306 4307@item @emph{Class}: 4308Elemental function 4309 4310@item @emph{Syntax}: 4311@code{RESULT = COTAN(X)} 4312 4313@item @emph{Arguments}: 4314@multitable @columnfractions .15 .70 4315@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4316@end multitable 4317 4318@item @emph{Return value}: 4319The return value has same type and kind as @var{X}, and its value is in radians. 4320 4321@item @emph{Example}: 4322@smallexample 4323program test_cotan 4324 real(8) :: x = 0.165_8 4325 x = cotan(x) 4326end program test_cotan 4327@end smallexample 4328 4329@item @emph{Specific names}: 4330@multitable @columnfractions .20 .20 .20 .25 4331@item Name @tab Argument @tab Return type @tab Standard 4332@item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 4333@item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 4334@end multitable 4335 4336@item @emph{See also}: 4337Converse function: @ref{TAN} 4338Degrees function: @ref{COTAND} 4339@end table 4340 4341 4342 4343@node COTAND 4344@section @code{COTAND} --- Cotangent function, degrees 4345@fnindex COTAND 4346@fnindex DCOTAND 4347@cindex trigonometric function, cotangent, degrees 4348@cindex cotangent, degrees 4349 4350@table @asis 4351@item @emph{Description}: 4352@code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to 4353@code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}. 4354 4355@item @emph{Standard}: 4356GNU Extension, enabled with @option{-fdec-math}. 4357 4358This function is for compatibility only and should be avoided in favor of 4359standard constructs wherever possible. 4360 4361@item @emph{Class}: 4362Elemental function 4363 4364@item @emph{Syntax}: 4365@code{RESULT = COTAND(X)} 4366 4367@item @emph{Arguments}: 4368@multitable @columnfractions .15 .70 4369@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4370@end multitable 4371 4372@item @emph{Return value}: 4373The return value has same type and kind as @var{X}, and its value is in degrees. 4374 4375@item @emph{Example}: 4376@smallexample 4377program test_cotand 4378 real(8) :: x = 0.165_8 4379 x = cotand(x) 4380end program test_cotand 4381@end smallexample 4382 4383@item @emph{Specific names}: 4384@multitable @columnfractions .20 .20 .20 .25 4385@item Name @tab Argument @tab Return type @tab Standard 4386@item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 4387@item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 4388@end multitable 4389 4390@item @emph{See also}: 4391Converse function: @ref{TAND} 4392Radians function: @ref{COTAN} 4393 4394@end table 4395 4396 4397 4398@node COUNT 4399@section @code{COUNT} --- Count function 4400@fnindex COUNT 4401@cindex array, conditionally count elements 4402@cindex array, element counting 4403@cindex array, number of elements 4404 4405@table @asis 4406@item @emph{Description}: 4407 4408Counts the number of @code{.TRUE.} elements in a logical @var{MASK}, 4409or, if the @var{DIM} argument is supplied, counts the number of 4410elements along each row of the array in the @var{DIM} direction. 4411If the array has zero size, or all of the elements of @var{MASK} are 4412@code{.FALSE.}, then the result is @code{0}. 4413 4414@item @emph{Standard}: 4415Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 4416 4417@item @emph{Class}: 4418Transformational function 4419 4420@item @emph{Syntax}: 4421@code{RESULT = COUNT(MASK [, DIM, KIND])} 4422 4423@item @emph{Arguments}: 4424@multitable @columnfractions .15 .70 4425@item @var{MASK} @tab The type shall be @code{LOGICAL}. 4426@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}. 4427@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 4428expression indicating the kind parameter of the result. 4429@end multitable 4430 4431@item @emph{Return value}: 4432The return value is of type @code{INTEGER} and of kind @var{KIND}. If 4433@var{KIND} is absent, the return value is of default integer kind. 4434If @var{DIM} is present, the result is an array with a rank one less 4435than the rank of @var{ARRAY}, and a size corresponding to the shape 4436of @var{ARRAY} with the @var{DIM} dimension removed. 4437 4438@item @emph{Example}: 4439@smallexample 4440program test_count 4441 integer, dimension(2,3) :: a, b 4442 logical, dimension(2,3) :: mask 4443 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) 4444 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /)) 4445 print '(3i3)', a(1,:) 4446 print '(3i3)', a(2,:) 4447 print * 4448 print '(3i3)', b(1,:) 4449 print '(3i3)', b(2,:) 4450 print * 4451 mask = a.ne.b 4452 print '(3l3)', mask(1,:) 4453 print '(3l3)', mask(2,:) 4454 print * 4455 print '(3i3)', count(mask) 4456 print * 4457 print '(3i3)', count(mask, 1) 4458 print * 4459 print '(3i3)', count(mask, 2) 4460end program test_count 4461@end smallexample 4462@end table 4463 4464 4465 4466@node CPU_TIME 4467@section @code{CPU_TIME} --- CPU elapsed time in seconds 4468@fnindex CPU_TIME 4469@cindex time, elapsed 4470 4471@table @asis 4472@item @emph{Description}: 4473Returns a @code{REAL} value representing the elapsed CPU time in 4474seconds. This is useful for testing segments of code to determine 4475execution time. 4476 4477If a time source is available, time will be reported with microsecond 4478resolution. If no time source is available, @var{TIME} is set to 4479@code{-1.0}. 4480 4481Note that @var{TIME} may contain a, system dependent, arbitrary offset 4482and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute 4483value is meaningless, only differences between subsequent calls to 4484this subroutine, as shown in the example below, should be used. 4485 4486 4487@item @emph{Standard}: 4488Fortran 95 and later 4489 4490@item @emph{Class}: 4491Subroutine 4492 4493@item @emph{Syntax}: 4494@code{CALL CPU_TIME(TIME)} 4495 4496@item @emph{Arguments}: 4497@multitable @columnfractions .15 .70 4498@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}. 4499@end multitable 4500 4501@item @emph{Return value}: 4502None 4503 4504@item @emph{Example}: 4505@smallexample 4506program test_cpu_time 4507 real :: start, finish 4508 call cpu_time(start) 4509 ! put code to test here 4510 call cpu_time(finish) 4511 print '("Time = ",f6.3," seconds.")',finish-start 4512end program test_cpu_time 4513@end smallexample 4514 4515@item @emph{See also}: 4516@ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME} 4517@end table 4518 4519 4520 4521@node CSHIFT 4522@section @code{CSHIFT} --- Circular shift elements of an array 4523@fnindex CSHIFT 4524@cindex array, shift circularly 4525@cindex array, permutation 4526@cindex array, rotate 4527 4528@table @asis 4529@item @emph{Description}: 4530@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of 4531@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is 4532taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the 4533range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. 4534If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted 4535by @var{SHIFT} places. If rank is greater than one, then all complete rank one 4536sections of @var{ARRAY} along the given dimension are shifted. Elements 4537shifted out one end of each rank one section are shifted back in the other end. 4538 4539@item @emph{Standard}: 4540Fortran 95 and later 4541 4542@item @emph{Class}: 4543Transformational function 4544 4545@item @emph{Syntax}: 4546@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])} 4547 4548@item @emph{Arguments}: 4549@multitable @columnfractions .15 .70 4550@item @var{ARRAY} @tab Shall be an array of any type. 4551@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 4552@item @var{DIM} @tab The type shall be @code{INTEGER}. 4553@end multitable 4554 4555@item @emph{Return value}: 4556Returns an array of same type and rank as the @var{ARRAY} argument. 4557 4558@item @emph{Example}: 4559@smallexample 4560program test_cshift 4561 integer, dimension(3,3) :: a 4562 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 4563 print '(3i3)', a(1,:) 4564 print '(3i3)', a(2,:) 4565 print '(3i3)', a(3,:) 4566 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2) 4567 print * 4568 print '(3i3)', a(1,:) 4569 print '(3i3)', a(2,:) 4570 print '(3i3)', a(3,:) 4571end program test_cshift 4572@end smallexample 4573@end table 4574 4575 4576 4577@node CTIME 4578@section @code{CTIME} --- Convert a time into a string 4579@fnindex CTIME 4580@cindex time, conversion to string 4581@cindex conversion, to string 4582 4583@table @asis 4584@item @emph{Description}: 4585@code{CTIME} converts a system time value, such as returned by 4586@ref{TIME8}, to a string. The output will be of the form @samp{Sat 4587Aug 19 18:13:14 1995}. 4588 4589This intrinsic is provided in both subroutine and function forms; however, 4590only one form can be used in any given program unit. 4591 4592@item @emph{Standard}: 4593GNU extension 4594 4595@item @emph{Class}: 4596Subroutine, function 4597 4598@item @emph{Syntax}: 4599@multitable @columnfractions .80 4600@item @code{CALL CTIME(TIME, RESULT)}. 4601@item @code{RESULT = CTIME(TIME)}. 4602@end multitable 4603 4604@item @emph{Arguments}: 4605@multitable @columnfractions .15 .70 4606@item @var{TIME} @tab The type shall be of type @code{INTEGER}. 4607@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and 4608of default kind. It is an @code{INTENT(OUT)} argument. If the length 4609of this variable is too short for the time and date string to fit 4610completely, it will be blank on procedure return. 4611@end multitable 4612 4613@item @emph{Return value}: 4614The converted date and time as a string. 4615 4616@item @emph{Example}: 4617@smallexample 4618program test_ctime 4619 integer(8) :: i 4620 character(len=30) :: date 4621 i = time8() 4622 4623 ! Do something, main part of the program 4624 4625 call ctime(i,date) 4626 print *, 'Program was started on ', date 4627end program test_ctime 4628@end smallexample 4629 4630@item @emph{See Also}: 4631@ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} 4632@end table 4633 4634 4635 4636@node DATE_AND_TIME 4637@section @code{DATE_AND_TIME} --- Date and time subroutine 4638@fnindex DATE_AND_TIME 4639@cindex date, current 4640@cindex current date 4641@cindex time, current 4642@cindex current time 4643 4644@table @asis 4645@item @emph{Description}: 4646@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and 4647time information from the real-time system clock. @var{DATE} is 4648@code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and 4649has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, 4650representing the difference with respect to Coordinated Universal Time (UTC). 4651Unavailable time and date parameters return blanks. 4652 4653@var{VALUES} is @code{INTENT(OUT)} and provides the following: 4654 4655@multitable @columnfractions .15 .30 .40 4656@item @tab @code{VALUE(1)}: @tab The year 4657@item @tab @code{VALUE(2)}: @tab The month 4658@item @tab @code{VALUE(3)}: @tab The day of the month 4659@item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes 4660@item @tab @code{VALUE(5)}: @tab The hour of the day 4661@item @tab @code{VALUE(6)}: @tab The minutes of the hour 4662@item @tab @code{VALUE(7)}: @tab The seconds of the minute 4663@item @tab @code{VALUE(8)}: @tab The milliseconds of the second 4664@end multitable 4665 4666@item @emph{Standard}: 4667Fortran 95 and later 4668 4669@item @emph{Class}: 4670Subroutine 4671 4672@item @emph{Syntax}: 4673@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])} 4674 4675@item @emph{Arguments}: 4676@multitable @columnfractions .15 .70 4677@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)} 4678or larger, and of default kind. 4679@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)} 4680or larger, and of default kind. 4681@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)} 4682or larger, and of default kind. 4683@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}. 4684@end multitable 4685 4686@item @emph{Return value}: 4687None 4688 4689@item @emph{Example}: 4690@smallexample 4691program test_time_and_date 4692 character(8) :: date 4693 character(10) :: time 4694 character(5) :: zone 4695 integer,dimension(8) :: values 4696 ! using keyword arguments 4697 call date_and_time(date,time,zone,values) 4698 call date_and_time(DATE=date,ZONE=zone) 4699 call date_and_time(TIME=time) 4700 call date_and_time(VALUES=values) 4701 print '(a,2x,a,2x,a)', date, time, zone 4702 print '(8i5)', values 4703end program test_time_and_date 4704@end smallexample 4705 4706@item @emph{See also}: 4707@ref{CPU_TIME}, @ref{SYSTEM_CLOCK} 4708@end table 4709 4710 4711 4712@node DBLE 4713@section @code{DBLE} --- Double conversion function 4714@fnindex DBLE 4715@cindex conversion, to real 4716 4717@table @asis 4718@item @emph{Description}: 4719@code{DBLE(A)} Converts @var{A} to double precision real type. 4720 4721@item @emph{Standard}: 4722Fortran 77 and later 4723 4724@item @emph{Class}: 4725Elemental function 4726 4727@item @emph{Syntax}: 4728@code{RESULT = DBLE(A)} 4729 4730@item @emph{Arguments}: 4731@multitable @columnfractions .15 .70 4732@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL}, 4733or @code{COMPLEX}. 4734@end multitable 4735 4736@item @emph{Return value}: 4737The return value is of type double precision real. 4738 4739@item @emph{Example}: 4740@smallexample 4741program test_dble 4742 real :: x = 2.18 4743 integer :: i = 5 4744 complex :: z = (2.3,1.14) 4745 print *, dble(x), dble(i), dble(z) 4746end program test_dble 4747@end smallexample 4748 4749@item @emph{See also}: 4750@ref{REAL} 4751@end table 4752 4753 4754 4755@node DCMPLX 4756@section @code{DCMPLX} --- Double complex conversion function 4757@fnindex DCMPLX 4758@cindex complex numbers, conversion to 4759@cindex conversion, to complex 4760 4761@table @asis 4762@item @emph{Description}: 4763@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is 4764converted to the real component. If @var{Y} is present it is converted to the 4765imaginary component. If @var{Y} is not present then the imaginary component is 4766set to 0.0. If @var{X} is complex then @var{Y} must not be present. 4767 4768@item @emph{Standard}: 4769GNU extension 4770 4771@item @emph{Class}: 4772Elemental function 4773 4774@item @emph{Syntax}: 4775@code{RESULT = DCMPLX(X [, Y])} 4776 4777@item @emph{Arguments}: 4778@multitable @columnfractions .15 .70 4779@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 4780or @code{COMPLEX}. 4781@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be 4782@code{INTEGER} or @code{REAL}. 4783@end multitable 4784 4785@item @emph{Return value}: 4786The return value is of type @code{COMPLEX(8)} 4787 4788@item @emph{Example}: 4789@smallexample 4790program test_dcmplx 4791 integer :: i = 42 4792 real :: x = 3.14 4793 complex :: z 4794 z = cmplx(i, x) 4795 print *, dcmplx(i) 4796 print *, dcmplx(x) 4797 print *, dcmplx(z) 4798 print *, dcmplx(x,i) 4799end program test_dcmplx 4800@end smallexample 4801@end table 4802 4803 4804@node DIGITS 4805@section @code{DIGITS} --- Significant binary digits function 4806@fnindex DIGITS 4807@cindex model representation, significant digits 4808 4809@table @asis 4810@item @emph{Description}: 4811@code{DIGITS(X)} returns the number of significant binary digits of the internal 4812model representation of @var{X}. For example, on a system using a 32-bit 4813floating point representation, a default real number would likely return 24. 4814 4815@item @emph{Standard}: 4816Fortran 95 and later 4817 4818@item @emph{Class}: 4819Inquiry function 4820 4821@item @emph{Syntax}: 4822@code{RESULT = DIGITS(X)} 4823 4824@item @emph{Arguments}: 4825@multitable @columnfractions .15 .70 4826@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4827@end multitable 4828 4829@item @emph{Return value}: 4830The return value is of type @code{INTEGER}. 4831 4832@item @emph{Example}: 4833@smallexample 4834program test_digits 4835 integer :: i = 12345 4836 real :: x = 3.143 4837 real(8) :: y = 2.33 4838 print *, digits(i) 4839 print *, digits(x) 4840 print *, digits(y) 4841end program test_digits 4842@end smallexample 4843@end table 4844 4845 4846 4847@node DIM 4848@section @code{DIM} --- Positive difference 4849@fnindex DIM 4850@fnindex IDIM 4851@fnindex DDIM 4852@cindex positive difference 4853 4854@table @asis 4855@item @emph{Description}: 4856@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive; 4857otherwise returns zero. 4858 4859@item @emph{Standard}: 4860Fortran 77 and later 4861 4862@item @emph{Class}: 4863Elemental function 4864 4865@item @emph{Syntax}: 4866@code{RESULT = DIM(X, Y)} 4867 4868@item @emph{Arguments}: 4869@multitable @columnfractions .15 .70 4870@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL} 4871@item @var{Y} @tab The type shall be the same type and kind as @var{X}. 4872@end multitable 4873 4874@item @emph{Return value}: 4875The return value is of type @code{INTEGER} or @code{REAL}. 4876 4877@item @emph{Example}: 4878@smallexample 4879program test_dim 4880 integer :: i 4881 real(8) :: x 4882 i = dim(4, 15) 4883 x = dim(4.345_8, 2.111_8) 4884 print *, i 4885 print *, x 4886end program test_dim 4887@end smallexample 4888 4889@item @emph{Specific names}: 4890@multitable @columnfractions .20 .20 .20 .25 4891@item Name @tab Argument @tab Return type @tab Standard 4892@item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 4893@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later 4894@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 4895@end multitable 4896@end table 4897 4898 4899 4900@node DOT_PRODUCT 4901@section @code{DOT_PRODUCT} --- Dot product function 4902@fnindex DOT_PRODUCT 4903@cindex dot product 4904@cindex vector product 4905@cindex product, vector 4906 4907@table @asis 4908@item @emph{Description}: 4909@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication 4910of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be 4911either numeric or logical and must be arrays of rank one and of equal size. If 4912the vectors are @code{INTEGER} or @code{REAL}, the result is 4913@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result 4914is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL}, 4915the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}. 4916 4917@item @emph{Standard}: 4918Fortran 95 and later 4919 4920@item @emph{Class}: 4921Transformational function 4922 4923@item @emph{Syntax}: 4924@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)} 4925 4926@item @emph{Arguments}: 4927@multitable @columnfractions .15 .70 4928@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1. 4929@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. 4930@end multitable 4931 4932@item @emph{Return value}: 4933If the arguments are numeric, the return value is a scalar of numeric type, 4934@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are 4935@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}. 4936 4937@item @emph{Example}: 4938@smallexample 4939program test_dot_prod 4940 integer, dimension(3) :: a, b 4941 a = (/ 1, 2, 3 /) 4942 b = (/ 4, 5, 6 /) 4943 print '(3i3)', a 4944 print * 4945 print '(3i3)', b 4946 print * 4947 print *, dot_product(a,b) 4948end program test_dot_prod 4949@end smallexample 4950@end table 4951 4952 4953 4954@node DPROD 4955@section @code{DPROD} --- Double product function 4956@fnindex DPROD 4957@cindex product, double-precision 4958 4959@table @asis 4960@item @emph{Description}: 4961@code{DPROD(X,Y)} returns the product @code{X*Y}. 4962 4963@item @emph{Standard}: 4964Fortran 77 and later 4965 4966@item @emph{Class}: 4967Elemental function 4968 4969@item @emph{Syntax}: 4970@code{RESULT = DPROD(X, Y)} 4971 4972@item @emph{Arguments}: 4973@multitable @columnfractions .15 .70 4974@item @var{X} @tab The type shall be @code{REAL}. 4975@item @var{Y} @tab The type shall be @code{REAL}. 4976@end multitable 4977 4978@item @emph{Return value}: 4979The return value is of type @code{REAL(8)}. 4980 4981@item @emph{Example}: 4982@smallexample 4983program test_dprod 4984 real :: x = 5.2 4985 real :: y = 2.3 4986 real(8) :: d 4987 d = dprod(x,y) 4988 print *, d 4989end program test_dprod 4990@end smallexample 4991 4992@item @emph{Specific names}: 4993@multitable @columnfractions .20 .20 .20 .25 4994@item Name @tab Argument @tab Return type @tab Standard 4995@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 4996@end multitable 4997 4998@end table 4999 5000 5001@node DREAL 5002@section @code{DREAL} --- Double real part function 5003@fnindex DREAL 5004@cindex complex numbers, real part 5005 5006@table @asis 5007@item @emph{Description}: 5008@code{DREAL(Z)} returns the real part of complex variable @var{Z}. 5009 5010@item @emph{Standard}: 5011GNU extension 5012 5013@item @emph{Class}: 5014Elemental function 5015 5016@item @emph{Syntax}: 5017@code{RESULT = DREAL(A)} 5018 5019@item @emph{Arguments}: 5020@multitable @columnfractions .15 .70 5021@item @var{A} @tab The type shall be @code{COMPLEX(8)}. 5022@end multitable 5023 5024@item @emph{Return value}: 5025The return value is of type @code{REAL(8)}. 5026 5027@item @emph{Example}: 5028@smallexample 5029program test_dreal 5030 complex(8) :: z = (1.3_8,7.2_8) 5031 print *, dreal(z) 5032end program test_dreal 5033@end smallexample 5034 5035@item @emph{See also}: 5036@ref{AIMAG} 5037 5038@end table 5039 5040 5041 5042@node DSHIFTL 5043@section @code{DSHIFTL} --- Combined left shift 5044@fnindex DSHIFTL 5045@cindex left shift, combined 5046@cindex shift, left 5047 5048@table @asis 5049@item @emph{Description}: 5050@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5051rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT} 5052bits of @var{J}, and the remaining bits are the rightmost bits of 5053@var{I}. 5054 5055@item @emph{Standard}: 5056Fortran 2008 and later 5057 5058@item @emph{Class}: 5059Elemental function 5060 5061@item @emph{Syntax}: 5062@code{RESULT = DSHIFTL(I, J, SHIFT)} 5063 5064@item @emph{Arguments}: 5065@multitable @columnfractions .15 .70 5066@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5067@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5068If both @var{I} and @var{J} have integer type, then they shall have 5069the same kind type parameter. @var{I} and @var{J} shall not both be 5070BOZ constants. 5071@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5072be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5073shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5074@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5075@end multitable 5076 5077@item @emph{Return value}: 5078If either @var{I} or @var{J} is a BOZ constant, it is first converted 5079as if by the intrinsic function @code{INT} to an integer type with the 5080kind type parameter of the other. 5081 5082@item @emph{See also}: 5083@ref{DSHIFTR} 5084@end table 5085 5086 5087@node DSHIFTR 5088@section @code{DSHIFTR} --- Combined right shift 5089@fnindex DSHIFTR 5090@cindex right shift, combined 5091@cindex shift, right 5092 5093@table @asis 5094@item @emph{Description}: 5095@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5096leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT} 5097bits of @var{I}, and the remaining bits are the leftmost bits of 5098@var{J}. 5099 5100@item @emph{Standard}: 5101Fortran 2008 and later 5102 5103@item @emph{Class}: 5104Elemental function 5105 5106@item @emph{Syntax}: 5107@code{RESULT = DSHIFTR(I, J, SHIFT)} 5108 5109@item @emph{Arguments}: 5110@multitable @columnfractions .15 .70 5111@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5112@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5113If both @var{I} and @var{J} have integer type, then they shall have 5114the same kind type parameter. @var{I} and @var{J} shall not both be 5115BOZ constants. 5116@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5117be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5118shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5119@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5120@end multitable 5121 5122@item @emph{Return value}: 5123If either @var{I} or @var{J} is a BOZ constant, it is first converted 5124as if by the intrinsic function @code{INT} to an integer type with the 5125kind type parameter of the other. 5126 5127@item @emph{See also}: 5128@ref{DSHIFTL} 5129@end table 5130 5131 5132@node DTIME 5133@section @code{DTIME} --- Execution time subroutine (or function) 5134@fnindex DTIME 5135@cindex time, elapsed 5136@cindex elapsed time 5137 5138@table @asis 5139@item @emph{Description}: 5140@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime 5141since the start of the process's execution in @var{TIME}. @var{VALUES} 5142returns the user and system components of this time in @code{VALUES(1)} and 5143@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + 5144VALUES(2)}. 5145 5146Subsequent invocations of @code{DTIME} return values accumulated since the 5147previous invocation. 5148 5149On some systems, the underlying timings are represented using types with 5150sufficiently small limits that overflows (wrap around) are possible, such as 515132-bit types. Therefore, the values returned by this intrinsic might be, or 5152become, negative, or numerically less than previous values, during a single 5153run of the compiled program. 5154 5155Please note, that this implementation is thread safe if used within OpenMP 5156directives, i.e., its state will be consistent while called from multiple 5157threads. However, if @code{DTIME} is called from multiple threads, the result 5158is still the time since the last invocation. This may not give the intended 5159results. If possible, use @code{CPU_TIME} instead. 5160 5161This intrinsic is provided in both subroutine and function forms; however, 5162only one form can be used in any given program unit. 5163 5164@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5165 5166@multitable @columnfractions .15 .30 .40 5167@item @tab @code{VALUES(1)}: @tab User time in seconds. 5168@item @tab @code{VALUES(2)}: @tab System time in seconds. 5169@item @tab @code{TIME}: @tab Run time since start in seconds. 5170@end multitable 5171 5172@item @emph{Standard}: 5173GNU extension 5174 5175@item @emph{Class}: 5176Subroutine, function 5177 5178@item @emph{Syntax}: 5179@multitable @columnfractions .80 5180@item @code{CALL DTIME(VALUES, TIME)}. 5181@item @code{TIME = DTIME(VALUES)}, (not recommended). 5182@end multitable 5183 5184@item @emph{Arguments}: 5185@multitable @columnfractions .15 .70 5186@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5187@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5188@end multitable 5189 5190@item @emph{Return value}: 5191Elapsed time in seconds since the last invocation or since the start of program 5192execution if not called before. 5193 5194@item @emph{Example}: 5195@smallexample 5196program test_dtime 5197 integer(8) :: i, j 5198 real, dimension(2) :: tarray 5199 real :: result 5200 call dtime(tarray, result) 5201 print *, result 5202 print *, tarray(1) 5203 print *, tarray(2) 5204 do i=1,100000000 ! Just a delay 5205 j = i * i - i 5206 end do 5207 call dtime(tarray, result) 5208 print *, result 5209 print *, tarray(1) 5210 print *, tarray(2) 5211end program test_dtime 5212@end smallexample 5213 5214@item @emph{See also}: 5215@ref{CPU_TIME} 5216 5217@end table 5218 5219 5220 5221@node EOSHIFT 5222@section @code{EOSHIFT} --- End-off shift elements of an array 5223@fnindex EOSHIFT 5224@cindex array, shift 5225 5226@table @asis 5227@item @emph{Description}: 5228@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on 5229elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is 5230omitted it is taken to be @code{1}. @var{DIM} is a scalar of type 5231@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the 5232rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of 5233@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, 5234then all complete rank one sections of @var{ARRAY} along the given dimension are 5235shifted. Elements shifted out one end of each rank one section are dropped. If 5236@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY} 5237is copied back in the other end. If @var{BOUNDARY} is not present then the 5238following are copied in depending on the type of @var{ARRAY}. 5239 5240@multitable @columnfractions .15 .80 5241@item @emph{Array Type} @tab @emph{Boundary Value} 5242@item Numeric @tab 0 of the type and kind of @var{ARRAY}. 5243@item Logical @tab @code{.FALSE.}. 5244@item Character(@var{len}) @tab @var{len} blanks. 5245@end multitable 5246 5247@item @emph{Standard}: 5248Fortran 95 and later 5249 5250@item @emph{Class}: 5251Transformational function 5252 5253@item @emph{Syntax}: 5254@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])} 5255 5256@item @emph{Arguments}: 5257@multitable @columnfractions .15 .70 5258@item @var{ARRAY} @tab May be any type, not scalar. 5259@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 5260@item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 5261@item @var{DIM} @tab The type shall be @code{INTEGER}. 5262@end multitable 5263 5264@item @emph{Return value}: 5265Returns an array of same type and rank as the @var{ARRAY} argument. 5266 5267@item @emph{Example}: 5268@smallexample 5269program test_eoshift 5270 integer, dimension(3,3) :: a 5271 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 5272 print '(3i3)', a(1,:) 5273 print '(3i3)', a(2,:) 5274 print '(3i3)', a(3,:) 5275 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) 5276 print * 5277 print '(3i3)', a(1,:) 5278 print '(3i3)', a(2,:) 5279 print '(3i3)', a(3,:) 5280end program test_eoshift 5281@end smallexample 5282@end table 5283 5284 5285 5286@node EPSILON 5287@section @code{EPSILON} --- Epsilon function 5288@fnindex EPSILON 5289@cindex model representation, epsilon 5290 5291@table @asis 5292@item @emph{Description}: 5293@code{EPSILON(X)} returns the smallest number @var{E} of the same kind 5294as @var{X} such that @math{1 + E > 1}. 5295 5296@item @emph{Standard}: 5297Fortran 95 and later 5298 5299@item @emph{Class}: 5300Inquiry function 5301 5302@item @emph{Syntax}: 5303@code{RESULT = EPSILON(X)} 5304 5305@item @emph{Arguments}: 5306@multitable @columnfractions .15 .70 5307@item @var{X} @tab The type shall be @code{REAL}. 5308@end multitable 5309 5310@item @emph{Return value}: 5311The return value is of same type as the argument. 5312 5313@item @emph{Example}: 5314@smallexample 5315program test_epsilon 5316 real :: x = 3.143 5317 real(8) :: y = 2.33 5318 print *, EPSILON(x) 5319 print *, EPSILON(y) 5320end program test_epsilon 5321@end smallexample 5322@end table 5323 5324 5325 5326@node ERF 5327@section @code{ERF} --- Error function 5328@fnindex ERF 5329@cindex error function 5330 5331@table @asis 5332@item @emph{Description}: 5333@code{ERF(X)} computes the error function of @var{X}. 5334 5335@item @emph{Standard}: 5336Fortran 2008 and later 5337 5338@item @emph{Class}: 5339Elemental function 5340 5341@item @emph{Syntax}: 5342@code{RESULT = ERF(X)} 5343 5344@item @emph{Arguments}: 5345@multitable @columnfractions .15 .70 5346@item @var{X} @tab The type shall be @code{REAL}. 5347@end multitable 5348 5349@item @emph{Return value}: 5350The return value is of type @code{REAL}, of the same kind as 5351@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }. 5352 5353@item @emph{Example}: 5354@smallexample 5355program test_erf 5356 real(8) :: x = 0.17_8 5357 x = erf(x) 5358end program test_erf 5359@end smallexample 5360 5361@item @emph{Specific names}: 5362@multitable @columnfractions .20 .20 .20 .25 5363@item Name @tab Argument @tab Return type @tab Standard 5364@item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5365@end multitable 5366@end table 5367 5368 5369 5370@node ERFC 5371@section @code{ERFC} --- Error function 5372@fnindex ERFC 5373@cindex error function, complementary 5374 5375@table @asis 5376@item @emph{Description}: 5377@code{ERFC(X)} computes the complementary error function of @var{X}. 5378 5379@item @emph{Standard}: 5380Fortran 2008 and later 5381 5382@item @emph{Class}: 5383Elemental function 5384 5385@item @emph{Syntax}: 5386@code{RESULT = ERFC(X)} 5387 5388@item @emph{Arguments}: 5389@multitable @columnfractions .15 .70 5390@item @var{X} @tab The type shall be @code{REAL}. 5391@end multitable 5392 5393@item @emph{Return value}: 5394The return value is of type @code{REAL} and of the same kind as @var{X}. 5395It lies in the range @math{ 0 \leq erfc (x) \leq 2 }. 5396 5397@item @emph{Example}: 5398@smallexample 5399program test_erfc 5400 real(8) :: x = 0.17_8 5401 x = erfc(x) 5402end program test_erfc 5403@end smallexample 5404 5405@item @emph{Specific names}: 5406@multitable @columnfractions .20 .20 .20 .25 5407@item Name @tab Argument @tab Return type @tab Standard 5408@item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5409@end multitable 5410@end table 5411 5412 5413 5414@node ERFC_SCALED 5415@section @code{ERFC_SCALED} --- Error function 5416@fnindex ERFC_SCALED 5417@cindex error function, complementary, exponentially-scaled 5418 5419@table @asis 5420@item @emph{Description}: 5421@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary 5422error function of @var{X}. 5423 5424@item @emph{Standard}: 5425Fortran 2008 and later 5426 5427@item @emph{Class}: 5428Elemental function 5429 5430@item @emph{Syntax}: 5431@code{RESULT = ERFC_SCALED(X)} 5432 5433@item @emph{Arguments}: 5434@multitable @columnfractions .15 .70 5435@item @var{X} @tab The type shall be @code{REAL}. 5436@end multitable 5437 5438@item @emph{Return value}: 5439The return value is of type @code{REAL} and of the same kind as @var{X}. 5440 5441@item @emph{Example}: 5442@smallexample 5443program test_erfc_scaled 5444 real(8) :: x = 0.17_8 5445 x = erfc_scaled(x) 5446end program test_erfc_scaled 5447@end smallexample 5448@end table 5449 5450 5451 5452@node ETIME 5453@section @code{ETIME} --- Execution time subroutine (or function) 5454@fnindex ETIME 5455@cindex time, elapsed 5456 5457@table @asis 5458@item @emph{Description}: 5459@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime 5460since the start of the process's execution in @var{TIME}. @var{VALUES} 5461returns the user and system components of this time in @code{VALUES(1)} and 5462@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. 5463 5464On some systems, the underlying timings are represented using types with 5465sufficiently small limits that overflows (wrap around) are possible, such as 546632-bit types. Therefore, the values returned by this intrinsic might be, or 5467become, negative, or numerically less than previous values, during a single 5468run of the compiled program. 5469 5470This intrinsic is provided in both subroutine and function forms; however, 5471only one form can be used in any given program unit. 5472 5473@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5474 5475@multitable @columnfractions .15 .30 .60 5476@item @tab @code{VALUES(1)}: @tab User time in seconds. 5477@item @tab @code{VALUES(2)}: @tab System time in seconds. 5478@item @tab @code{TIME}: @tab Run time since start in seconds. 5479@end multitable 5480 5481@item @emph{Standard}: 5482GNU extension 5483 5484@item @emph{Class}: 5485Subroutine, function 5486 5487@item @emph{Syntax}: 5488@multitable @columnfractions .80 5489@item @code{CALL ETIME(VALUES, TIME)}. 5490@item @code{TIME = ETIME(VALUES)}, (not recommended). 5491@end multitable 5492 5493@item @emph{Arguments}: 5494@multitable @columnfractions .15 .70 5495@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5496@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5497@end multitable 5498 5499@item @emph{Return value}: 5500Elapsed time in seconds since the start of program execution. 5501 5502@item @emph{Example}: 5503@smallexample 5504program test_etime 5505 integer(8) :: i, j 5506 real, dimension(2) :: tarray 5507 real :: result 5508 call ETIME(tarray, result) 5509 print *, result 5510 print *, tarray(1) 5511 print *, tarray(2) 5512 do i=1,100000000 ! Just a delay 5513 j = i * i - i 5514 end do 5515 call ETIME(tarray, result) 5516 print *, result 5517 print *, tarray(1) 5518 print *, tarray(2) 5519end program test_etime 5520@end smallexample 5521 5522@item @emph{See also}: 5523@ref{CPU_TIME} 5524 5525@end table 5526 5527 5528 5529@node EVENT_QUERY 5530@section @code{EVENT_QUERY} --- Query whether a coarray event has occurred 5531@fnindex EVENT_QUERY 5532@cindex Events, EVENT_QUERY 5533 5534@table @asis 5535@item @emph{Description}: 5536@code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been 5537posted to the @var{EVENT} variable and not yet been removed by calling 5538@code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful, 5539it is assigned the value 0. If it is present and the invocation has failed, 5540it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}. 5541 5542@item @emph{Standard}: 5543TS 18508 or later 5544 5545@item @emph{Class}: 5546 subroutine 5547 5548@item @emph{Syntax}: 5549@code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])} 5550 5551@item @emph{Arguments}: 5552@multitable @columnfractions .15 .70 5553@item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE}, 5554defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed. 5555@item @var{COUNT} @tab (intent(out))Scalar integer with at least the 5556precision of default integer. 5557@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 5558@end multitable 5559 5560@item @emph{Example}: 5561@smallexample 5562program atomic 5563 use iso_fortran_env 5564 implicit none 5565 type(event_type) :: event_value_has_been_set[*] 5566 integer :: cnt 5567 if (this_image() == 1) then 5568 call event_query (event_value_has_been_set, cnt) 5569 if (cnt > 0) write(*,*) "Value has been set" 5570 elseif (this_image() == 2) then 5571 event post (event_value_has_been_set[1]) 5572 end if 5573end program atomic 5574@end smallexample 5575 5576@end table 5577 5578 5579 5580@node EXECUTE_COMMAND_LINE 5581@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command 5582@fnindex EXECUTE_COMMAND_LINE 5583@cindex system, system call 5584@cindex command line 5585 5586@table @asis 5587@item @emph{Description}: 5588@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or 5589asynchronously. 5590 5591The @code{COMMAND} argument is passed to the shell and executed, using 5592the C library's @code{system} call. (The shell is @code{sh} on Unix 5593systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present 5594and has the value false, the execution of the command is asynchronous 5595if the system supports it; otherwise, the command is executed 5596synchronously. 5597 5598The three last arguments allow the user to get status information. After 5599synchronous execution, @code{EXITSTAT} contains the integer exit code of 5600the command, as returned by @code{system}. @code{CMDSTAT} is set to zero 5601if the command line was executed (whatever its exit status was). 5602@code{CMDMSG} is assigned an error message if an error has occurred. 5603 5604Note that the @code{system} function need not be thread-safe. It is 5605the responsibility of the user to ensure that @code{system} is not 5606called concurrently. 5607 5608@item @emph{Standard}: 5609Fortran 2008 and later 5610 5611@item @emph{Class}: 5612Subroutine 5613 5614@item @emph{Syntax}: 5615@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])} 5616 5617@item @emph{Arguments}: 5618@multitable @columnfractions .15 .70 5619@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar. 5620@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar. 5621@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5622default kind. 5623@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5624default kind. 5625@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the 5626default kind. 5627@end multitable 5628 5629@item @emph{Example}: 5630@smallexample 5631program test_exec 5632 integer :: i 5633 5634 call execute_command_line ("external_prog.exe", exitstat=i) 5635 print *, "Exit status of external_prog.exe was ", i 5636 5637 call execute_command_line ("reindex_files.exe", wait=.false.) 5638 print *, "Now reindexing files in the background" 5639 5640end program test_exec 5641@end smallexample 5642 5643 5644@item @emph{Note}: 5645 5646Because this intrinsic is implemented in terms of the @code{system} 5647function call, its behavior with respect to signaling is processor 5648dependent. In particular, on POSIX-compliant systems, the SIGINT and 5649SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As 5650such, if the parent process is terminated, the child process might not be 5651terminated alongside. 5652 5653 5654@item @emph{See also}: 5655@ref{SYSTEM} 5656@end table 5657 5658 5659 5660@node EXIT 5661@section @code{EXIT} --- Exit the program with status. 5662@fnindex EXIT 5663@cindex program termination 5664@cindex terminate program 5665 5666@table @asis 5667@item @emph{Description}: 5668@code{EXIT} causes immediate termination of the program with status. If status 5669is omitted it returns the canonical @emph{success} for the system. All Fortran 5670I/O units are closed. 5671 5672@item @emph{Standard}: 5673GNU extension 5674 5675@item @emph{Class}: 5676Subroutine 5677 5678@item @emph{Syntax}: 5679@code{CALL EXIT([STATUS])} 5680 5681@item @emph{Arguments}: 5682@multitable @columnfractions .15 .70 5683@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind. 5684@end multitable 5685 5686@item @emph{Return value}: 5687@code{STATUS} is passed to the parent process on exit. 5688 5689@item @emph{Example}: 5690@smallexample 5691program test_exit 5692 integer :: STATUS = 0 5693 print *, 'This program is going to exit.' 5694 call EXIT(STATUS) 5695end program test_exit 5696@end smallexample 5697 5698@item @emph{See also}: 5699@ref{ABORT}, @ref{KILL} 5700@end table 5701 5702 5703 5704@node EXP 5705@section @code{EXP} --- Exponential function 5706@fnindex EXP 5707@fnindex DEXP 5708@fnindex CEXP 5709@fnindex ZEXP 5710@fnindex CDEXP 5711@cindex exponential function 5712@cindex logarithm function, inverse 5713 5714@table @asis 5715@item @emph{Description}: 5716@code{EXP(X)} computes the base @math{e} exponential of @var{X}. 5717 5718@item @emph{Standard}: 5719Fortran 77 and later, has overloads that are GNU extensions 5720 5721@item @emph{Class}: 5722Elemental function 5723 5724@item @emph{Syntax}: 5725@code{RESULT = EXP(X)} 5726 5727@item @emph{Arguments}: 5728@multitable @columnfractions .15 .70 5729@item @var{X} @tab The type shall be @code{REAL} or 5730@code{COMPLEX}. 5731@end multitable 5732 5733@item @emph{Return value}: 5734The return value has same type and kind as @var{X}. 5735 5736@item @emph{Example}: 5737@smallexample 5738program test_exp 5739 real :: x = 1.0 5740 x = exp(x) 5741end program test_exp 5742@end smallexample 5743 5744@item @emph{Specific names}: 5745@multitable @columnfractions .20 .20 .20 .25 5746@item Name @tab Argument @tab Return type @tab Standard 5747@item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 5748@item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 5749@item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 5750@item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5751@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5752@end multitable 5753@end table 5754 5755 5756 5757@node EXPONENT 5758@section @code{EXPONENT} --- Exponent function 5759@fnindex EXPONENT 5760@cindex real number, exponent 5761@cindex floating point, exponent 5762 5763@table @asis 5764@item @emph{Description}: 5765@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X} 5766is zero the value returned is zero. 5767 5768@item @emph{Standard}: 5769Fortran 95 and later 5770 5771@item @emph{Class}: 5772Elemental function 5773 5774@item @emph{Syntax}: 5775@code{RESULT = EXPONENT(X)} 5776 5777@item @emph{Arguments}: 5778@multitable @columnfractions .15 .70 5779@item @var{X} @tab The type shall be @code{REAL}. 5780@end multitable 5781 5782@item @emph{Return value}: 5783The return value is of type default @code{INTEGER}. 5784 5785@item @emph{Example}: 5786@smallexample 5787program test_exponent 5788 real :: x = 1.0 5789 integer :: i 5790 i = exponent(x) 5791 print *, i 5792 print *, exponent(0.0) 5793end program test_exponent 5794@end smallexample 5795@end table 5796 5797 5798 5799@node EXTENDS_TYPE_OF 5800@section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension 5801@fnindex EXTENDS_TYPE_OF 5802 5803@table @asis 5804@item @emph{Description}: 5805Query dynamic type for extension. 5806 5807@item @emph{Standard}: 5808Fortran 2003 and later 5809 5810@item @emph{Class}: 5811Inquiry function 5812 5813@item @emph{Syntax}: 5814@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)} 5815 5816@item @emph{Arguments}: 5817@multitable @columnfractions .15 .70 5818@item @var{A} @tab Shall be an object of extensible declared type or 5819unlimited polymorphic. 5820@item @var{MOLD} @tab Shall be an object of extensible declared type or 5821unlimited polymorphic. 5822@end multitable 5823 5824@item @emph{Return value}: 5825The return value is a scalar of type default logical. It is true if and only if 5826the dynamic type of A is an extension type of the dynamic type of MOLD. 5827 5828 5829@item @emph{See also}: 5830@ref{SAME_TYPE_AS} 5831@end table 5832 5833 5834 5835@node FDATE 5836@section @code{FDATE} --- Get the current time as a string 5837@fnindex FDATE 5838@cindex time, current 5839@cindex current time 5840@cindex date, current 5841@cindex current date 5842 5843@table @asis 5844@item @emph{Description}: 5845@code{FDATE(DATE)} returns the current date (using the same format as 5846@ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE, 5847TIME())}. 5848 5849This intrinsic is provided in both subroutine and function forms; however, 5850only one form can be used in any given program unit. 5851 5852@item @emph{Standard}: 5853GNU extension 5854 5855@item @emph{Class}: 5856Subroutine, function 5857 5858@item @emph{Syntax}: 5859@multitable @columnfractions .80 5860@item @code{CALL FDATE(DATE)}. 5861@item @code{DATE = FDATE()}. 5862@end multitable 5863 5864@item @emph{Arguments}: 5865@multitable @columnfractions .15 .70 5866@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the 5867default kind. It is an @code{INTENT(OUT)} argument. If the length of 5868this variable is too short for the date and time string to fit 5869completely, it will be blank on procedure return. 5870@end multitable 5871 5872@item @emph{Return value}: 5873The current date and time as a string. 5874 5875@item @emph{Example}: 5876@smallexample 5877program test_fdate 5878 integer(8) :: i, j 5879 character(len=30) :: date 5880 call fdate(date) 5881 print *, 'Program started on ', date 5882 do i = 1, 100000000 ! Just a delay 5883 j = i * i - i 5884 end do 5885 call fdate(date) 5886 print *, 'Program ended on ', date 5887end program test_fdate 5888@end smallexample 5889 5890@item @emph{See also}: 5891@ref{DATE_AND_TIME}, @ref{CTIME} 5892@end table 5893 5894 5895@node FGET 5896@section @code{FGET} --- Read a single character in stream mode from stdin 5897@fnindex FGET 5898@cindex read character, stream mode 5899@cindex stream mode, read character 5900@cindex file operation, read character 5901 5902@table @asis 5903@item @emph{Description}: 5904Read a single character in stream mode from stdin by bypassing normal 5905formatted output. Stream I/O should not be mixed with normal record-oriented 5906(formatted or unformatted) I/O on the same unit; the results are unpredictable. 5907 5908This intrinsic is provided in both subroutine and function forms; however, 5909only one form can be used in any given program unit. 5910 5911Note that the @code{FGET} intrinsic is provided for backwards compatibility with 5912@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 5913Programmers should consider the use of new stream IO feature in new code 5914for future portability. See also @ref{Fortran 2003 status}. 5915 5916@item @emph{Standard}: 5917GNU extension 5918 5919@item @emph{Class}: 5920Subroutine, function 5921 5922@item @emph{Syntax}: 5923@multitable @columnfractions .80 5924@item @code{CALL FGET(C [, STATUS])} 5925@item @code{STATUS = FGET(C)} 5926@end multitable 5927 5928@item @emph{Arguments}: 5929@multitable @columnfractions .15 .70 5930@item @var{C} @tab The type shall be @code{CHARACTER} and of default 5931kind. 5932@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 5933Returns 0 on success, -1 on end-of-file, and a system specific positive 5934error code otherwise. 5935@end multitable 5936 5937@item @emph{Example}: 5938@smallexample 5939PROGRAM test_fget 5940 INTEGER, PARAMETER :: strlen = 100 5941 INTEGER :: status, i = 1 5942 CHARACTER(len=strlen) :: str = "" 5943 5944 WRITE (*,*) 'Enter text:' 5945 DO 5946 CALL fget(str(i:i), status) 5947 if (status /= 0 .OR. i > strlen) exit 5948 i = i + 1 5949 END DO 5950 WRITE (*,*) TRIM(str) 5951END PROGRAM 5952@end smallexample 5953 5954@item @emph{See also}: 5955@ref{FGETC}, @ref{FPUT}, @ref{FPUTC} 5956@end table 5957 5958 5959 5960@node FGETC 5961@section @code{FGETC} --- Read a single character in stream mode 5962@fnindex FGETC 5963@cindex read character, stream mode 5964@cindex stream mode, read character 5965@cindex file operation, read character 5966 5967@table @asis 5968@item @emph{Description}: 5969Read a single character in stream mode by bypassing normal formatted output. 5970Stream I/O should not be mixed with normal record-oriented (formatted or 5971unformatted) I/O on the same unit; the results are unpredictable. 5972 5973This intrinsic is provided in both subroutine and function forms; however, 5974only one form can be used in any given program unit. 5975 5976Note that the @code{FGET} intrinsic is provided for backwards compatibility 5977with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 5978Programmers should consider the use of new stream IO feature in new code 5979for future portability. See also @ref{Fortran 2003 status}. 5980 5981@item @emph{Standard}: 5982GNU extension 5983 5984@item @emph{Class}: 5985Subroutine, function 5986 5987@item @emph{Syntax}: 5988@multitable @columnfractions .80 5989@item @code{CALL FGETC(UNIT, C [, STATUS])} 5990@item @code{STATUS = FGETC(UNIT, C)} 5991@end multitable 5992 5993@item @emph{Arguments}: 5994@multitable @columnfractions .15 .70 5995@item @var{UNIT} @tab The type shall be @code{INTEGER}. 5996@item @var{C} @tab The type shall be @code{CHARACTER} and of default 5997kind. 5998@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 5999Returns 0 on success, -1 on end-of-file and a system specific positive 6000error code otherwise. 6001@end multitable 6002 6003@item @emph{Example}: 6004@smallexample 6005PROGRAM test_fgetc 6006 INTEGER :: fd = 42, status 6007 CHARACTER :: c 6008 6009 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD") 6010 DO 6011 CALL fgetc(fd, c, status) 6012 IF (status /= 0) EXIT 6013 call fput(c) 6014 END DO 6015 CLOSE(UNIT=fd) 6016END PROGRAM 6017@end smallexample 6018 6019@item @emph{See also}: 6020@ref{FGET}, @ref{FPUT}, @ref{FPUTC} 6021@end table 6022 6023 6024 6025@node FLOOR 6026@section @code{FLOOR} --- Integer floor function 6027@fnindex FLOOR 6028@cindex floor 6029@cindex rounding, floor 6030 6031@table @asis 6032@item @emph{Description}: 6033@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}. 6034 6035@item @emph{Standard}: 6036Fortran 95 and later 6037 6038@item @emph{Class}: 6039Elemental function 6040 6041@item @emph{Syntax}: 6042@code{RESULT = FLOOR(A [, KIND])} 6043 6044@item @emph{Arguments}: 6045@multitable @columnfractions .15 .70 6046@item @var{A} @tab The type shall be @code{REAL}. 6047@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6048expression indicating the kind parameter of the result. 6049@end multitable 6050 6051@item @emph{Return value}: 6052The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 6053and of default-kind @code{INTEGER} otherwise. 6054 6055@item @emph{Example}: 6056@smallexample 6057program test_floor 6058 real :: x = 63.29 6059 real :: y = -63.59 6060 print *, floor(x) ! returns 63 6061 print *, floor(y) ! returns -64 6062end program test_floor 6063@end smallexample 6064 6065@item @emph{See also}: 6066@ref{CEILING}, @ref{NINT} 6067 6068@end table 6069 6070 6071 6072@node FLUSH 6073@section @code{FLUSH} --- Flush I/O unit(s) 6074@fnindex FLUSH 6075@cindex file operation, flush 6076 6077@table @asis 6078@item @emph{Description}: 6079Flushes Fortran unit(s) currently open for output. Without the optional 6080argument, all units are flushed, otherwise just the unit specified. 6081 6082@item @emph{Standard}: 6083GNU extension 6084 6085@item @emph{Class}: 6086Subroutine 6087 6088@item @emph{Syntax}: 6089@code{CALL FLUSH(UNIT)} 6090 6091@item @emph{Arguments}: 6092@multitable @columnfractions .15 .70 6093@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}. 6094@end multitable 6095 6096@item @emph{Note}: 6097Beginning with the Fortran 2003 standard, there is a @code{FLUSH} 6098statement that should be preferred over the @code{FLUSH} intrinsic. 6099 6100The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement 6101have identical effect: they flush the runtime library's I/O buffer so 6102that the data becomes visible to other processes. This does not guarantee 6103that the data is committed to disk. 6104 6105On POSIX systems, you can request that all data is transferred to the 6106storage device by calling the @code{fsync} function, with the POSIX file 6107descriptor of the I/O unit as argument (retrieved with GNU intrinsic 6108@code{FNUM}). The following example shows how: 6109 6110@smallexample 6111 ! Declare the interface for POSIX fsync function 6112 interface 6113 function fsync (fd) bind(c,name="fsync") 6114 use iso_c_binding, only: c_int 6115 integer(c_int), value :: fd 6116 integer(c_int) :: fsync 6117 end function fsync 6118 end interface 6119 6120 ! Variable declaration 6121 integer :: ret 6122 6123 ! Opening unit 10 6124 open (10,file="foo") 6125 6126 ! ... 6127 ! Perform I/O on unit 10 6128 ! ... 6129 6130 ! Flush and sync 6131 flush(10) 6132 ret = fsync(fnum(10)) 6133 6134 ! Handle possible error 6135 if (ret /= 0) stop "Error calling FSYNC" 6136@end smallexample 6137 6138@end table 6139 6140 6141 6142@node FNUM 6143@section @code{FNUM} --- File number function 6144@fnindex FNUM 6145@cindex file operation, file number 6146 6147@table @asis 6148@item @emph{Description}: 6149@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the 6150open Fortran I/O unit @code{UNIT}. 6151 6152@item @emph{Standard}: 6153GNU extension 6154 6155@item @emph{Class}: 6156Function 6157 6158@item @emph{Syntax}: 6159@code{RESULT = FNUM(UNIT)} 6160 6161@item @emph{Arguments}: 6162@multitable @columnfractions .15 .70 6163@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6164@end multitable 6165 6166@item @emph{Return value}: 6167The return value is of type @code{INTEGER} 6168 6169@item @emph{Example}: 6170@smallexample 6171program test_fnum 6172 integer :: i 6173 open (unit=10, status = "scratch") 6174 i = fnum(10) 6175 print *, i 6176 close (10) 6177end program test_fnum 6178@end smallexample 6179@end table 6180 6181 6182 6183@node FPUT 6184@section @code{FPUT} --- Write a single character in stream mode to stdout 6185@fnindex FPUT 6186@cindex write character, stream mode 6187@cindex stream mode, write character 6188@cindex file operation, write character 6189 6190@table @asis 6191@item @emph{Description}: 6192Write a single character in stream mode to stdout by bypassing normal 6193formatted output. Stream I/O should not be mixed with normal record-oriented 6194(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6195 6196This intrinsic is provided in both subroutine and function forms; however, 6197only one form can be used in any given program unit. 6198 6199Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6200@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6201Programmers should consider the use of new stream IO feature in new code 6202for future portability. See also @ref{Fortran 2003 status}. 6203 6204@item @emph{Standard}: 6205GNU extension 6206 6207@item @emph{Class}: 6208Subroutine, function 6209 6210@item @emph{Syntax}: 6211@multitable @columnfractions .80 6212@item @code{CALL FPUT(C [, STATUS])} 6213@item @code{STATUS = FPUT(C)} 6214@end multitable 6215 6216@item @emph{Arguments}: 6217@multitable @columnfractions .15 .70 6218@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6219kind. 6220@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6221Returns 0 on success, -1 on end-of-file and a system specific positive 6222error code otherwise. 6223@end multitable 6224 6225@item @emph{Example}: 6226@smallexample 6227PROGRAM test_fput 6228 CHARACTER(len=10) :: str = "gfortran" 6229 INTEGER :: i 6230 DO i = 1, len_trim(str) 6231 CALL fput(str(i:i)) 6232 END DO 6233END PROGRAM 6234@end smallexample 6235 6236@item @emph{See also}: 6237@ref{FPUTC}, @ref{FGET}, @ref{FGETC} 6238@end table 6239 6240 6241 6242@node FPUTC 6243@section @code{FPUTC} --- Write a single character in stream mode 6244@fnindex FPUTC 6245@cindex write character, stream mode 6246@cindex stream mode, write character 6247@cindex file operation, write character 6248 6249@table @asis 6250@item @emph{Description}: 6251Write a single character in stream mode by bypassing normal formatted 6252output. Stream I/O should not be mixed with normal record-oriented 6253(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6254 6255This intrinsic is provided in both subroutine and function forms; however, 6256only one form can be used in any given program unit. 6257 6258Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6259@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6260Programmers should consider the use of new stream IO feature in new code 6261for future portability. See also @ref{Fortran 2003 status}. 6262 6263@item @emph{Standard}: 6264GNU extension 6265 6266@item @emph{Class}: 6267Subroutine, function 6268 6269@item @emph{Syntax}: 6270@multitable @columnfractions .80 6271@item @code{CALL FPUTC(UNIT, C [, STATUS])} 6272@item @code{STATUS = FPUTC(UNIT, C)} 6273@end multitable 6274 6275@item @emph{Arguments}: 6276@multitable @columnfractions .15 .70 6277@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6278@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6279kind. 6280@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6281Returns 0 on success, -1 on end-of-file and a system specific positive 6282error code otherwise. 6283@end multitable 6284 6285@item @emph{Example}: 6286@smallexample 6287PROGRAM test_fputc 6288 CHARACTER(len=10) :: str = "gfortran" 6289 INTEGER :: fd = 42, i 6290 6291 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW") 6292 DO i = 1, len_trim(str) 6293 CALL fputc(fd, str(i:i)) 6294 END DO 6295 CLOSE(fd) 6296END PROGRAM 6297@end smallexample 6298 6299@item @emph{See also}: 6300@ref{FPUT}, @ref{FGET}, @ref{FGETC} 6301@end table 6302 6303 6304 6305@node FRACTION 6306@section @code{FRACTION} --- Fractional part of the model representation 6307@fnindex FRACTION 6308@cindex real number, fraction 6309@cindex floating point, fraction 6310 6311@table @asis 6312@item @emph{Description}: 6313@code{FRACTION(X)} returns the fractional part of the model 6314representation of @code{X}. 6315 6316@item @emph{Standard}: 6317Fortran 95 and later 6318 6319@item @emph{Class}: 6320Elemental function 6321 6322@item @emph{Syntax}: 6323@code{Y = FRACTION(X)} 6324 6325@item @emph{Arguments}: 6326@multitable @columnfractions .15 .70 6327@item @var{X} @tab The type of the argument shall be a @code{REAL}. 6328@end multitable 6329 6330@item @emph{Return value}: 6331The return value is of the same type and kind as the argument. 6332The fractional part of the model representation of @code{X} is returned; 6333it is @code{X * RADIX(X)**(-EXPONENT(X))}. 6334 6335@item @emph{Example}: 6336@smallexample 6337program test_fraction 6338 real :: x 6339 x = 178.1387e-4 6340 print *, fraction(x), x * radix(x)**(-exponent(x)) 6341end program test_fraction 6342@end smallexample 6343 6344@end table 6345 6346 6347 6348@node FREE 6349@section @code{FREE} --- Frees memory 6350@fnindex FREE 6351@cindex pointer, cray 6352 6353@table @asis 6354@item @emph{Description}: 6355Frees memory previously allocated by @code{MALLOC}. The @code{FREE} 6356intrinsic is an extension intended to be used with Cray pointers, and is 6357provided in GNU Fortran to allow user to compile legacy code. For 6358new code using Fortran 95 pointers, the memory de-allocation intrinsic is 6359@code{DEALLOCATE}. 6360 6361@item @emph{Standard}: 6362GNU extension 6363 6364@item @emph{Class}: 6365Subroutine 6366 6367@item @emph{Syntax}: 6368@code{CALL FREE(PTR)} 6369 6370@item @emph{Arguments}: 6371@multitable @columnfractions .15 .70 6372@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the 6373location of the memory that should be de-allocated. 6374@end multitable 6375 6376@item @emph{Return value}: 6377None 6378 6379@item @emph{Example}: 6380See @code{MALLOC} for an example. 6381 6382@item @emph{See also}: 6383@ref{MALLOC} 6384@end table 6385 6386 6387 6388@node FSEEK 6389@section @code{FSEEK} --- Low level file positioning subroutine 6390@fnindex FSEEK 6391@cindex file operation, seek 6392@cindex file operation, position 6393 6394@table @asis 6395@item @emph{Description}: 6396Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} 6397is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET}, 6398if set to 1, @var{OFFSET} is taken to be relative to the current position 6399@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}. 6400On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek 6401fails silently. 6402 6403This intrinsic routine is not fully backwards compatible with @command{g77}. 6404In @command{g77}, the @code{FSEEK} takes a statement label instead of a 6405@var{STATUS} variable. If FSEEK is used in old code, change 6406@smallexample 6407 CALL FSEEK(UNIT, OFFSET, WHENCE, *label) 6408@end smallexample 6409to 6410@smallexample 6411 INTEGER :: status 6412 CALL FSEEK(UNIT, OFFSET, WHENCE, status) 6413 IF (status /= 0) GOTO label 6414@end smallexample 6415 6416Please note that GNU Fortran provides the Fortran 2003 Stream facility. 6417Programmers should consider the use of new stream IO feature in new code 6418for future portability. See also @ref{Fortran 2003 status}. 6419 6420@item @emph{Standard}: 6421GNU extension 6422 6423@item @emph{Class}: 6424Subroutine 6425 6426@item @emph{Syntax}: 6427@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])} 6428 6429@item @emph{Arguments}: 6430@multitable @columnfractions .15 .70 6431@item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}. 6432@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}. 6433@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}. 6434Its value shall be either 0, 1 or 2. 6435@item @var{STATUS} @tab (Optional) shall be a scalar of type 6436@code{INTEGER(4)}. 6437@end multitable 6438 6439@item @emph{Example}: 6440@smallexample 6441PROGRAM test_fseek 6442 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2 6443 INTEGER :: fd, offset, ierr 6444 6445 ierr = 0 6446 offset = 5 6447 fd = 10 6448 6449 OPEN(UNIT=fd, FILE="fseek.test") 6450 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET 6451 print *, FTELL(fd), ierr 6452 6453 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end 6454 print *, FTELL(fd), ierr 6455 6456 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning 6457 print *, FTELL(fd), ierr 6458 6459 CLOSE(UNIT=fd) 6460END PROGRAM 6461@end smallexample 6462 6463@item @emph{See also}: 6464@ref{FTELL} 6465@end table 6466 6467 6468 6469@node FSTAT 6470@section @code{FSTAT} --- Get file status 6471@fnindex FSTAT 6472@cindex file system, file status 6473 6474@table @asis 6475@item @emph{Description}: 6476@code{FSTAT} is identical to @ref{STAT}, except that information about an 6477already opened file is obtained. 6478 6479The elements in @code{VALUES} are the same as described by @ref{STAT}. 6480 6481This intrinsic is provided in both subroutine and function forms; however, 6482only one form can be used in any given program unit. 6483 6484@item @emph{Standard}: 6485GNU extension 6486 6487@item @emph{Class}: 6488Subroutine, function 6489 6490@item @emph{Syntax}: 6491@multitable @columnfractions .80 6492@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])} 6493@item @code{STATUS = FSTAT(UNIT, VALUES)} 6494@end multitable 6495 6496@item @emph{Arguments}: 6497@multitable @columnfractions .15 .70 6498@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. 6499@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 6500@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 6501on success and a system specific error code otherwise. 6502@end multitable 6503 6504@item @emph{Example}: 6505See @ref{STAT} for an example. 6506 6507@item @emph{See also}: 6508To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT} 6509@end table 6510 6511 6512 6513@node FTELL 6514@section @code{FTELL} --- Current stream position 6515@fnindex FTELL 6516@cindex file operation, position 6517 6518@table @asis 6519@item @emph{Description}: 6520Retrieves the current position within an open file. 6521 6522This intrinsic is provided in both subroutine and function forms; however, 6523only one form can be used in any given program unit. 6524 6525@item @emph{Standard}: 6526GNU extension 6527 6528@item @emph{Class}: 6529Subroutine, function 6530 6531@item @emph{Syntax}: 6532@multitable @columnfractions .80 6533@item @code{CALL FTELL(UNIT, OFFSET)} 6534@item @code{OFFSET = FTELL(UNIT)} 6535@end multitable 6536 6537@item @emph{Arguments}: 6538@multitable @columnfractions .15 .70 6539@item @var{OFFSET} @tab Shall of type @code{INTEGER}. 6540@item @var{UNIT} @tab Shall of type @code{INTEGER}. 6541@end multitable 6542 6543@item @emph{Return value}: 6544In either syntax, @var{OFFSET} is set to the current offset of unit 6545number @var{UNIT}, or to @math{-1} if the unit is not currently open. 6546 6547@item @emph{Example}: 6548@smallexample 6549PROGRAM test_ftell 6550 INTEGER :: i 6551 OPEN(10, FILE="temp.dat") 6552 CALL ftell(10,i) 6553 WRITE(*,*) i 6554END PROGRAM 6555@end smallexample 6556 6557@item @emph{See also}: 6558@ref{FSEEK} 6559@end table 6560 6561 6562 6563@node GAMMA 6564@section @code{GAMMA} --- Gamma function 6565@fnindex GAMMA 6566@fnindex DGAMMA 6567@cindex Gamma function 6568@cindex Factorial function 6569 6570@table @asis 6571@item @emph{Description}: 6572@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive, 6573integer values of @var{X} the Gamma function simplifies to the factorial 6574function @math{\Gamma(x)=(x-1)!}. 6575 6576@tex 6577$$ 6578\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t 6579$$ 6580@end tex 6581 6582@item @emph{Standard}: 6583Fortran 2008 and later 6584 6585@item @emph{Class}: 6586Elemental function 6587 6588@item @emph{Syntax}: 6589@code{X = GAMMA(X)} 6590 6591@item @emph{Arguments}: 6592@multitable @columnfractions .15 .70 6593@item @var{X} @tab Shall be of type @code{REAL} and neither zero 6594nor a negative integer. 6595@end multitable 6596 6597@item @emph{Return value}: 6598The return value is of type @code{REAL} of the same kind as @var{X}. 6599 6600@item @emph{Example}: 6601@smallexample 6602program test_gamma 6603 real :: x = 1.0 6604 x = gamma(x) ! returns 1.0 6605end program test_gamma 6606@end smallexample 6607 6608@item @emph{Specific names}: 6609@multitable @columnfractions .20 .20 .20 .25 6610@item Name @tab Argument @tab Return type @tab Standard 6611@item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 6612@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 6613@end multitable 6614 6615@item @emph{See also}: 6616Logarithm of the Gamma function: @ref{LOG_GAMMA} 6617 6618@end table 6619 6620 6621 6622@node GERROR 6623@section @code{GERROR} --- Get last system error message 6624@fnindex GERROR 6625@cindex system, error handling 6626 6627@table @asis 6628@item @emph{Description}: 6629Returns the system error message corresponding to the last system error. 6630This resembles the functionality of @code{strerror(3)} in C. 6631 6632@item @emph{Standard}: 6633GNU extension 6634 6635@item @emph{Class}: 6636Subroutine 6637 6638@item @emph{Syntax}: 6639@code{CALL GERROR(RESULT)} 6640 6641@item @emph{Arguments}: 6642@multitable @columnfractions .15 .70 6643@item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default 6644@end multitable 6645 6646@item @emph{Example}: 6647@smallexample 6648PROGRAM test_gerror 6649 CHARACTER(len=100) :: msg 6650 CALL gerror(msg) 6651 WRITE(*,*) msg 6652END PROGRAM 6653@end smallexample 6654 6655@item @emph{See also}: 6656@ref{IERRNO}, @ref{PERROR} 6657@end table 6658 6659 6660 6661@node GETARG 6662@section @code{GETARG} --- Get command line arguments 6663@fnindex GETARG 6664@cindex command-line arguments 6665@cindex arguments, to program 6666 6667@table @asis 6668@item @emph{Description}: 6669Retrieve the @var{POS}-th argument that was passed on the 6670command line when the containing program was invoked. 6671 6672This intrinsic routine is provided for backwards compatibility with 6673GNU Fortran 77. In new code, programmers should consider the use of 6674the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 6675standard. 6676 6677@item @emph{Standard}: 6678GNU extension 6679 6680@item @emph{Class}: 6681Subroutine 6682 6683@item @emph{Syntax}: 6684@code{CALL GETARG(POS, VALUE)} 6685 6686@item @emph{Arguments}: 6687@multitable @columnfractions .15 .70 6688@item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than 6689the default integer kind; @math{@var{POS} \geq 0} 6690@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default 6691kind. 6692@item @var{VALUE} @tab Shall be of type @code{CHARACTER}. 6693@end multitable 6694 6695@item @emph{Return value}: 6696After @code{GETARG} returns, the @var{VALUE} argument holds the 6697@var{POS}th command line argument. If @var{VALUE} can not hold the 6698argument, it is truncated to fit the length of @var{VALUE}. If there are 6699less than @var{POS} arguments specified at the command line, @var{VALUE} 6700will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set 6701to the name of the program (on systems that support this feature). 6702 6703@item @emph{Example}: 6704@smallexample 6705PROGRAM test_getarg 6706 INTEGER :: i 6707 CHARACTER(len=32) :: arg 6708 6709 DO i = 1, iargc() 6710 CALL getarg(i, arg) 6711 WRITE (*,*) arg 6712 END DO 6713END PROGRAM 6714@end smallexample 6715 6716@item @emph{See also}: 6717GNU Fortran 77 compatibility function: @ref{IARGC} 6718 6719Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, 6720@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 6721@end table 6722 6723 6724 6725@node GET_COMMAND 6726@section @code{GET_COMMAND} --- Get the entire command line 6727@fnindex GET_COMMAND 6728@cindex command-line arguments 6729@cindex arguments, to program 6730 6731@table @asis 6732@item @emph{Description}: 6733Retrieve the entire command line that was used to invoke the program. 6734 6735@item @emph{Standard}: 6736Fortran 2003 and later 6737 6738@item @emph{Class}: 6739Subroutine 6740 6741@item @emph{Syntax}: 6742@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])} 6743 6744@item @emph{Arguments}: 6745@multitable @columnfractions .15 .70 6746@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and 6747of default kind. 6748@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of 6749default kind. 6750@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of 6751default kind. 6752@end multitable 6753 6754@item @emph{Return value}: 6755If @var{COMMAND} is present, stores the entire command line that was used 6756to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is 6757assigned the length of the command line. If @var{STATUS} is present, it 6758is assigned 0 upon success of the command, -1 if @var{COMMAND} is too 6759short to store the command line, or a positive value in case of an error. 6760 6761@item @emph{Example}: 6762@smallexample 6763PROGRAM test_get_command 6764 CHARACTER(len=255) :: cmd 6765 CALL get_command(cmd) 6766 WRITE (*,*) TRIM(cmd) 6767END PROGRAM 6768@end smallexample 6769 6770@item @emph{See also}: 6771@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 6772@end table 6773 6774 6775 6776@node GET_COMMAND_ARGUMENT 6777@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments 6778@fnindex GET_COMMAND_ARGUMENT 6779@cindex command-line arguments 6780@cindex arguments, to program 6781 6782@table @asis 6783@item @emph{Description}: 6784Retrieve the @var{NUMBER}-th argument that was passed on the 6785command line when the containing program was invoked. 6786 6787@item @emph{Standard}: 6788Fortran 2003 and later 6789 6790@item @emph{Class}: 6791Subroutine 6792 6793@item @emph{Syntax}: 6794@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])} 6795 6796@item @emph{Arguments}: 6797@multitable @columnfractions .15 .70 6798@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of 6799default kind, @math{@var{NUMBER} \geq 0} 6800@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 6801and of default kind. 6802@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6803and of default kind. 6804@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6805and of default kind. 6806@end multitable 6807 6808@item @emph{Return value}: 6809After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the 6810@var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is 6811truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER} 6812arguments specified at the command line, @var{VALUE} will be filled with blanks. 6813If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on 6814systems that support this feature). The @var{LENGTH} argument contains the 6815length of the @var{NUMBER}-th command line argument. If the argument retrieval 6816fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated 6817command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is 6818zero. 6819 6820@item @emph{Example}: 6821@smallexample 6822PROGRAM test_get_command_argument 6823 INTEGER :: i 6824 CHARACTER(len=32) :: arg 6825 6826 i = 0 6827 DO 6828 CALL get_command_argument(i, arg) 6829 IF (LEN_TRIM(arg) == 0) EXIT 6830 6831 WRITE (*,*) TRIM(arg) 6832 i = i+1 6833 END DO 6834END PROGRAM 6835@end smallexample 6836 6837@item @emph{See also}: 6838@ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT} 6839@end table 6840 6841 6842 6843@node GETCWD 6844@section @code{GETCWD} --- Get current working directory 6845@fnindex GETCWD 6846@cindex system, working directory 6847 6848@table @asis 6849@item @emph{Description}: 6850Get current working directory. 6851 6852This intrinsic is provided in both subroutine and function forms; however, 6853only one form can be used in any given program unit. 6854 6855@item @emph{Standard}: 6856GNU extension 6857 6858@item @emph{Class}: 6859Subroutine, function 6860 6861@item @emph{Syntax}: 6862@multitable @columnfractions .80 6863@item @code{CALL GETCWD(C [, STATUS])} 6864@item @code{STATUS = GETCWD(C)} 6865@end multitable 6866 6867@item @emph{Arguments}: 6868@multitable @columnfractions .15 .70 6869@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. 6870@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, 6871a system specific and nonzero error code otherwise. 6872@end multitable 6873 6874@item @emph{Example}: 6875@smallexample 6876PROGRAM test_getcwd 6877 CHARACTER(len=255) :: cwd 6878 CALL getcwd(cwd) 6879 WRITE(*,*) TRIM(cwd) 6880END PROGRAM 6881@end smallexample 6882 6883@item @emph{See also}: 6884@ref{CHDIR} 6885@end table 6886 6887 6888 6889@node GETENV 6890@section @code{GETENV} --- Get an environmental variable 6891@fnindex GETENV 6892@cindex environment variable 6893 6894@table @asis 6895@item @emph{Description}: 6896Get the @var{VALUE} of the environmental variable @var{NAME}. 6897 6898This intrinsic routine is provided for backwards compatibility with 6899GNU Fortran 77. In new code, programmers should consider the use of 6900the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran 69012003 standard. 6902 6903Note that @code{GETENV} need not be thread-safe. It is the 6904responsibility of the user to ensure that the environment is not being 6905updated concurrently with a call to the @code{GETENV} intrinsic. 6906 6907@item @emph{Standard}: 6908GNU extension 6909 6910@item @emph{Class}: 6911Subroutine 6912 6913@item @emph{Syntax}: 6914@code{CALL GETENV(NAME, VALUE)} 6915 6916@item @emph{Arguments}: 6917@multitable @columnfractions .15 .70 6918@item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind. 6919@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. 6920@end multitable 6921 6922@item @emph{Return value}: 6923Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 6924not large enough to hold the data, it is truncated. If @var{NAME} 6925is not set, @var{VALUE} will be filled with blanks. 6926 6927@item @emph{Example}: 6928@smallexample 6929PROGRAM test_getenv 6930 CHARACTER(len=255) :: homedir 6931 CALL getenv("HOME", homedir) 6932 WRITE (*,*) TRIM(homedir) 6933END PROGRAM 6934@end smallexample 6935 6936@item @emph{See also}: 6937@ref{GET_ENVIRONMENT_VARIABLE} 6938@end table 6939 6940 6941 6942@node GET_ENVIRONMENT_VARIABLE 6943@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable 6944@fnindex GET_ENVIRONMENT_VARIABLE 6945@cindex environment variable 6946 6947@table @asis 6948@item @emph{Description}: 6949Get the @var{VALUE} of the environmental variable @var{NAME}. 6950 6951Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It 6952is the responsibility of the user to ensure that the environment is 6953not being updated concurrently with a call to the 6954@code{GET_ENVIRONMENT_VARIABLE} intrinsic. 6955 6956@item @emph{Standard}: 6957Fortran 2003 and later 6958 6959@item @emph{Class}: 6960Subroutine 6961 6962@item @emph{Syntax}: 6963@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)} 6964 6965@item @emph{Arguments}: 6966@multitable @columnfractions .15 .70 6967@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER} 6968and of default kind. 6969@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 6970and of default kind. 6971@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6972and of default kind. 6973@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6974and of default kind. 6975@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL} 6976and of default kind. 6977@end multitable 6978 6979@item @emph{Return value}: 6980Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 6981not large enough to hold the data, it is truncated. If @var{NAME} 6982is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH} 6983contains the length needed for storing the environment variable @var{NAME} 6984or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present 6985but too short for the environment variable; it is 1 if the environment 6986variable does not exist and 2 if the processor does not support environment 6987variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is 6988present with the value @code{.FALSE.}, the trailing blanks in @var{NAME} 6989are significant; otherwise they are not part of the environment variable 6990name. 6991 6992@item @emph{Example}: 6993@smallexample 6994PROGRAM test_getenv 6995 CHARACTER(len=255) :: homedir 6996 CALL get_environment_variable("HOME", homedir) 6997 WRITE (*,*) TRIM(homedir) 6998END PROGRAM 6999@end smallexample 7000@end table 7001 7002 7003 7004@node GETGID 7005@section @code{GETGID} --- Group ID function 7006@fnindex GETGID 7007@cindex system, group ID 7008 7009@table @asis 7010@item @emph{Description}: 7011Returns the numerical group ID of the current process. 7012 7013@item @emph{Standard}: 7014GNU extension 7015 7016@item @emph{Class}: 7017Function 7018 7019@item @emph{Syntax}: 7020@code{RESULT = GETGID()} 7021 7022@item @emph{Return value}: 7023The return value of @code{GETGID} is an @code{INTEGER} of the default 7024kind. 7025 7026 7027@item @emph{Example}: 7028See @code{GETPID} for an example. 7029 7030@item @emph{See also}: 7031@ref{GETPID}, @ref{GETUID} 7032@end table 7033 7034 7035 7036@node GETLOG 7037@section @code{GETLOG} --- Get login name 7038@fnindex GETLOG 7039@cindex system, login name 7040@cindex login name 7041 7042@table @asis 7043@item @emph{Description}: 7044Gets the username under which the program is running. 7045 7046@item @emph{Standard}: 7047GNU extension 7048 7049@item @emph{Class}: 7050Subroutine 7051 7052@item @emph{Syntax}: 7053@code{CALL GETLOG(C)} 7054 7055@item @emph{Arguments}: 7056@multitable @columnfractions .15 .70 7057@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind. 7058@end multitable 7059 7060@item @emph{Return value}: 7061Stores the current user name in @var{LOGIN}. (On systems where POSIX 7062functions @code{geteuid} and @code{getpwuid} are not available, and 7063the @code{getlogin} function is not implemented either, this will 7064return a blank string.) 7065 7066@item @emph{Example}: 7067@smallexample 7068PROGRAM TEST_GETLOG 7069 CHARACTER(32) :: login 7070 CALL GETLOG(login) 7071 WRITE(*,*) login 7072END PROGRAM 7073@end smallexample 7074 7075@item @emph{See also}: 7076@ref{GETUID} 7077@end table 7078 7079 7080 7081@node GETPID 7082@section @code{GETPID} --- Process ID function 7083@fnindex GETPID 7084@cindex system, process ID 7085@cindex process ID 7086 7087@table @asis 7088@item @emph{Description}: 7089Returns the numerical process identifier of the current process. 7090 7091@item @emph{Standard}: 7092GNU extension 7093 7094@item @emph{Class}: 7095Function 7096 7097@item @emph{Syntax}: 7098@code{RESULT = GETPID()} 7099 7100@item @emph{Return value}: 7101The return value of @code{GETPID} is an @code{INTEGER} of the default 7102kind. 7103 7104 7105@item @emph{Example}: 7106@smallexample 7107program info 7108 print *, "The current process ID is ", getpid() 7109 print *, "Your numerical user ID is ", getuid() 7110 print *, "Your numerical group ID is ", getgid() 7111end program info 7112@end smallexample 7113 7114@item @emph{See also}: 7115@ref{GETGID}, @ref{GETUID} 7116@end table 7117 7118 7119 7120@node GETUID 7121@section @code{GETUID} --- User ID function 7122@fnindex GETUID 7123@cindex system, user ID 7124@cindex user id 7125 7126@table @asis 7127@item @emph{Description}: 7128Returns the numerical user ID of the current process. 7129 7130@item @emph{Standard}: 7131GNU extension 7132 7133@item @emph{Class}: 7134Function 7135 7136@item @emph{Syntax}: 7137@code{RESULT = GETUID()} 7138 7139@item @emph{Return value}: 7140The return value of @code{GETUID} is an @code{INTEGER} of the default 7141kind. 7142 7143 7144@item @emph{Example}: 7145See @code{GETPID} for an example. 7146 7147@item @emph{See also}: 7148@ref{GETPID}, @ref{GETLOG} 7149@end table 7150 7151 7152 7153@node GMTIME 7154@section @code{GMTIME} --- Convert time to GMT info 7155@fnindex GMTIME 7156@cindex time, conversion to GMT info 7157 7158@table @asis 7159@item @emph{Description}: 7160Given a system time value @var{TIME} (as provided by the @ref{TIME} 7161intrinsic), fills @var{VALUES} with values extracted from it appropriate 7162to the UTC time zone (Universal Coordinated Time, also known in some 7163countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}. 7164 7165This intrinsic routine is provided for backwards compatibility with 7166GNU Fortran 77. In new code, programmers should consider the use of 7167the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 7168standard. 7169 7170@item @emph{Standard}: 7171GNU extension 7172 7173@item @emph{Class}: 7174Subroutine 7175 7176@item @emph{Syntax}: 7177@code{CALL GMTIME(TIME, VALUES)} 7178 7179@item @emph{Arguments}: 7180@multitable @columnfractions .15 .70 7181@item @var{TIME} @tab An @code{INTEGER} scalar expression 7182corresponding to a system time, with @code{INTENT(IN)}. 7183@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 7184with @code{INTENT(OUT)}. 7185@end multitable 7186 7187@item @emph{Return value}: 7188The elements of @var{VALUES} are assigned as follows: 7189@enumerate 7190@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 7191seconds 7192@item Minutes after the hour, range 0--59 7193@item Hours past midnight, range 0--23 7194@item Day of month, range 1--31 7195@item Number of months since January, range 0--11 7196@item Years since 1900 7197@item Number of days since Sunday, range 0--6 7198@item Days since January 1, range 0--365 7199@item Daylight savings indicator: positive if daylight savings is in 7200effect, zero if not, and negative if the information is not available. 7201@end enumerate 7202 7203@item @emph{See also}: 7204@ref{DATE_AND_TIME}, @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} 7205 7206@end table 7207 7208 7209 7210@node HOSTNM 7211@section @code{HOSTNM} --- Get system host name 7212@fnindex HOSTNM 7213@cindex system, host name 7214 7215@table @asis 7216@item @emph{Description}: 7217Retrieves the host name of the system on which the program is running. 7218 7219This intrinsic is provided in both subroutine and function forms; however, 7220only one form can be used in any given program unit. 7221 7222@item @emph{Standard}: 7223GNU extension 7224 7225@item @emph{Class}: 7226Subroutine, function 7227 7228@item @emph{Syntax}: 7229@multitable @columnfractions .80 7230@item @code{CALL HOSTNM(C [, STATUS])} 7231@item @code{STATUS = HOSTNM(NAME)} 7232@end multitable 7233 7234@item @emph{Arguments}: 7235@multitable @columnfractions .15 .70 7236@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind. 7237@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 7238Returns 0 on success, or a system specific error code otherwise. 7239@end multitable 7240 7241@item @emph{Return value}: 7242In either syntax, @var{NAME} is set to the current hostname if it can 7243be obtained, or to a blank string otherwise. 7244 7245@end table 7246 7247 7248 7249@node HUGE 7250@section @code{HUGE} --- Largest number of a kind 7251@fnindex HUGE 7252@cindex limits, largest number 7253@cindex model representation, largest number 7254 7255@table @asis 7256@item @emph{Description}: 7257@code{HUGE(X)} returns the largest number that is not an infinity in 7258the model of the type of @code{X}. 7259 7260@item @emph{Standard}: 7261Fortran 95 and later 7262 7263@item @emph{Class}: 7264Inquiry function 7265 7266@item @emph{Syntax}: 7267@code{RESULT = HUGE(X)} 7268 7269@item @emph{Arguments}: 7270@multitable @columnfractions .15 .70 7271@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}. 7272@end multitable 7273 7274@item @emph{Return value}: 7275The return value is of the same type and kind as @var{X} 7276 7277@item @emph{Example}: 7278@smallexample 7279program test_huge_tiny 7280 print *, huge(0), huge(0.0), huge(0.0d0) 7281 print *, tiny(0.0), tiny(0.0d0) 7282end program test_huge_tiny 7283@end smallexample 7284@end table 7285 7286 7287 7288@node HYPOT 7289@section @code{HYPOT} --- Euclidean distance function 7290@fnindex HYPOT 7291@cindex Euclidean distance 7292 7293@table @asis 7294@item @emph{Description}: 7295@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to 7296@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow. 7297 7298@item @emph{Standard}: 7299Fortran 2008 and later 7300 7301@item @emph{Class}: 7302Elemental function 7303 7304@item @emph{Syntax}: 7305@code{RESULT = HYPOT(X, Y)} 7306 7307@item @emph{Arguments}: 7308@multitable @columnfractions .15 .70 7309@item @var{X} @tab The type shall be @code{REAL}. 7310@item @var{Y} @tab The type and kind type parameter shall be the same as 7311@var{X}. 7312@end multitable 7313 7314@item @emph{Return value}: 7315The return value has the same type and kind type parameter as @var{X}. 7316 7317@item @emph{Example}: 7318@smallexample 7319program test_hypot 7320 real(4) :: x = 1.e0_4, y = 0.5e0_4 7321 x = hypot(x,y) 7322end program test_hypot 7323@end smallexample 7324@end table 7325 7326 7327 7328@node IACHAR 7329@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence 7330@fnindex IACHAR 7331@cindex @acronym{ASCII} collating sequence 7332@cindex collating sequence, @acronym{ASCII} 7333@cindex conversion, to integer 7334 7335@table @asis 7336@item @emph{Description}: 7337@code{IACHAR(C)} returns the code for the @acronym{ASCII} character 7338in the first character position of @code{C}. 7339 7340@item @emph{Standard}: 7341Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 7342 7343@item @emph{Class}: 7344Elemental function 7345 7346@item @emph{Syntax}: 7347@code{RESULT = IACHAR(C [, KIND])} 7348 7349@item @emph{Arguments}: 7350@multitable @columnfractions .15 .70 7351@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 7352@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7353expression indicating the kind parameter of the result. 7354@end multitable 7355 7356@item @emph{Return value}: 7357The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7358@var{KIND} is absent, the return value is of default integer kind. 7359 7360@item @emph{Example}: 7361@smallexample 7362program test_iachar 7363 integer i 7364 i = iachar(' ') 7365end program test_iachar 7366@end smallexample 7367 7368@item @emph{Note}: 7369See @ref{ICHAR} for a discussion of converting between numerical values 7370and formatted string representations. 7371 7372@item @emph{See also}: 7373@ref{ACHAR}, @ref{CHAR}, @ref{ICHAR} 7374 7375@end table 7376 7377 7378 7379@node IALL 7380@section @code{IALL} --- Bitwise AND of array elements 7381@fnindex IALL 7382@cindex array, AND 7383@cindex bits, AND of array elements 7384 7385@table @asis 7386@item @emph{Description}: 7387Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM} 7388if the corresponding element in @var{MASK} is @code{TRUE}. 7389 7390@item @emph{Standard}: 7391Fortran 2008 and later 7392 7393@item @emph{Class}: 7394Transformational function 7395 7396@item @emph{Syntax}: 7397@multitable @columnfractions .80 7398@item @code{RESULT = IALL(ARRAY[, MASK])} 7399@item @code{RESULT = IALL(ARRAY, DIM[, MASK])} 7400@end multitable 7401 7402@item @emph{Arguments}: 7403@multitable @columnfractions .15 .70 7404@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7405@item @var{DIM} @tab (Optional) shall be a scalar of type 7406@code{INTEGER} with a value in the range from 1 to n, where n 7407equals the rank of @var{ARRAY}. 7408@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7409and either be a scalar or an array of the same shape as @var{ARRAY}. 7410@end multitable 7411 7412@item @emph{Return value}: 7413The result is of the same type as @var{ARRAY}. 7414 7415If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in 7416@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7417the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7418dimension @var{DIM} dropped is returned. 7419 7420@item @emph{Example}: 7421@smallexample 7422PROGRAM test_iall 7423 INTEGER(1) :: a(2) 7424 7425 a(1) = b'00100100' 7426 a(2) = b'01101010' 7427 7428 ! prints 00100000 7429 PRINT '(b8.8)', IALL(a) 7430END PROGRAM 7431@end smallexample 7432 7433@item @emph{See also}: 7434@ref{IANY}, @ref{IPARITY}, @ref{IAND} 7435@end table 7436 7437 7438 7439@node IAND 7440@section @code{IAND} --- Bitwise logical and 7441@fnindex IAND 7442@fnindex BIAND 7443@fnindex IIAND 7444@fnindex JIAND 7445@fnindex KIAND 7446@cindex bitwise logical and 7447@cindex logical and, bitwise 7448 7449@table @asis 7450@item @emph{Description}: 7451Bitwise logical @code{AND}. 7452 7453@item @emph{Standard}: 7454Fortran 95 and later, has overloads that are GNU extensions 7455 7456@item @emph{Class}: 7457Elemental function 7458 7459@item @emph{Syntax}: 7460@code{RESULT = IAND(I, J)} 7461 7462@item @emph{Arguments}: 7463@multitable @columnfractions .15 .70 7464@item @var{I} @tab The type shall be @code{INTEGER}. 7465@item @var{J} @tab The type shall be @code{INTEGER}, of the same 7466kind as @var{I}. (As a GNU extension, different kinds are also 7467permitted.) 7468@end multitable 7469 7470@item @emph{Return value}: 7471The return type is @code{INTEGER}, of the same kind as the 7472arguments. (If the argument kinds differ, it is of the same kind as 7473the larger argument.) 7474 7475@item @emph{Example}: 7476@smallexample 7477PROGRAM test_iand 7478 INTEGER :: a, b 7479 DATA a / Z'F' /, b / Z'3' / 7480 WRITE (*,*) IAND(a, b) 7481END PROGRAM 7482@end smallexample 7483 7484@item @emph{Specific names}: 7485@multitable @columnfractions .20 .20 .20 .25 7486@item Name @tab Argument @tab Return type @tab Standard 7487@item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7488@item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7489@item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7490@item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7491@item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7492@end multitable 7493 7494@item @emph{See also}: 7495@ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 7496 7497@end table 7498 7499 7500 7501@node IANY 7502@section @code{IANY} --- Bitwise OR of array elements 7503@fnindex IANY 7504@cindex array, OR 7505@cindex bits, OR of array elements 7506 7507@table @asis 7508@item @emph{Description}: 7509Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along 7510dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 7511 7512@item @emph{Standard}: 7513Fortran 2008 and later 7514 7515@item @emph{Class}: 7516Transformational function 7517 7518@item @emph{Syntax}: 7519@multitable @columnfractions .80 7520@item @code{RESULT = IANY(ARRAY[, MASK])} 7521@item @code{RESULT = IANY(ARRAY, DIM[, MASK])} 7522@end multitable 7523 7524@item @emph{Arguments}: 7525@multitable @columnfractions .15 .70 7526@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7527@item @var{DIM} @tab (Optional) shall be a scalar of type 7528@code{INTEGER} with a value in the range from 1 to n, where n 7529equals the rank of @var{ARRAY}. 7530@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7531and either be a scalar or an array of the same shape as @var{ARRAY}. 7532@end multitable 7533 7534@item @emph{Return value}: 7535The result is of the same type as @var{ARRAY}. 7536 7537If @var{DIM} is absent, a scalar with the bitwise OR of all elements in 7538@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7539the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7540dimension @var{DIM} dropped is returned. 7541 7542@item @emph{Example}: 7543@smallexample 7544PROGRAM test_iany 7545 INTEGER(1) :: a(2) 7546 7547 a(1) = b'00100100' 7548 a(2) = b'01101010' 7549 7550 ! prints 01101110 7551 PRINT '(b8.8)', IANY(a) 7552END PROGRAM 7553@end smallexample 7554 7555@item @emph{See also}: 7556@ref{IPARITY}, @ref{IALL}, @ref{IOR} 7557@end table 7558 7559 7560 7561@node IARGC 7562@section @code{IARGC} --- Get the number of command line arguments 7563@fnindex IARGC 7564@cindex command-line arguments 7565@cindex command-line arguments, number of 7566@cindex arguments, to program 7567 7568@table @asis 7569@item @emph{Description}: 7570@code{IARGC} returns the number of arguments passed on the 7571command line when the containing program was invoked. 7572 7573This intrinsic routine is provided for backwards compatibility with 7574GNU Fortran 77. In new code, programmers should consider the use of 7575the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 7576standard. 7577 7578@item @emph{Standard}: 7579GNU extension 7580 7581@item @emph{Class}: 7582Function 7583 7584@item @emph{Syntax}: 7585@code{RESULT = IARGC()} 7586 7587@item @emph{Arguments}: 7588None. 7589 7590@item @emph{Return value}: 7591The number of command line arguments, type @code{INTEGER(4)}. 7592 7593@item @emph{Example}: 7594See @ref{GETARG} 7595 7596@item @emph{See also}: 7597GNU Fortran 77 compatibility subroutine: @ref{GETARG} 7598 7599Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, 7600@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 7601@end table 7602 7603 7604 7605@node IBCLR 7606@section @code{IBCLR} --- Clear bit 7607@fnindex IBCLR 7608@fnindex BBCLR 7609@fnindex IIBCLR 7610@fnindex JIBCLR 7611@fnindex KIBCLR 7612@cindex bits, unset 7613@cindex bits, clear 7614 7615@table @asis 7616@item @emph{Description}: 7617@code{IBCLR} returns the value of @var{I} with the bit at position 7618@var{POS} set to zero. 7619 7620@item @emph{Standard}: 7621Fortran 95 and later, has overloads that are GNU extensions 7622 7623@item @emph{Class}: 7624Elemental function 7625 7626@item @emph{Syntax}: 7627@code{RESULT = IBCLR(I, POS)} 7628 7629@item @emph{Arguments}: 7630@multitable @columnfractions .15 .70 7631@item @var{I} @tab The type shall be @code{INTEGER}. 7632@item @var{POS} @tab The type shall be @code{INTEGER}. 7633@end multitable 7634 7635@item @emph{Return value}: 7636The return value is of type @code{INTEGER} and of the same kind as 7637@var{I}. 7638 7639@item @emph{Specific names}: 7640@multitable @columnfractions .20 .20 .20 .25 7641@item Name @tab Argument @tab Return type @tab Standard 7642@item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7643@item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7644@item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7645@item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7646@item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7647@end multitable 7648 7649@item @emph{See also}: 7650@ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} 7651 7652@end table 7653 7654 7655 7656@node IBITS 7657@section @code{IBITS} --- Bit extraction 7658@fnindex IBITS 7659@fnindex BBITS 7660@fnindex IIBITS 7661@fnindex JIBITS 7662@fnindex KIBITS 7663@cindex bits, get 7664@cindex bits, extract 7665 7666@table @asis 7667@item @emph{Description}: 7668@code{IBITS} extracts a field of length @var{LEN} from @var{I}, 7669starting from bit position @var{POS} and extending left for @var{LEN} 7670bits. The result is right-justified and the remaining bits are 7671zeroed. The value of @code{POS+LEN} must be less than or equal to the 7672value @code{BIT_SIZE(I)}. 7673 7674@item @emph{Standard}: 7675Fortran 95 and later, has overloads that are GNU extensions 7676 7677@item @emph{Class}: 7678Elemental function 7679 7680@item @emph{Syntax}: 7681@code{RESULT = IBITS(I, POS, LEN)} 7682 7683@item @emph{Arguments}: 7684@multitable @columnfractions .15 .70 7685@item @var{I} @tab The type shall be @code{INTEGER}. 7686@item @var{POS} @tab The type shall be @code{INTEGER}. 7687@item @var{LEN} @tab The type shall be @code{INTEGER}. 7688@end multitable 7689 7690@item @emph{Return value}: 7691The return value is of type @code{INTEGER} and of the same kind as 7692@var{I}. 7693 7694@item @emph{Specific names}: 7695@multitable @columnfractions .20 .20 .20 .25 7696@item Name @tab Argument @tab Return type @tab Standard 7697@item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7698@item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7699@item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7700@item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7701@item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7702@end multitable 7703 7704@item @emph{See also}: 7705@ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR} 7706@end table 7707 7708 7709 7710@node IBSET 7711@section @code{IBSET} --- Set bit 7712@fnindex IBSET 7713@fnindex BBSET 7714@fnindex IIBSET 7715@fnindex JIBSET 7716@fnindex KIBSET 7717@cindex bits, set 7718 7719@table @asis 7720@item @emph{Description}: 7721@code{IBSET} returns the value of @var{I} with the bit at position 7722@var{POS} set to one. 7723 7724@item @emph{Standard}: 7725Fortran 95 and later, has overloads that are GNU extensions 7726 7727@item @emph{Class}: 7728Elemental function 7729 7730@item @emph{Syntax}: 7731@code{RESULT = IBSET(I, POS)} 7732 7733@item @emph{Arguments}: 7734@multitable @columnfractions .15 .70 7735@item @var{I} @tab The type shall be @code{INTEGER}. 7736@item @var{POS} @tab The type shall be @code{INTEGER}. 7737@end multitable 7738 7739@item @emph{Return value}: 7740The return value is of type @code{INTEGER} and of the same kind as 7741@var{I}. 7742 7743@item @emph{Specific names}: 7744@multitable @columnfractions .20 .20 .20 .25 7745@item Name @tab Argument @tab Return type @tab Standard 7746@item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7747@item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7748@item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7749@item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7750@item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7751@end multitable 7752 7753@item @emph{See also}: 7754@ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} 7755 7756@end table 7757 7758 7759 7760@node ICHAR 7761@section @code{ICHAR} --- Character-to-integer conversion function 7762@fnindex ICHAR 7763@cindex conversion, to integer 7764 7765@table @asis 7766@item @emph{Description}: 7767@code{ICHAR(C)} returns the code for the character in the first character 7768position of @code{C} in the system's native character set. 7769The correspondence between characters and their codes is not necessarily 7770the same across different GNU Fortran implementations. 7771 7772@item @emph{Standard}: 7773Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 7774 7775@item @emph{Class}: 7776Elemental function 7777 7778@item @emph{Syntax}: 7779@code{RESULT = ICHAR(C [, KIND])} 7780 7781@item @emph{Arguments}: 7782@multitable @columnfractions .15 .70 7783@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 7784@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7785expression indicating the kind parameter of the result. 7786@end multitable 7787 7788@item @emph{Return value}: 7789The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7790@var{KIND} is absent, the return value is of default integer kind. 7791 7792@item @emph{Example}: 7793@smallexample 7794program test_ichar 7795 integer i 7796 i = ichar(' ') 7797end program test_ichar 7798@end smallexample 7799 7800@item @emph{Specific names}: 7801@multitable @columnfractions .20 .20 .20 .25 7802@item Name @tab Argument @tab Return type @tab Standard 7803@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later 7804@end multitable 7805 7806@item @emph{Note}: 7807No intrinsic exists to convert between a numeric value and a formatted 7808character string representation -- for instance, given the 7809@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or 7810@code{REAL} value with the value 154, or vice versa. Instead, this 7811functionality is provided by internal-file I/O, as in the following 7812example: 7813@smallexample 7814program read_val 7815 integer value 7816 character(len=10) string, string2 7817 string = '154' 7818 7819 ! Convert a string to a numeric value 7820 read (string,'(I10)') value 7821 print *, value 7822 7823 ! Convert a value to a formatted string 7824 write (string2,'(I10)') value 7825 print *, string2 7826end program read_val 7827@end smallexample 7828 7829@item @emph{See also}: 7830@ref{ACHAR}, @ref{CHAR}, @ref{IACHAR} 7831 7832@end table 7833 7834 7835 7836@node IDATE 7837@section @code{IDATE} --- Get current local time subroutine (day/month/year) 7838@fnindex IDATE 7839@cindex date, current 7840@cindex current date 7841 7842@table @asis 7843@item @emph{Description}: 7844@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the 7845current local time. The day (in the range 1-31), month (in the range 1-12), 7846and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively. 7847The year has four significant digits. 7848 7849This intrinsic routine is provided for backwards compatibility with 7850GNU Fortran 77. In new code, programmers should consider the use of 7851the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 7852standard. 7853 7854@item @emph{Standard}: 7855GNU extension 7856 7857@item @emph{Class}: 7858Subroutine 7859 7860@item @emph{Syntax}: 7861@code{CALL IDATE(VALUES)} 7862 7863@item @emph{Arguments}: 7864@multitable @columnfractions .15 .70 7865@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and 7866the kind shall be the default integer kind. 7867@end multitable 7868 7869@item @emph{Return value}: 7870Does not return anything. 7871 7872@item @emph{Example}: 7873@smallexample 7874program test_idate 7875 integer, dimension(3) :: tarray 7876 call idate(tarray) 7877 print *, tarray(1) 7878 print *, tarray(2) 7879 print *, tarray(3) 7880end program test_idate 7881@end smallexample 7882 7883@item @emph{See also}: 7884@ref{DATE_AND_TIME} 7885@end table 7886 7887 7888@node IEOR 7889@section @code{IEOR} --- Bitwise logical exclusive or 7890@fnindex IEOR 7891@fnindex BIEOR 7892@fnindex IIEOR 7893@fnindex JIEOR 7894@fnindex KIEOR 7895@cindex bitwise logical exclusive or 7896@cindex logical exclusive or, bitwise 7897 7898@table @asis 7899@item @emph{Description}: 7900@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and 7901@var{J}. 7902 7903@item @emph{Standard}: 7904Fortran 95 and later, has overloads that are GNU extensions 7905 7906@item @emph{Class}: 7907Elemental function 7908 7909@item @emph{Syntax}: 7910@code{RESULT = IEOR(I, J)} 7911 7912@item @emph{Arguments}: 7913@multitable @columnfractions .15 .70 7914@item @var{I} @tab The type shall be @code{INTEGER}. 7915@item @var{J} @tab The type shall be @code{INTEGER}, of the same 7916kind as @var{I}. (As a GNU extension, different kinds are also 7917permitted.) 7918@end multitable 7919 7920@item @emph{Return value}: 7921The return type is @code{INTEGER}, of the same kind as the 7922arguments. (If the argument kinds differ, it is of the same kind as 7923the larger argument.) 7924 7925@item @emph{Specific names}: 7926@multitable @columnfractions .20 .20 .20 .25 7927@item Name @tab Argument @tab Return type @tab Standard 7928@item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7929@item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7930@item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7931@item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7932@item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7933@end multitable 7934 7935@item @emph{See also}: 7936@ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 7937@end table 7938 7939 7940 7941@node IERRNO 7942@section @code{IERRNO} --- Get the last system error number 7943@fnindex IERRNO 7944@cindex system, error handling 7945 7946@table @asis 7947@item @emph{Description}: 7948Returns the last system error number, as given by the C @code{errno} 7949variable. 7950 7951@item @emph{Standard}: 7952GNU extension 7953 7954@item @emph{Class}: 7955Function 7956 7957@item @emph{Syntax}: 7958@code{RESULT = IERRNO()} 7959 7960@item @emph{Arguments}: 7961None. 7962 7963@item @emph{Return value}: 7964The return value is of type @code{INTEGER} and of the default integer 7965kind. 7966 7967@item @emph{See also}: 7968@ref{PERROR} 7969@end table 7970 7971 7972 7973@node IMAGE_INDEX 7974@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index 7975@fnindex IMAGE_INDEX 7976@cindex coarray, @code{IMAGE_INDEX} 7977@cindex images, cosubscript to image index conversion 7978 7979@table @asis 7980@item @emph{Description}: 7981Returns the image index belonging to a cosubscript. 7982 7983@item @emph{Standard}: 7984Fortran 2008 and later 7985 7986@item @emph{Class}: 7987Inquiry function. 7988 7989@item @emph{Syntax}: 7990@code{RESULT = IMAGE_INDEX(COARRAY, SUB)} 7991 7992@item @emph{Arguments}: None. 7993@multitable @columnfractions .15 .70 7994@item @var{COARRAY} @tab Coarray of any type. 7995@item @var{SUB} @tab default integer rank-1 array of a size equal to 7996the corank of @var{COARRAY}. 7997@end multitable 7998 7999 8000@item @emph{Return value}: 8001Scalar default integer with the value of the image index which corresponds 8002to the cosubscripts. For invalid cosubscripts the result is zero. 8003 8004@item @emph{Example}: 8005@smallexample 8006INTEGER :: array[2,-1:4,8,*] 8007! Writes 28 (or 0 if there are fewer than 28 images) 8008WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1]) 8009@end smallexample 8010 8011@item @emph{See also}: 8012@ref{THIS_IMAGE}, @ref{NUM_IMAGES} 8013@end table 8014 8015 8016 8017@node INDEX intrinsic 8018@section @code{INDEX} --- Position of a substring within a string 8019@fnindex INDEX 8020@cindex substring position 8021@cindex string, find substring 8022 8023@table @asis 8024@item @emph{Description}: 8025Returns the position of the start of the first occurrence of string 8026@var{SUBSTRING} as a substring in @var{STRING}, counting from one. If 8027@var{SUBSTRING} is not present in @var{STRING}, zero is returned. If 8028the @var{BACK} argument is present and true, the return value is the 8029start of the last occurrence rather than the first. 8030 8031@item @emph{Standard}: 8032Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8033 8034@item @emph{Class}: 8035Elemental function 8036 8037@item @emph{Syntax}: 8038@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])} 8039 8040@item @emph{Arguments}: 8041@multitable @columnfractions .15 .70 8042@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with 8043@code{INTENT(IN)} 8044@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with 8045@code{INTENT(IN)} 8046@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with 8047@code{INTENT(IN)} 8048@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8049expression indicating the kind parameter of the result. 8050@end multitable 8051 8052@item @emph{Return value}: 8053The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8054@var{KIND} is absent, the return value is of default integer kind. 8055 8056@item @emph{Specific names}: 8057@multitable @columnfractions .20 .20 .20 .25 8058@item Name @tab Argument @tab Return type @tab Standard 8059@item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later 8060@end multitable 8061 8062@item @emph{See also}: 8063@ref{SCAN}, @ref{VERIFY} 8064@end table 8065 8066 8067 8068@node INT 8069@section @code{INT} --- Convert to integer type 8070@fnindex INT 8071@fnindex IFIX 8072@fnindex IDINT 8073@cindex conversion, to integer 8074 8075@table @asis 8076@item @emph{Description}: 8077Convert to integer type 8078 8079@item @emph{Standard}: 8080Fortran 77 and later 8081 8082@item @emph{Class}: 8083Elemental function 8084 8085@item @emph{Syntax}: 8086@code{RESULT = INT(A [, KIND))} 8087 8088@item @emph{Arguments}: 8089@multitable @columnfractions .15 .70 8090@item @var{A} @tab Shall be of type @code{INTEGER}, 8091@code{REAL}, or @code{COMPLEX}. 8092@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8093expression indicating the kind parameter of the result. 8094@end multitable 8095 8096@item @emph{Return value}: 8097These functions return a @code{INTEGER} variable or array under 8098the following rules: 8099 8100@table @asis 8101@item (A) 8102If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 8103@item (B) 8104If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} 8105equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer 8106whose magnitude is the largest integer that does not exceed the magnitude 8107of @var{A} and whose sign is the same as the sign of @var{A}. 8108@item (C) 8109If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}. 8110@end table 8111 8112@item @emph{Example}: 8113@smallexample 8114program test_int 8115 integer :: i = 42 8116 complex :: z = (-3.7, 1.0) 8117 print *, int(i) 8118 print *, int(z), int(z,8) 8119end program 8120@end smallexample 8121 8122@item @emph{Specific names}: 8123@multitable @columnfractions .20 .20 .20 .25 8124@item Name @tab Argument @tab Return type @tab Standard 8125@item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8126@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8127@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 8128@end multitable 8129 8130@end table 8131 8132 8133@node INT2 8134@section @code{INT2} --- Convert to 16-bit integer type 8135@fnindex INT2 8136@fnindex SHORT 8137@cindex conversion, to integer 8138 8139@table @asis 8140@item @emph{Description}: 8141Convert to a @code{KIND=2} integer type. This is equivalent to the 8142standard @code{INT} intrinsic with an optional argument of 8143@code{KIND=2}, and is only included for backwards compatibility. 8144 8145The @code{SHORT} intrinsic is equivalent to @code{INT2}. 8146 8147@item @emph{Standard}: 8148GNU extension 8149 8150@item @emph{Class}: 8151Elemental function 8152 8153@item @emph{Syntax}: 8154@code{RESULT = INT2(A)} 8155 8156@item @emph{Arguments}: 8157@multitable @columnfractions .15 .70 8158@item @var{A} @tab Shall be of type @code{INTEGER}, 8159@code{REAL}, or @code{COMPLEX}. 8160@end multitable 8161 8162@item @emph{Return value}: 8163The return value is a @code{INTEGER(2)} variable. 8164 8165@item @emph{See also}: 8166@ref{INT}, @ref{INT8}, @ref{LONG} 8167@end table 8168 8169 8170 8171@node INT8 8172@section @code{INT8} --- Convert to 64-bit integer type 8173@fnindex INT8 8174@cindex conversion, to integer 8175 8176@table @asis 8177@item @emph{Description}: 8178Convert to a @code{KIND=8} integer type. This is equivalent to the 8179standard @code{INT} intrinsic with an optional argument of 8180@code{KIND=8}, and is only included for backwards compatibility. 8181 8182@item @emph{Standard}: 8183GNU extension 8184 8185@item @emph{Class}: 8186Elemental function 8187 8188@item @emph{Syntax}: 8189@code{RESULT = INT8(A)} 8190 8191@item @emph{Arguments}: 8192@multitable @columnfractions .15 .70 8193@item @var{A} @tab Shall be of type @code{INTEGER}, 8194@code{REAL}, or @code{COMPLEX}. 8195@end multitable 8196 8197@item @emph{Return value}: 8198The return value is a @code{INTEGER(8)} variable. 8199 8200@item @emph{See also}: 8201@ref{INT}, @ref{INT2}, @ref{LONG} 8202@end table 8203 8204 8205 8206@node IOR 8207@section @code{IOR} --- Bitwise logical or 8208@fnindex IOR 8209@fnindex BIOR 8210@fnindex IIOR 8211@fnindex JIOR 8212@fnindex KIOR 8213@cindex bitwise logical or 8214@cindex logical or, bitwise 8215 8216@table @asis 8217@item @emph{Description}: 8218@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and 8219@var{J}. 8220 8221@item @emph{Standard}: 8222Fortran 95 and later, has overloads that are GNU extensions 8223 8224@item @emph{Class}: 8225Elemental function 8226 8227@item @emph{Syntax}: 8228@code{RESULT = IOR(I, J)} 8229 8230@item @emph{Arguments}: 8231@multitable @columnfractions .15 .70 8232@item @var{I} @tab The type shall be @code{INTEGER}. 8233@item @var{J} @tab The type shall be @code{INTEGER}, of the same 8234kind as @var{I}. (As a GNU extension, different kinds are also 8235permitted.) 8236@end multitable 8237 8238@item @emph{Return value}: 8239The return type is @code{INTEGER}, of the same kind as the 8240arguments. (If the argument kinds differ, it is of the same kind as 8241the larger argument.) 8242 8243@item @emph{Specific names}: 8244@multitable @columnfractions .20 .20 .20 .25 8245@item Name @tab Argument @tab Return type @tab Standard 8246@item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 8247@item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8248@item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8249@item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8250@item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8251@end multitable 8252 8253@item @emph{See also}: 8254@ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 8255@end table 8256 8257 8258 8259@node IPARITY 8260@section @code{IPARITY} --- Bitwise XOR of array elements 8261@fnindex IPARITY 8262@cindex array, parity 8263@cindex array, XOR 8264@cindex bits, XOR of array elements 8265 8266@table @asis 8267@item @emph{Description}: 8268Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along 8269dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 8270 8271@item @emph{Standard}: 8272Fortran 2008 and later 8273 8274@item @emph{Class}: 8275Transformational function 8276 8277@item @emph{Syntax}: 8278@multitable @columnfractions .80 8279@item @code{RESULT = IPARITY(ARRAY[, MASK])} 8280@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])} 8281@end multitable 8282 8283@item @emph{Arguments}: 8284@multitable @columnfractions .15 .70 8285@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 8286@item @var{DIM} @tab (Optional) shall be a scalar of type 8287@code{INTEGER} with a value in the range from 1 to n, where n 8288equals the rank of @var{ARRAY}. 8289@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 8290and either be a scalar or an array of the same shape as @var{ARRAY}. 8291@end multitable 8292 8293@item @emph{Return value}: 8294The result is of the same type as @var{ARRAY}. 8295 8296If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in 8297@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 8298the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 8299dimension @var{DIM} dropped is returned. 8300 8301@item @emph{Example}: 8302@smallexample 8303PROGRAM test_iparity 8304 INTEGER(1) :: a(2) 8305 8306 a(1) = b'00100100' 8307 a(2) = b'01101010' 8308 8309 ! prints 01001110 8310 PRINT '(b8.8)', IPARITY(a) 8311END PROGRAM 8312@end smallexample 8313 8314@item @emph{See also}: 8315@ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY} 8316@end table 8317 8318 8319 8320@node IRAND 8321@section @code{IRAND} --- Integer pseudo-random number 8322@fnindex IRAND 8323@cindex random number generation 8324 8325@table @asis 8326@item @emph{Description}: 8327@code{IRAND(FLAG)} returns a pseudo-random number from a uniform 8328distribution between 0 and a system-dependent limit (which is in most 8329cases 2147483647). If @var{FLAG} is 0, the next number 8330in the current sequence is returned; if @var{FLAG} is 1, the generator 8331is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 8332it is used as a new seed with @code{SRAND}. 8333 8334This intrinsic routine is provided for backwards compatibility with 8335GNU Fortran 77. It implements a simple modulo generator as provided 8336by @command{g77}. For new code, one should consider the use of 8337@ref{RANDOM_NUMBER} as it implements a superior algorithm. 8338 8339@item @emph{Standard}: 8340GNU extension 8341 8342@item @emph{Class}: 8343Function 8344 8345@item @emph{Syntax}: 8346@code{RESULT = IRAND(I)} 8347 8348@item @emph{Arguments}: 8349@multitable @columnfractions .15 .70 8350@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 8351@end multitable 8352 8353@item @emph{Return value}: 8354The return value is of @code{INTEGER(kind=4)} type. 8355 8356@item @emph{Example}: 8357@smallexample 8358program test_irand 8359 integer,parameter :: seed = 86456 8360 8361 call srand(seed) 8362 print *, irand(), irand(), irand(), irand() 8363 print *, irand(seed), irand(), irand(), irand() 8364end program test_irand 8365@end smallexample 8366 8367@end table 8368 8369 8370 8371@node IS_IOSTAT_END 8372@section @code{IS_IOSTAT_END} --- Test for end-of-file value 8373@fnindex IS_IOSTAT_END 8374@cindex @code{IOSTAT}, end of file 8375 8376@table @asis 8377@item @emph{Description}: 8378@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O 8379status ``end of file''. The function is equivalent to comparing the variable 8380with the @code{IOSTAT_END} parameter of the intrinsic module 8381@code{ISO_FORTRAN_ENV}. 8382 8383@item @emph{Standard}: 8384Fortran 2003 and later 8385 8386@item @emph{Class}: 8387Elemental function 8388 8389@item @emph{Syntax}: 8390@code{RESULT = IS_IOSTAT_END(I)} 8391 8392@item @emph{Arguments}: 8393@multitable @columnfractions .15 .70 8394@item @var{I} @tab Shall be of the type @code{INTEGER}. 8395@end multitable 8396 8397@item @emph{Return value}: 8398Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8399@var{I} has the value which indicates an end of file condition for 8400@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8401 8402@item @emph{Example}: 8403@smallexample 8404PROGRAM iostat 8405 IMPLICIT NONE 8406 INTEGER :: stat, i 8407 OPEN(88, FILE='test.dat') 8408 READ(88, *, IOSTAT=stat) i 8409 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE' 8410END PROGRAM 8411@end smallexample 8412@end table 8413 8414 8415 8416@node IS_IOSTAT_EOR 8417@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value 8418@fnindex IS_IOSTAT_EOR 8419@cindex @code{IOSTAT}, end of record 8420 8421@table @asis 8422@item @emph{Description}: 8423@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O 8424status ``end of record''. The function is equivalent to comparing the 8425variable with the @code{IOSTAT_EOR} parameter of the intrinsic module 8426@code{ISO_FORTRAN_ENV}. 8427 8428@item @emph{Standard}: 8429Fortran 2003 and later 8430 8431@item @emph{Class}: 8432Elemental function 8433 8434@item @emph{Syntax}: 8435@code{RESULT = IS_IOSTAT_EOR(I)} 8436 8437@item @emph{Arguments}: 8438@multitable @columnfractions .15 .70 8439@item @var{I} @tab Shall be of the type @code{INTEGER}. 8440@end multitable 8441 8442@item @emph{Return value}: 8443Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8444@var{I} has the value which indicates an end of file condition for 8445@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8446 8447@item @emph{Example}: 8448@smallexample 8449PROGRAM iostat 8450 IMPLICIT NONE 8451 INTEGER :: stat, i(50) 8452 OPEN(88, FILE='test.dat', FORM='UNFORMATTED') 8453 READ(88, IOSTAT=stat) i 8454 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD' 8455END PROGRAM 8456@end smallexample 8457@end table 8458 8459 8460 8461@node ISATTY 8462@section @code{ISATTY} --- Whether a unit is a terminal device. 8463@fnindex ISATTY 8464@cindex system, terminal 8465 8466@table @asis 8467@item @emph{Description}: 8468Determine whether a unit is connected to a terminal device. 8469 8470@item @emph{Standard}: 8471GNU extension 8472 8473@item @emph{Class}: 8474Function 8475 8476@item @emph{Syntax}: 8477@code{RESULT = ISATTY(UNIT)} 8478 8479@item @emph{Arguments}: 8480@multitable @columnfractions .15 .70 8481@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 8482@end multitable 8483 8484@item @emph{Return value}: 8485Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal 8486device, @code{.FALSE.} otherwise. 8487 8488@item @emph{Example}: 8489@smallexample 8490PROGRAM test_isatty 8491 INTEGER(kind=1) :: unit 8492 DO unit = 1, 10 8493 write(*,*) isatty(unit=unit) 8494 END DO 8495END PROGRAM 8496@end smallexample 8497@item @emph{See also}: 8498@ref{TTYNAM} 8499@end table 8500 8501 8502 8503@node ISHFT 8504@section @code{ISHFT} --- Shift bits 8505@fnindex ISHFT 8506@fnindex BSHFT 8507@fnindex IISHFT 8508@fnindex JISHFT 8509@fnindex KISHFT 8510@cindex bits, shift 8511 8512@table @asis 8513@item @emph{Description}: 8514@code{ISHFT} returns a value corresponding to @var{I} with all of the 8515bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than 8516zero corresponds to a left shift, a value of zero corresponds to no 8517shift, and a value less than zero corresponds to a right shift. If the 8518absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the 8519value is undefined. Bits shifted out from the left end or right end are 8520lost; zeros are shifted in from the opposite end. 8521 8522@item @emph{Standard}: 8523Fortran 95 and later, has overloads that are GNU extensions 8524 8525@item @emph{Class}: 8526Elemental function 8527 8528@item @emph{Syntax}: 8529@code{RESULT = ISHFT(I, SHIFT)} 8530 8531@item @emph{Arguments}: 8532@multitable @columnfractions .15 .70 8533@item @var{I} @tab The type shall be @code{INTEGER}. 8534@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8535@end multitable 8536 8537@item @emph{Return value}: 8538The return value is of type @code{INTEGER} and of the same kind as 8539@var{I}. 8540 8541@item @emph{Specific names}: 8542@multitable @columnfractions .20 .20 .20 .25 8543@item Name @tab Argument @tab Return type @tab Standard 8544@item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 8545@item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8546@item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8547@item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8548@item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8549@end multitable 8550 8551@item @emph{See also}: 8552@ref{ISHFTC} 8553@end table 8554 8555 8556 8557@node ISHFTC 8558@section @code{ISHFTC} --- Shift bits circularly 8559@fnindex ISHFTC 8560@fnindex BSHFTC 8561@fnindex IISHFTC 8562@fnindex JISHFTC 8563@fnindex KISHFTC 8564@cindex bits, shift circular 8565 8566@table @asis 8567@item @emph{Description}: 8568@code{ISHFTC} returns a value corresponding to @var{I} with the 8569rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that 8570is, bits shifted out one end are shifted into the opposite end. A value 8571of @var{SHIFT} greater than zero corresponds to a left shift, a value of 8572zero corresponds to no shift, and a value less than zero corresponds to 8573a right shift. The absolute value of @var{SHIFT} must be less than 8574@var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be 8575equivalent to @code{BIT_SIZE(I)}. 8576 8577@item @emph{Standard}: 8578Fortran 95 and later, has overloads that are GNU extensions 8579 8580@item @emph{Class}: 8581Elemental function 8582 8583@item @emph{Syntax}: 8584@code{RESULT = ISHFTC(I, SHIFT [, SIZE])} 8585 8586@item @emph{Arguments}: 8587@multitable @columnfractions .15 .70 8588@item @var{I} @tab The type shall be @code{INTEGER}. 8589@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8590@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER}; 8591the value must be greater than zero and less than or equal to 8592@code{BIT_SIZE(I)}. 8593@end multitable 8594 8595@item @emph{Return value}: 8596The return value is of type @code{INTEGER} and of the same kind as 8597@var{I}. 8598 8599@item @emph{Specific names}: 8600@multitable @columnfractions .20 .20 .20 .25 8601@item Name @tab Argument @tab Return type @tab Standard 8602@item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 8603@item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8604@item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8605@item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8606@item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8607@end multitable 8608 8609@item @emph{See also}: 8610@ref{ISHFT} 8611@end table 8612 8613 8614 8615@node ISNAN 8616@section @code{ISNAN} --- Test for a NaN 8617@fnindex ISNAN 8618@cindex IEEE, ISNAN 8619 8620@table @asis 8621@item @emph{Description}: 8622@code{ISNAN} tests whether a floating-point value is an IEEE 8623Not-a-Number (NaN). 8624@item @emph{Standard}: 8625GNU extension 8626 8627@item @emph{Class}: 8628Elemental function 8629 8630@item @emph{Syntax}: 8631@code{ISNAN(X)} 8632 8633@item @emph{Arguments}: 8634@multitable @columnfractions .15 .70 8635@item @var{X} @tab Variable of the type @code{REAL}. 8636 8637@end multitable 8638 8639@item @emph{Return value}: 8640Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE} 8641if @var{X} is a NaN and @code{FALSE} otherwise. 8642 8643@item @emph{Example}: 8644@smallexample 8645program test_nan 8646 implicit none 8647 real :: x 8648 x = -1.0 8649 x = sqrt(x) 8650 if (isnan(x)) stop '"x" is a NaN' 8651end program test_nan 8652@end smallexample 8653@end table 8654 8655 8656 8657@node ITIME 8658@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) 8659@fnindex ITIME 8660@cindex time, current 8661@cindex current time 8662 8663@table @asis 8664@item @emph{Description}: 8665@code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the 8666current local time. The hour (in the range 1-24), minute (in the range 1-60), 8667and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES}, 8668respectively. 8669 8670This intrinsic routine is provided for backwards compatibility with 8671GNU Fortran 77. In new code, programmers should consider the use of 8672the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 8673standard. 8674 8675@item @emph{Standard}: 8676GNU extension 8677 8678@item @emph{Class}: 8679Subroutine 8680 8681@item @emph{Syntax}: 8682@code{CALL ITIME(VALUES)} 8683 8684@item @emph{Arguments}: 8685@multitable @columnfractions .15 .70 8686@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} 8687and the kind shall be the default integer kind. 8688@end multitable 8689 8690@item @emph{Return value}: 8691Does not return anything. 8692 8693 8694@item @emph{Example}: 8695@smallexample 8696program test_itime 8697 integer, dimension(3) :: tarray 8698 call itime(tarray) 8699 print *, tarray(1) 8700 print *, tarray(2) 8701 print *, tarray(3) 8702end program test_itime 8703@end smallexample 8704 8705@item @emph{See also}: 8706@ref{DATE_AND_TIME} 8707@end table 8708 8709 8710 8711@node KILL 8712@section @code{KILL} --- Send a signal to a process 8713@fnindex KILL 8714 8715@table @asis 8716@item @emph{Description}: 8717@item @emph{Standard}: 8718Sends the signal specified by @var{SIG} to the process @var{PID}. 8719See @code{kill(2)}. 8720 8721This intrinsic is provided in both subroutine and function forms; 8722however, only one form can be used in any given program unit. 8723 8724@item @emph{Class}: 8725Subroutine, function 8726 8727@item @emph{Syntax}: 8728@multitable @columnfractions .80 8729@item @code{CALL KILL(PID, SIG [, STATUS])} 8730@item @code{STATUS = KILL(PID, SIG)} 8731@end multitable 8732 8733@item @emph{Arguments}: 8734@multitable @columnfractions .15 .70 8735@item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 8736@item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 8737@item @var{STATUS} @tab [Subroutine](Optional) 8738Shall be a scalar @code{INTEGER}. 8739Returns 0 on success; otherwise a system-specific error code is returned. 8740@item @var{STATUS} @tab [Function] The kind type parameter is that of 8741@code{pid}. 8742Returns 0 on success; otherwise a system-specific error code is returned. 8743@end multitable 8744 8745@item @emph{See also}: 8746@ref{ABORT}, @ref{EXIT} 8747@end table 8748 8749 8750@node KIND 8751@section @code{KIND} --- Kind of an entity 8752@fnindex KIND 8753@cindex kind 8754 8755@table @asis 8756@item @emph{Description}: 8757@code{KIND(X)} returns the kind value of the entity @var{X}. 8758 8759@item @emph{Standard}: 8760Fortran 95 and later 8761 8762@item @emph{Class}: 8763Inquiry function 8764 8765@item @emph{Syntax}: 8766@code{K = KIND(X)} 8767 8768@item @emph{Arguments}: 8769@multitable @columnfractions .15 .70 8770@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER}, 8771@code{REAL}, @code{COMPLEX} or @code{CHARACTER}. 8772@end multitable 8773 8774@item @emph{Return value}: 8775The return value is a scalar of type @code{INTEGER} and of the default 8776integer kind. 8777 8778@item @emph{Example}: 8779@smallexample 8780program test_kind 8781 integer,parameter :: kc = kind(' ') 8782 integer,parameter :: kl = kind(.true.) 8783 8784 print *, "The default character kind is ", kc 8785 print *, "The default logical kind is ", kl 8786end program test_kind 8787@end smallexample 8788 8789@end table 8790 8791 8792 8793@node LBOUND 8794@section @code{LBOUND} --- Lower dimension bounds of an array 8795@fnindex LBOUND 8796@cindex array, lower bound 8797 8798@table @asis 8799@item @emph{Description}: 8800Returns the lower bounds of an array, or a single lower bound 8801along the @var{DIM} dimension. 8802@item @emph{Standard}: 8803Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 8804 8805@item @emph{Class}: 8806Inquiry function 8807 8808@item @emph{Syntax}: 8809@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])} 8810 8811@item @emph{Arguments}: 8812@multitable @columnfractions .15 .70 8813@item @var{ARRAY} @tab Shall be an array, of any type. 8814@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 8815@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8816expression indicating the kind parameter of the result. 8817@end multitable 8818 8819@item @emph{Return value}: 8820The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8821@var{KIND} is absent, the return value is of default integer kind. 8822If @var{DIM} is absent, the result is an array of the lower bounds of 8823@var{ARRAY}. If @var{DIM} is present, the result is a scalar 8824corresponding to the lower bound of the array along that dimension. If 8825@var{ARRAY} is an expression rather than a whole array or array 8826structure component, or if it has a zero extent along the relevant 8827dimension, the lower bound is taken to be 1. 8828 8829@item @emph{See also}: 8830@ref{UBOUND}, @ref{LCOBOUND} 8831@end table 8832 8833 8834 8835@node LCOBOUND 8836@section @code{LCOBOUND} --- Lower codimension bounds of an array 8837@fnindex LCOBOUND 8838@cindex coarray, lower bound 8839 8840@table @asis 8841@item @emph{Description}: 8842Returns the lower bounds of a coarray, or a single lower cobound 8843along the @var{DIM} codimension. 8844@item @emph{Standard}: 8845Fortran 2008 and later 8846 8847@item @emph{Class}: 8848Inquiry function 8849 8850@item @emph{Syntax}: 8851@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])} 8852 8853@item @emph{Arguments}: 8854@multitable @columnfractions .15 .70 8855@item @var{ARRAY} @tab Shall be an coarray, of any type. 8856@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 8857@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8858expression indicating the kind parameter of the result. 8859@end multitable 8860 8861@item @emph{Return value}: 8862The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8863@var{KIND} is absent, the return value is of default integer kind. 8864If @var{DIM} is absent, the result is an array of the lower cobounds of 8865@var{COARRAY}. If @var{DIM} is present, the result is a scalar 8866corresponding to the lower cobound of the array along that codimension. 8867 8868@item @emph{See also}: 8869@ref{UCOBOUND}, @ref{LBOUND} 8870@end table 8871 8872 8873 8874@node LEADZ 8875@section @code{LEADZ} --- Number of leading zero bits of an integer 8876@fnindex LEADZ 8877@cindex zero bits 8878 8879@table @asis 8880@item @emph{Description}: 8881@code{LEADZ} returns the number of leading zero bits of an integer. 8882 8883@item @emph{Standard}: 8884Fortran 2008 and later 8885 8886@item @emph{Class}: 8887Elemental function 8888 8889@item @emph{Syntax}: 8890@code{RESULT = LEADZ(I)} 8891 8892@item @emph{Arguments}: 8893@multitable @columnfractions .15 .70 8894@item @var{I} @tab Shall be of type @code{INTEGER}. 8895@end multitable 8896 8897@item @emph{Return value}: 8898The type of the return value is the default @code{INTEGER}. 8899If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 8900 8901@item @emph{Example}: 8902@smallexample 8903PROGRAM test_leadz 8904 WRITE (*,*) BIT_SIZE(1) ! prints 32 8905 WRITE (*,*) LEADZ(1) ! prints 31 8906END PROGRAM 8907@end smallexample 8908 8909@item @emph{See also}: 8910@ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR} 8911@end table 8912 8913 8914 8915@node LEN 8916@section @code{LEN} --- Length of a character entity 8917@fnindex LEN 8918@cindex string, length 8919 8920@table @asis 8921@item @emph{Description}: 8922Returns the length of a character string. If @var{STRING} is an array, 8923the length of an element of @var{STRING} is returned. Note that 8924@var{STRING} need not be defined when this intrinsic is invoked, since 8925only the length, not the content, of @var{STRING} is needed. 8926 8927@item @emph{Standard}: 8928Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8929 8930@item @emph{Class}: 8931Inquiry function 8932 8933@item @emph{Syntax}: 8934@code{L = LEN(STRING [, KIND])} 8935 8936@item @emph{Arguments}: 8937@multitable @columnfractions .15 .70 8938@item @var{STRING} @tab Shall be a scalar or array of type 8939@code{CHARACTER}, with @code{INTENT(IN)} 8940@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8941expression indicating the kind parameter of the result. 8942@end multitable 8943 8944@item @emph{Return value}: 8945The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8946@var{KIND} is absent, the return value is of default integer kind. 8947 8948 8949@item @emph{Specific names}: 8950@multitable @columnfractions .20 .20 .20 .25 8951@item Name @tab Argument @tab Return type @tab Standard 8952@item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later 8953@end multitable 8954 8955 8956@item @emph{See also}: 8957@ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR} 8958@end table 8959 8960 8961 8962@node LEN_TRIM 8963@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters 8964@fnindex LEN_TRIM 8965@cindex string, length, without trailing whitespace 8966 8967@table @asis 8968@item @emph{Description}: 8969Returns the length of a character string, ignoring any trailing blanks. 8970 8971@item @emph{Standard}: 8972Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 8973 8974@item @emph{Class}: 8975Elemental function 8976 8977@item @emph{Syntax}: 8978@code{RESULT = LEN_TRIM(STRING [, KIND])} 8979 8980@item @emph{Arguments}: 8981@multitable @columnfractions .15 .70 8982@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 8983with @code{INTENT(IN)} 8984@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8985expression indicating the kind parameter of the result. 8986@end multitable 8987 8988@item @emph{Return value}: 8989The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8990@var{KIND} is absent, the return value is of default integer kind. 8991 8992@item @emph{See also}: 8993@ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR} 8994@end table 8995 8996 8997 8998@node LGE 8999@section @code{LGE} --- Lexical greater than or equal 9000@fnindex LGE 9001@cindex lexical comparison of strings 9002@cindex string, comparison 9003 9004@table @asis 9005@item @emph{Description}: 9006Determines whether one string is lexically greater than or equal to 9007another string, where the two strings are interpreted as containing 9008ASCII character codes. If the String A and String B are not the same 9009length, the shorter is compared as if spaces were appended to it to form 9010a value that has the same length as the longer. 9011 9012In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9013@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9014operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9015that the latter use the processor's character ordering (which is not 9016ASCII on some targets), whereas the former always use the ASCII 9017ordering. 9018 9019@item @emph{Standard}: 9020Fortran 77 and later 9021 9022@item @emph{Class}: 9023Elemental function 9024 9025@item @emph{Syntax}: 9026@code{RESULT = LGE(STRING_A, STRING_B)} 9027 9028@item @emph{Arguments}: 9029@multitable @columnfractions .15 .70 9030@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9031@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9032@end multitable 9033 9034@item @emph{Return value}: 9035Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.} 9036otherwise, based on the ASCII ordering. 9037 9038@item @emph{Specific names}: 9039@multitable @columnfractions .20 .20 .20 .25 9040@item Name @tab Argument @tab Return type @tab Standard 9041@item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9042@end multitable 9043 9044@item @emph{See also}: 9045@ref{LGT}, @ref{LLE}, @ref{LLT} 9046@end table 9047 9048 9049 9050@node LGT 9051@section @code{LGT} --- Lexical greater than 9052@fnindex LGT 9053@cindex lexical comparison of strings 9054@cindex string, comparison 9055 9056@table @asis 9057@item @emph{Description}: 9058Determines whether one string is lexically greater than another string, 9059where the two strings are interpreted as containing ASCII character 9060codes. If the String A and String B are not the same length, the 9061shorter is compared as if spaces were appended to it to form a value 9062that has the same length as the longer. 9063 9064In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9065@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9066operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9067that the latter use the processor's character ordering (which is not 9068ASCII on some targets), whereas the former always use the ASCII 9069ordering. 9070 9071@item @emph{Standard}: 9072Fortran 77 and later 9073 9074@item @emph{Class}: 9075Elemental function 9076 9077@item @emph{Syntax}: 9078@code{RESULT = LGT(STRING_A, STRING_B)} 9079 9080@item @emph{Arguments}: 9081@multitable @columnfractions .15 .70 9082@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9083@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9084@end multitable 9085 9086@item @emph{Return value}: 9087Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.} 9088otherwise, based on the ASCII ordering. 9089 9090@item @emph{Specific names}: 9091@multitable @columnfractions .20 .20 .20 .25 9092@item Name @tab Argument @tab Return type @tab Standard 9093@item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9094@end multitable 9095 9096@item @emph{See also}: 9097@ref{LGE}, @ref{LLE}, @ref{LLT} 9098@end table 9099 9100 9101 9102@node LINK 9103@section @code{LINK} --- Create a hard link 9104@fnindex LINK 9105@cindex file system, create link 9106@cindex file system, hard link 9107 9108@table @asis 9109@item @emph{Description}: 9110Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null 9111character (@code{CHAR(0)}) can be used to mark the end of the names in 9112@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 9113names are ignored. If the @var{STATUS} argument is supplied, it 9114contains 0 on success or a nonzero error code upon return; see 9115@code{link(2)}. 9116 9117This intrinsic is provided in both subroutine and function forms; 9118however, only one form can be used in any given program unit. 9119 9120@item @emph{Standard}: 9121GNU extension 9122 9123@item @emph{Class}: 9124Subroutine, function 9125 9126@item @emph{Syntax}: 9127@multitable @columnfractions .80 9128@item @code{CALL LINK(PATH1, PATH2 [, STATUS])} 9129@item @code{STATUS = LINK(PATH1, PATH2)} 9130@end multitable 9131 9132@item @emph{Arguments}: 9133@multitable @columnfractions .15 .70 9134@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 9135@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 9136@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 9137@end multitable 9138 9139@item @emph{See also}: 9140@ref{SYMLNK}, @ref{UNLINK} 9141@end table 9142 9143 9144 9145@node LLE 9146@section @code{LLE} --- Lexical less than or equal 9147@fnindex LLE 9148@cindex lexical comparison of strings 9149@cindex string, comparison 9150 9151@table @asis 9152@item @emph{Description}: 9153Determines whether one string is lexically less than or equal to another 9154string, where the two strings are interpreted as containing ASCII 9155character codes. If the String A and String B are not the same length, 9156the shorter is compared as if spaces were appended to it to form a value 9157that has the same length as the longer. 9158 9159In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9160@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9161operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9162that the latter use the processor's character ordering (which is not 9163ASCII on some targets), whereas the former always use the ASCII 9164ordering. 9165 9166@item @emph{Standard}: 9167Fortran 77 and later 9168 9169@item @emph{Class}: 9170Elemental function 9171 9172@item @emph{Syntax}: 9173@code{RESULT = LLE(STRING_A, STRING_B)} 9174 9175@item @emph{Arguments}: 9176@multitable @columnfractions .15 .70 9177@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9178@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9179@end multitable 9180 9181@item @emph{Return value}: 9182Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.} 9183otherwise, based on the ASCII ordering. 9184 9185@item @emph{Specific names}: 9186@multitable @columnfractions .20 .20 .20 .25 9187@item Name @tab Argument @tab Return type @tab Standard 9188@item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9189@end multitable 9190 9191@item @emph{See also}: 9192@ref{LGE}, @ref{LGT}, @ref{LLT} 9193@end table 9194 9195 9196 9197@node LLT 9198@section @code{LLT} --- Lexical less than 9199@fnindex LLT 9200@cindex lexical comparison of strings 9201@cindex string, comparison 9202 9203@table @asis 9204@item @emph{Description}: 9205Determines whether one string is lexically less than another string, 9206where the two strings are interpreted as containing ASCII character 9207codes. If the String A and String B are not the same length, the 9208shorter is compared as if spaces were appended to it to form a value 9209that has the same length as the longer. 9210 9211In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9212@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9213operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9214that the latter use the processor's character ordering (which is not 9215ASCII on some targets), whereas the former always use the ASCII 9216ordering. 9217 9218@item @emph{Standard}: 9219Fortran 77 and later 9220 9221@item @emph{Class}: 9222Elemental function 9223 9224@item @emph{Syntax}: 9225@code{RESULT = LLT(STRING_A, STRING_B)} 9226 9227@item @emph{Arguments}: 9228@multitable @columnfractions .15 .70 9229@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9230@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9231@end multitable 9232 9233@item @emph{Return value}: 9234Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.} 9235otherwise, based on the ASCII ordering. 9236 9237@item @emph{Specific names}: 9238@multitable @columnfractions .20 .20 .20 .25 9239@item Name @tab Argument @tab Return type @tab Standard 9240@item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9241@end multitable 9242 9243@item @emph{See also}: 9244@ref{LGE}, @ref{LGT}, @ref{LLE} 9245@end table 9246 9247 9248 9249@node LNBLNK 9250@section @code{LNBLNK} --- Index of the last non-blank character in a string 9251@fnindex LNBLNK 9252@cindex string, find non-blank character 9253 9254@table @asis 9255@item @emph{Description}: 9256Returns the length of a character string, ignoring any trailing blanks. 9257This is identical to the standard @code{LEN_TRIM} intrinsic, and is only 9258included for backwards compatibility. 9259 9260@item @emph{Standard}: 9261GNU extension 9262 9263@item @emph{Class}: 9264Elemental function 9265 9266@item @emph{Syntax}: 9267@code{RESULT = LNBLNK(STRING)} 9268 9269@item @emph{Arguments}: 9270@multitable @columnfractions .15 .70 9271@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9272with @code{INTENT(IN)} 9273@end multitable 9274 9275@item @emph{Return value}: 9276The return value is of @code{INTEGER(kind=4)} type. 9277 9278@item @emph{See also}: 9279@ref{INDEX intrinsic}, @ref{LEN_TRIM} 9280@end table 9281 9282 9283 9284@node LOC 9285@section @code{LOC} --- Returns the address of a variable 9286@fnindex LOC 9287@cindex location of a variable in memory 9288 9289@table @asis 9290@item @emph{Description}: 9291@code{LOC(X)} returns the address of @var{X} as an integer. 9292 9293@item @emph{Standard}: 9294GNU extension 9295 9296@item @emph{Class}: 9297Inquiry function 9298 9299@item @emph{Syntax}: 9300@code{RESULT = LOC(X)} 9301 9302@item @emph{Arguments}: 9303@multitable @columnfractions .15 .70 9304@item @var{X} @tab Variable of any type. 9305@end multitable 9306 9307@item @emph{Return value}: 9308The return value is of type @code{INTEGER}, with a @code{KIND} 9309corresponding to the size (in bytes) of a memory address on the target 9310machine. 9311 9312@item @emph{Example}: 9313@smallexample 9314program test_loc 9315 integer :: i 9316 real :: r 9317 i = loc(r) 9318 print *, i 9319end program test_loc 9320@end smallexample 9321@end table 9322 9323 9324 9325@node LOG 9326@section @code{LOG} --- Natural logarithm function 9327@fnindex LOG 9328@fnindex ALOG 9329@fnindex DLOG 9330@fnindex CLOG 9331@fnindex ZLOG 9332@fnindex CDLOG 9333@cindex exponential function, inverse 9334@cindex logarithm function 9335@cindex natural logarithm function 9336 9337@table @asis 9338@item @emph{Description}: 9339@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the 9340logarithm to the base @math{e}. 9341 9342@item @emph{Standard}: 9343Fortran 77 and later 9344 9345@item @emph{Class}: 9346Elemental function 9347 9348@item @emph{Syntax}: 9349@code{RESULT = LOG(X)} 9350 9351@item @emph{Arguments}: 9352@multitable @columnfractions .15 .70 9353@item @var{X} @tab The type shall be @code{REAL} or 9354@code{COMPLEX}. 9355@end multitable 9356 9357@item @emph{Return value}: 9358The return value is of type @code{REAL} or @code{COMPLEX}. 9359The kind type parameter is the same as @var{X}. 9360If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range 9361@math{-\pi < \omega \leq \pi}. 9362 9363@item @emph{Example}: 9364@smallexample 9365program test_log 9366 real(8) :: x = 2.7182818284590451_8 9367 complex :: z = (1.0, 2.0) 9368 x = log(x) ! will yield (approximately) 1 9369 z = log(z) 9370end program test_log 9371@end smallexample 9372 9373@item @emph{Specific names}: 9374@multitable @columnfractions .20 .20 .20 .25 9375@item Name @tab Argument @tab Return type @tab Standard 9376@item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu 9377@item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu 9378@item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu 9379@item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 9380@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 9381@end multitable 9382@end table 9383 9384 9385 9386@node LOG10 9387@section @code{LOG10} --- Base 10 logarithm function 9388@fnindex LOG10 9389@fnindex ALOG10 9390@fnindex DLOG10 9391@cindex exponential function, inverse 9392@cindex logarithm function with base 10 9393@cindex base 10 logarithm function 9394 9395@table @asis 9396@item @emph{Description}: 9397@code{LOG10(X)} computes the base 10 logarithm of @var{X}. 9398 9399@item @emph{Standard}: 9400Fortran 77 and later 9401 9402@item @emph{Class}: 9403Elemental function 9404 9405@item @emph{Syntax}: 9406@code{RESULT = LOG10(X)} 9407 9408@item @emph{Arguments}: 9409@multitable @columnfractions .15 .70 9410@item @var{X} @tab The type shall be @code{REAL}. 9411@end multitable 9412 9413@item @emph{Return value}: 9414The return value is of type @code{REAL} or @code{COMPLEX}. 9415The kind type parameter is the same as @var{X}. 9416 9417@item @emph{Example}: 9418@smallexample 9419program test_log10 9420 real(8) :: x = 10.0_8 9421 x = log10(x) 9422end program test_log10 9423@end smallexample 9424 9425@item @emph{Specific names}: 9426@multitable @columnfractions .20 .20 .20 .25 9427@item Name @tab Argument @tab Return type @tab Standard 9428@item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 9429@item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 9430@end multitable 9431@end table 9432 9433 9434 9435@node LOG_GAMMA 9436@section @code{LOG_GAMMA} --- Logarithm of the Gamma function 9437@fnindex LOG_GAMMA 9438@fnindex LGAMMA 9439@fnindex ALGAMA 9440@fnindex DLGAMA 9441@cindex Gamma function, logarithm of 9442 9443@table @asis 9444@item @emph{Description}: 9445@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value 9446of the Gamma (@math{\Gamma}) function. 9447 9448@item @emph{Standard}: 9449Fortran 2008 and later 9450 9451@item @emph{Class}: 9452Elemental function 9453 9454@item @emph{Syntax}: 9455@code{X = LOG_GAMMA(X)} 9456 9457@item @emph{Arguments}: 9458@multitable @columnfractions .15 .70 9459@item @var{X} @tab Shall be of type @code{REAL} and neither zero 9460nor a negative integer. 9461@end multitable 9462 9463@item @emph{Return value}: 9464The return value is of type @code{REAL} of the same kind as @var{X}. 9465 9466@item @emph{Example}: 9467@smallexample 9468program test_log_gamma 9469 real :: x = 1.0 9470 x = lgamma(x) ! returns 0.0 9471end program test_log_gamma 9472@end smallexample 9473 9474@item @emph{Specific names}: 9475@multitable @columnfractions .20 .20 .20 .25 9476@item Name @tab Argument @tab Return type @tab Standard 9477@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 9478@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 9479@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 9480@end multitable 9481 9482@item @emph{See also}: 9483Gamma function: @ref{GAMMA} 9484 9485@end table 9486 9487 9488 9489@node LOGICAL 9490@section @code{LOGICAL} --- Convert to logical type 9491@fnindex LOGICAL 9492@cindex conversion, to logical 9493 9494@table @asis 9495@item @emph{Description}: 9496Converts one kind of @code{LOGICAL} variable to another. 9497 9498@item @emph{Standard}: 9499Fortran 95 and later 9500 9501@item @emph{Class}: 9502Elemental function 9503 9504@item @emph{Syntax}: 9505@code{RESULT = LOGICAL(L [, KIND])} 9506 9507@item @emph{Arguments}: 9508@multitable @columnfractions .15 .70 9509@item @var{L} @tab The type shall be @code{LOGICAL}. 9510@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9511expression indicating the kind parameter of the result. 9512@end multitable 9513 9514@item @emph{Return value}: 9515The return value is a @code{LOGICAL} value equal to @var{L}, with a 9516kind corresponding to @var{KIND}, or of the default logical kind if 9517@var{KIND} is not given. 9518 9519@item @emph{See also}: 9520@ref{INT}, @ref{REAL}, @ref{CMPLX} 9521@end table 9522 9523 9524 9525@node LONG 9526@section @code{LONG} --- Convert to integer type 9527@fnindex LONG 9528@cindex conversion, to integer 9529 9530@table @asis 9531@item @emph{Description}: 9532Convert to a @code{KIND=4} integer type, which is the same size as a C 9533@code{long} integer. This is equivalent to the standard @code{INT} 9534intrinsic with an optional argument of @code{KIND=4}, and is only 9535included for backwards compatibility. 9536 9537@item @emph{Standard}: 9538GNU extension 9539 9540@item @emph{Class}: 9541Elemental function 9542 9543@item @emph{Syntax}: 9544@code{RESULT = LONG(A)} 9545 9546@item @emph{Arguments}: 9547@multitable @columnfractions .15 .70 9548@item @var{A} @tab Shall be of type @code{INTEGER}, 9549@code{REAL}, or @code{COMPLEX}. 9550@end multitable 9551 9552@item @emph{Return value}: 9553The return value is a @code{INTEGER(4)} variable. 9554 9555@item @emph{See also}: 9556@ref{INT}, @ref{INT2}, @ref{INT8} 9557@end table 9558 9559 9560 9561@node LSHIFT 9562@section @code{LSHIFT} --- Left shift bits 9563@fnindex LSHIFT 9564@cindex bits, shift left 9565 9566@table @asis 9567@item @emph{Description}: 9568@code{LSHIFT} returns a value corresponding to @var{I} with all of the 9569bits shifted left by @var{SHIFT} places. If the absolute value of 9570@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 9571Bits shifted out from the left end are lost; zeros are shifted in from 9572the opposite end. 9573 9574This function has been superseded by the @code{ISHFT} intrinsic, which 9575is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic, 9576which is standard in Fortran 2008 and later. 9577 9578@item @emph{Standard}: 9579GNU extension 9580 9581@item @emph{Class}: 9582Elemental function 9583 9584@item @emph{Syntax}: 9585@code{RESULT = LSHIFT(I, SHIFT)} 9586 9587@item @emph{Arguments}: 9588@multitable @columnfractions .15 .70 9589@item @var{I} @tab The type shall be @code{INTEGER}. 9590@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 9591@end multitable 9592 9593@item @emph{Return value}: 9594The return value is of type @code{INTEGER} and of the same kind as 9595@var{I}. 9596 9597@item @emph{See also}: 9598@ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL}, 9599@ref{SHIFTR} 9600 9601@end table 9602 9603 9604 9605@node LSTAT 9606@section @code{LSTAT} --- Get file status 9607@fnindex LSTAT 9608@cindex file system, file status 9609 9610@table @asis 9611@item @emph{Description}: 9612@code{LSTAT} is identical to @ref{STAT}, except that if path is a 9613symbolic link, then the link itself is statted, not the file that it 9614refers to. 9615 9616The elements in @code{VALUES} are the same as described by @ref{STAT}. 9617 9618This intrinsic is provided in both subroutine and function forms; 9619however, only one form can be used in any given program unit. 9620 9621@item @emph{Standard}: 9622GNU extension 9623 9624@item @emph{Class}: 9625Subroutine, function 9626 9627@item @emph{Syntax}: 9628@multitable @columnfractions .80 9629@item @code{CALL LSTAT(NAME, VALUES [, STATUS])} 9630@item @code{STATUS = LSTAT(NAME, VALUES)} 9631@end multitable 9632 9633@item @emph{Arguments}: 9634@multitable @columnfractions .15 .70 9635@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default 9636kind, a valid path within the file system. 9637@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 9638@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. 9639Returns 0 on success and a system specific error code otherwise. 9640@end multitable 9641 9642@item @emph{Example}: 9643See @ref{STAT} for an example. 9644 9645@item @emph{See also}: 9646To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT} 9647@end table 9648 9649 9650 9651@node LTIME 9652@section @code{LTIME} --- Convert time to local time info 9653@fnindex LTIME 9654@cindex time, conversion to local time info 9655 9656@table @asis 9657@item @emph{Description}: 9658Given a system time value @var{TIME} (as provided by the @ref{TIME} 9659intrinsic), fills @var{VALUES} with values extracted from it appropriate 9660to the local time zone using @code{localtime(3)}. 9661 9662This intrinsic routine is provided for backwards compatibility with 9663GNU Fortran 77. In new code, programmers should consider the use of 9664the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 9665standard. 9666 9667@item @emph{Standard}: 9668GNU extension 9669 9670@item @emph{Class}: 9671Subroutine 9672 9673@item @emph{Syntax}: 9674@code{CALL LTIME(TIME, VALUES)} 9675 9676@item @emph{Arguments}: 9677@multitable @columnfractions .15 .70 9678@item @var{TIME} @tab An @code{INTEGER} scalar expression 9679corresponding to a system time, with @code{INTENT(IN)}. 9680@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 9681with @code{INTENT(OUT)}. 9682@end multitable 9683 9684@item @emph{Return value}: 9685The elements of @var{VALUES} are assigned as follows: 9686@enumerate 9687@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 9688seconds 9689@item Minutes after the hour, range 0--59 9690@item Hours past midnight, range 0--23 9691@item Day of month, range 1--31 9692@item Number of months since January, range 0--11 9693@item Years since 1900 9694@item Number of days since Sunday, range 0--6 9695@item Days since January 1, range 0--365 9696@item Daylight savings indicator: positive if daylight savings is in 9697effect, zero if not, and negative if the information is not available. 9698@end enumerate 9699 9700@item @emph{See also}: 9701@ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8} 9702 9703@end table 9704 9705 9706 9707@node MALLOC 9708@section @code{MALLOC} --- Allocate dynamic memory 9709@fnindex MALLOC 9710@cindex pointer, cray 9711 9712@table @asis 9713@item @emph{Description}: 9714@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and 9715returns the address of the allocated memory. The @code{MALLOC} intrinsic 9716is an extension intended to be used with Cray pointers, and is provided 9717in GNU Fortran to allow the user to compile legacy code. For new code 9718using Fortran 95 pointers, the memory allocation intrinsic is 9719@code{ALLOCATE}. 9720 9721@item @emph{Standard}: 9722GNU extension 9723 9724@item @emph{Class}: 9725Function 9726 9727@item @emph{Syntax}: 9728@code{PTR = MALLOC(SIZE)} 9729 9730@item @emph{Arguments}: 9731@multitable @columnfractions .15 .70 9732@item @var{SIZE} @tab The type shall be @code{INTEGER}. 9733@end multitable 9734 9735@item @emph{Return value}: 9736The return value is of type @code{INTEGER(K)}, with @var{K} such that 9737variables of type @code{INTEGER(K)} have the same size as 9738C pointers (@code{sizeof(void *)}). 9739 9740@item @emph{Example}: 9741The following example demonstrates the use of @code{MALLOC} and 9742@code{FREE} with Cray pointers. 9743 9744@smallexample 9745program test_malloc 9746 implicit none 9747 integer i 9748 real*8 x(*), z 9749 pointer(ptr_x,x) 9750 9751 ptr_x = malloc(20*8) 9752 do i = 1, 20 9753 x(i) = sqrt(1.0d0 / i) 9754 end do 9755 z = 0 9756 do i = 1, 20 9757 z = z + x(i) 9758 print *, z 9759 end do 9760 call free(ptr_x) 9761end program test_malloc 9762@end smallexample 9763 9764@item @emph{See also}: 9765@ref{FREE} 9766@end table 9767 9768 9769 9770@node MASKL 9771@section @code{MASKL} --- Left justified mask 9772@fnindex MASKL 9773@cindex mask, left justified 9774 9775@table @asis 9776@item @emph{Description}: 9777@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the 9778remaining bits set to 0. 9779 9780@item @emph{Standard}: 9781Fortran 2008 and later 9782 9783@item @emph{Class}: 9784Elemental function 9785 9786@item @emph{Syntax}: 9787@code{RESULT = MASKL(I[, KIND])} 9788 9789@item @emph{Arguments}: 9790@multitable @columnfractions .15 .70 9791@item @var{I} @tab Shall be of type @code{INTEGER}. 9792@item @var{KIND} @tab Shall be a scalar constant expression of type 9793@code{INTEGER}. 9794@end multitable 9795 9796@item @emph{Return value}: 9797The return value is of type @code{INTEGER}. If @var{KIND} is present, it 9798specifies the kind value of the return type; otherwise, it is of the 9799default integer kind. 9800 9801@item @emph{See also}: 9802@ref{MASKR} 9803@end table 9804 9805 9806 9807@node MASKR 9808@section @code{MASKR} --- Right justified mask 9809@fnindex MASKR 9810@cindex mask, right justified 9811 9812@table @asis 9813@item @emph{Description}: 9814@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the 9815remaining bits set to 0. 9816 9817@item @emph{Standard}: 9818Fortran 2008 and later 9819 9820@item @emph{Class}: 9821Elemental function 9822 9823@item @emph{Syntax}: 9824@code{RESULT = MASKR(I[, KIND])} 9825 9826@item @emph{Arguments}: 9827@multitable @columnfractions .15 .70 9828@item @var{I} @tab Shall be of type @code{INTEGER}. 9829@item @var{KIND} @tab Shall be a scalar constant expression of type 9830@code{INTEGER}. 9831@end multitable 9832 9833@item @emph{Return value}: 9834The return value is of type @code{INTEGER}. If @var{KIND} is present, it 9835specifies the kind value of the return type; otherwise, it is of the 9836default integer kind. 9837 9838@item @emph{See also}: 9839@ref{MASKL} 9840@end table 9841 9842 9843 9844@node MATMUL 9845@section @code{MATMUL} --- matrix multiplication 9846@fnindex MATMUL 9847@cindex matrix multiplication 9848@cindex product, matrix 9849 9850@table @asis 9851@item @emph{Description}: 9852Performs a matrix multiplication on numeric or logical arguments. 9853 9854@item @emph{Standard}: 9855Fortran 95 and later 9856 9857@item @emph{Class}: 9858Transformational function 9859 9860@item @emph{Syntax}: 9861@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)} 9862 9863@item @emph{Arguments}: 9864@multitable @columnfractions .15 .70 9865@item @var{MATRIX_A} @tab An array of @code{INTEGER}, 9866@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of 9867one or two. 9868@item @var{MATRIX_B} @tab An array of @code{INTEGER}, 9869@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric 9870type; otherwise, an array of @code{LOGICAL} type. The rank shall be one 9871or two, and the first (or only) dimension of @var{MATRIX_B} shall be 9872equal to the last (or only) dimension of @var{MATRIX_A}. 9873@var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays. 9874@end multitable 9875 9876@item @emph{Return value}: 9877The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and 9878kind of the result follow the usual type and kind promotion rules, as 9879for the @code{*} or @code{.AND.} operators. 9880 9881@item @emph{See also}: 9882@end table 9883 9884 9885 9886@node MAX 9887@section @code{MAX} --- Maximum value of an argument list 9888@fnindex MAX 9889@fnindex MAX0 9890@fnindex AMAX0 9891@fnindex MAX1 9892@fnindex AMAX1 9893@fnindex DMAX1 9894@cindex maximum value 9895 9896@table @asis 9897@item @emph{Description}: 9898Returns the argument with the largest (most positive) value. 9899 9900@item @emph{Standard}: 9901Fortran 77 and later 9902 9903@item @emph{Class}: 9904Elemental function 9905 9906@item @emph{Syntax}: 9907@code{RESULT = MAX(A1, A2 [, A3 [, ...]])} 9908 9909@item @emph{Arguments}: 9910@multitable @columnfractions .15 .70 9911@item @var{A1} @tab The type shall be @code{INTEGER} or 9912@code{REAL}. 9913@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 9914as @var{A1}. (As a GNU extension, arguments of different kinds are 9915permitted.) 9916@end multitable 9917 9918@item @emph{Return value}: 9919The return value corresponds to the maximum value among the arguments, 9920and has the same type and kind as the first argument. 9921 9922@item @emph{Specific names}: 9923@multitable @columnfractions .20 .20 .20 .25 9924@item Name @tab Argument @tab Return type @tab Standard 9925@item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 9926@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later 9927@item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later 9928@item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 9929@item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 9930@end multitable 9931 9932@item @emph{See also}: 9933@ref{MAXLOC} @ref{MAXVAL}, @ref{MIN} 9934 9935@end table 9936 9937 9938 9939@node MAXEXPONENT 9940@section @code{MAXEXPONENT} --- Maximum exponent of a real kind 9941@fnindex MAXEXPONENT 9942@cindex model representation, maximum exponent 9943 9944@table @asis 9945@item @emph{Description}: 9946@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the 9947type of @code{X}. 9948 9949@item @emph{Standard}: 9950Fortran 95 and later 9951 9952@item @emph{Class}: 9953Inquiry function 9954 9955@item @emph{Syntax}: 9956@code{RESULT = MAXEXPONENT(X)} 9957 9958@item @emph{Arguments}: 9959@multitable @columnfractions .15 .70 9960@item @var{X} @tab Shall be of type @code{REAL}. 9961@end multitable 9962 9963@item @emph{Return value}: 9964The return value is of type @code{INTEGER} and of the default integer 9965kind. 9966 9967@item @emph{Example}: 9968@smallexample 9969program exponents 9970 real(kind=4) :: x 9971 real(kind=8) :: y 9972 9973 print *, minexponent(x), maxexponent(x) 9974 print *, minexponent(y), maxexponent(y) 9975end program exponents 9976@end smallexample 9977@end table 9978 9979 9980 9981@node MAXLOC 9982@section @code{MAXLOC} --- Location of the maximum value within an array 9983@fnindex MAXLOC 9984@cindex array, location of maximum element 9985 9986@table @asis 9987@item @emph{Description}: 9988Determines the location of the element in the array with the maximum 9989value, or, if the @var{DIM} argument is supplied, determines the 9990locations of the maximum element along each row of the array in the 9991@var{DIM} direction. If @var{MASK} is present, only the elements for 9992which @var{MASK} is @code{.TRUE.} are considered. If more than one 9993element in the array has the maximum value, the location returned is 9994that of the first such element in array element order. If the array has 9995zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 9996the result is an array of zeroes. Similarly, if @var{DIM} is supplied 9997and all of the elements of @var{MASK} along a given row are zero, the 9998result value for that row is zero. 9999 10000@item @emph{Standard}: 10001Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the 10002@var{KIND} argument are available in Fortran 2003 and later. 10003 10004@item @emph{Class}: 10005Transformational function 10006 10007@item @emph{Syntax}: 10008@multitable @columnfractions .80 10009@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND])} 10010@item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND])} 10011@end multitable 10012 10013@item @emph{Arguments}: 10014@multitable @columnfractions .15 .70 10015@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10016@code{REAL}. 10017@item @var{DIM} @tab (Optional) Shall be a scalar of type 10018@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10019inclusive. It may not be an optional dummy argument. 10020@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10021and conformable with @var{ARRAY}. 10022@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10023expression indicating the kind parameter of the result. 10024@end multitable 10025 10026@item @emph{Return value}: 10027If @var{DIM} is absent, the result is a rank-one array with a length 10028equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10029is an array with a rank one less than the rank of @var{ARRAY}, and a 10030size corresponding to the size of @var{ARRAY} with the @var{DIM} 10031dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10032of one, the result is a scalar. If the optional argument @var{KIND} 10033is present, the result is an integer of kind @var{KIND}, otherwise it 10034is of default kind. 10035 10036@item @emph{See also}: 10037@ref{MAX}, @ref{MAXVAL} 10038 10039@end table 10040 10041 10042 10043@node MAXVAL 10044@section @code{MAXVAL} --- Maximum value of an array 10045@fnindex MAXVAL 10046@cindex array, maximum value 10047@cindex maximum value 10048 10049@table @asis 10050@item @emph{Description}: 10051Determines the maximum value of the elements in an array value, or, if 10052the @var{DIM} argument is supplied, determines the maximum value along 10053each row of the array in the @var{DIM} direction. If @var{MASK} is 10054present, only the elements for which @var{MASK} is @code{.TRUE.} are 10055considered. If the array has zero size, or all of the elements of 10056@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)} 10057if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character 10058type. 10059 10060@item @emph{Standard}: 10061Fortran 95 and later 10062 10063@item @emph{Class}: 10064Transformational function 10065 10066@item @emph{Syntax}: 10067@multitable @columnfractions .80 10068@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])} 10069@item @code{RESULT = MAXVAL(ARRAY [, MASK])} 10070@end multitable 10071 10072@item @emph{Arguments}: 10073@multitable @columnfractions .15 .70 10074@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10075@code{REAL}. 10076@item @var{DIM} @tab (Optional) Shall be a scalar of type 10077@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10078inclusive. It may not be an optional dummy argument. 10079@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10080and conformable with @var{ARRAY}. 10081@end multitable 10082 10083@item @emph{Return value}: 10084If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10085is a scalar. If @var{DIM} is present, the result is an array with a 10086rank one less than the rank of @var{ARRAY}, and a size corresponding to 10087the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10088cases, the result is of the same type and kind as @var{ARRAY}. 10089 10090@item @emph{See also}: 10091@ref{MAX}, @ref{MAXLOC} 10092@end table 10093 10094 10095 10096@node MCLOCK 10097@section @code{MCLOCK} --- Time function 10098@fnindex MCLOCK 10099@cindex time, clock ticks 10100@cindex clock ticks 10101 10102@table @asis 10103@item @emph{Description}: 10104Returns the number of clock ticks since the start of the process, based 10105on the function @code{clock(3)} in the C standard library. 10106 10107This intrinsic is not fully portable, such as to systems with 32-bit 10108@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 10109the values returned by this intrinsic might be, or become, negative, or 10110numerically less than previous values, during a single run of the 10111compiled program. 10112 10113@item @emph{Standard}: 10114GNU extension 10115 10116@item @emph{Class}: 10117Function 10118 10119@item @emph{Syntax}: 10120@code{RESULT = MCLOCK()} 10121 10122@item @emph{Return value}: 10123The return value is a scalar of type @code{INTEGER(4)}, equal to the 10124number of clock ticks since the start of the process, or @code{-1} if 10125the system does not support @code{clock(3)}. 10126 10127@item @emph{See also}: 10128@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME} 10129 10130@end table 10131 10132 10133 10134@node MCLOCK8 10135@section @code{MCLOCK8} --- Time function (64-bit) 10136@fnindex MCLOCK8 10137@cindex time, clock ticks 10138@cindex clock ticks 10139 10140@table @asis 10141@item @emph{Description}: 10142Returns the number of clock ticks since the start of the process, based 10143on the function @code{clock(3)} in the C standard library. 10144 10145@emph{Warning:} this intrinsic does not increase the range of the timing 10146values over that returned by @code{clock(3)}. On a system with a 32-bit 10147@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though 10148it is converted to a 64-bit @code{INTEGER(8)} value. That means 10149overflows of the 32-bit value can still occur. Therefore, the values 10150returned by this intrinsic might be or become negative or numerically 10151less than previous values during a single run of the compiled program. 10152 10153@item @emph{Standard}: 10154GNU extension 10155 10156@item @emph{Class}: 10157Function 10158 10159@item @emph{Syntax}: 10160@code{RESULT = MCLOCK8()} 10161 10162@item @emph{Return value}: 10163The return value is a scalar of type @code{INTEGER(8)}, equal to the 10164number of clock ticks since the start of the process, or @code{-1} if 10165the system does not support @code{clock(3)}. 10166 10167@item @emph{See also}: 10168@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} 10169 10170@end table 10171 10172 10173 10174@node MERGE 10175@section @code{MERGE} --- Merge variables 10176@fnindex MERGE 10177@cindex array, merge arrays 10178@cindex array, combine arrays 10179 10180@table @asis 10181@item @emph{Description}: 10182Select values from two arrays according to a logical mask. The result 10183is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to 10184@var{FSOURCE} if it is @code{.FALSE.}. 10185 10186@item @emph{Standard}: 10187Fortran 95 and later 10188 10189@item @emph{Class}: 10190Elemental function 10191 10192@item @emph{Syntax}: 10193@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)} 10194 10195@item @emph{Arguments}: 10196@multitable @columnfractions .15 .70 10197@item @var{TSOURCE} @tab May be of any type. 10198@item @var{FSOURCE} @tab Shall be of the same type and type parameters 10199as @var{TSOURCE}. 10200@item @var{MASK} @tab Shall be of type @code{LOGICAL}. 10201@end multitable 10202 10203@item @emph{Return value}: 10204The result is of the same type and type parameters as @var{TSOURCE}. 10205 10206@end table 10207 10208 10209 10210@node MERGE_BITS 10211@section @code{MERGE_BITS} --- Merge of bits under mask 10212@fnindex MERGE_BITS 10213@cindex bits, merge 10214 10215@table @asis 10216@item @emph{Description}: 10217@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J} 10218as determined by the mask. The i-th bit of the result is equal to the 10219i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to 10220the i-th bit of @var{J} otherwise. 10221 10222@item @emph{Standard}: 10223Fortran 2008 and later 10224 10225@item @emph{Class}: 10226Elemental function 10227 10228@item @emph{Syntax}: 10229@code{RESULT = MERGE_BITS(I, J, MASK)} 10230 10231@item @emph{Arguments}: 10232@multitable @columnfractions .15 .70 10233@item @var{I} @tab Shall be of type @code{INTEGER}. 10234@item @var{J} @tab Shall be of type @code{INTEGER} and of the same 10235kind as @var{I}. 10236@item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same 10237kind as @var{I}. 10238@end multitable 10239 10240@item @emph{Return value}: 10241The result is of the same type and kind as @var{I}. 10242 10243@end table 10244 10245 10246 10247@node MIN 10248@section @code{MIN} --- Minimum value of an argument list 10249@fnindex MIN 10250@fnindex MIN0 10251@fnindex AMIN0 10252@fnindex MIN1 10253@fnindex AMIN1 10254@fnindex DMIN1 10255@cindex minimum value 10256 10257@table @asis 10258@item @emph{Description}: 10259Returns the argument with the smallest (most negative) value. 10260 10261@item @emph{Standard}: 10262Fortran 77 and later 10263 10264@item @emph{Class}: 10265Elemental function 10266 10267@item @emph{Syntax}: 10268@code{RESULT = MIN(A1, A2 [, A3, ...])} 10269 10270@item @emph{Arguments}: 10271@multitable @columnfractions .15 .70 10272@item @var{A1} @tab The type shall be @code{INTEGER} or 10273@code{REAL}. 10274@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10275as @var{A1}. (As a GNU extension, arguments of different kinds are 10276permitted.) 10277@end multitable 10278 10279@item @emph{Return value}: 10280The return value corresponds to the maximum value among the arguments, 10281and has the same type and kind as the first argument. 10282 10283@item @emph{Specific names}: 10284@multitable @columnfractions .20 .20 .20 .25 10285@item Name @tab Argument @tab Return type @tab Standard 10286@item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10287@item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10288@item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10289@item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10290@item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10291@end multitable 10292 10293@item @emph{See also}: 10294@ref{MAX}, @ref{MINLOC}, @ref{MINVAL} 10295@end table 10296 10297 10298 10299@node MINEXPONENT 10300@section @code{MINEXPONENT} --- Minimum exponent of a real kind 10301@fnindex MINEXPONENT 10302@cindex model representation, minimum exponent 10303 10304@table @asis 10305@item @emph{Description}: 10306@code{MINEXPONENT(X)} returns the minimum exponent in the model of the 10307type of @code{X}. 10308 10309@item @emph{Standard}: 10310Fortran 95 and later 10311 10312@item @emph{Class}: 10313Inquiry function 10314 10315@item @emph{Syntax}: 10316@code{RESULT = MINEXPONENT(X)} 10317 10318@item @emph{Arguments}: 10319@multitable @columnfractions .15 .70 10320@item @var{X} @tab Shall be of type @code{REAL}. 10321@end multitable 10322 10323@item @emph{Return value}: 10324The return value is of type @code{INTEGER} and of the default integer 10325kind. 10326 10327@item @emph{Example}: 10328See @code{MAXEXPONENT} for an example. 10329@end table 10330 10331 10332 10333@node MINLOC 10334@section @code{MINLOC} --- Location of the minimum value within an array 10335@fnindex MINLOC 10336@cindex array, location of minimum element 10337 10338@table @asis 10339@item @emph{Description}: 10340Determines the location of the element in the array with the minimum 10341value, or, if the @var{DIM} argument is supplied, determines the 10342locations of the minimum element along each row of the array in the 10343@var{DIM} direction. If @var{MASK} is present, only the elements for 10344which @var{MASK} is @code{.TRUE.} are considered. If more than one 10345element in the array has the minimum value, the location returned is 10346that of the first such element in array element order. If the array has 10347zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10348the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10349and all of the elements of @var{MASK} along a given row are zero, the 10350result value for that row is zero. 10351 10352@item @emph{Standard}: 10353Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the 10354@var{KIND} argument are available in Fortran 2003 and later. 10355 10356@item @emph{Class}: 10357Transformational function 10358 10359@item @emph{Syntax}: 10360@multitable @columnfractions .80 10361@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND])} 10362@item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND])} 10363@end multitable 10364 10365@item @emph{Arguments}: 10366@multitable @columnfractions .15 .70 10367@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 10368@code{REAL} or @code{CHARACTER}. 10369@item @var{DIM} @tab (Optional) Shall be a scalar of type 10370@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10371inclusive. It may not be an optional dummy argument. 10372@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10373and conformable with @var{ARRAY}. 10374@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10375expression indicating the kind parameter of the result. 10376@end multitable 10377 10378@item @emph{Return value}: 10379If @var{DIM} is absent, the result is a rank-one array with a length 10380equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10381is an array with a rank one less than the rank of @var{ARRAY}, and a 10382size corresponding to the size of @var{ARRAY} with the @var{DIM} 10383dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10384of one, the result is a scalar. If the optional argument @var{KIND} 10385is present, the result is an integer of kind @var{KIND}, otherwise it 10386is of default kind. 10387 10388@item @emph{See also}: 10389@ref{MIN}, @ref{MINVAL} 10390 10391@end table 10392 10393 10394 10395@node MINVAL 10396@section @code{MINVAL} --- Minimum value of an array 10397@fnindex MINVAL 10398@cindex array, minimum value 10399@cindex minimum value 10400 10401@table @asis 10402@item @emph{Description}: 10403Determines the minimum value of the elements in an array value, or, if 10404the @var{DIM} argument is supplied, determines the minimum value along 10405each row of the array in the @var{DIM} direction. If @var{MASK} is 10406present, only the elements for which @var{MASK} is @code{.TRUE.} are 10407considered. If the array has zero size, or all of the elements of 10408@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if 10409@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if 10410@var{ARRAY} is of character type. 10411 10412@item @emph{Standard}: 10413Fortran 95 and later 10414 10415@item @emph{Class}: 10416Transformational function 10417 10418@item @emph{Syntax}: 10419@multitable @columnfractions .80 10420@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])} 10421@item @code{RESULT = MINVAL(ARRAY [, MASK])} 10422@end multitable 10423 10424@item @emph{Arguments}: 10425@multitable @columnfractions .15 .70 10426@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10427@code{REAL}. 10428@item @var{DIM} @tab (Optional) Shall be a scalar of type 10429@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10430inclusive. It may not be an optional dummy argument. 10431@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10432and conformable with @var{ARRAY}. 10433@end multitable 10434 10435@item @emph{Return value}: 10436If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10437is a scalar. If @var{DIM} is present, the result is an array with a 10438rank one less than the rank of @var{ARRAY}, and a size corresponding to 10439the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10440cases, the result is of the same type and kind as @var{ARRAY}. 10441 10442@item @emph{See also}: 10443@ref{MIN}, @ref{MINLOC} 10444 10445@end table 10446 10447 10448 10449@node MOD 10450@section @code{MOD} --- Remainder function 10451@fnindex MOD 10452@fnindex AMOD 10453@fnindex DMOD 10454@fnindex BMOD 10455@fnindex IMOD 10456@fnindex JMOD 10457@fnindex KMOD 10458@cindex remainder 10459@cindex division, remainder 10460 10461@table @asis 10462@item @emph{Description}: 10463@code{MOD(A,P)} computes the remainder of the division of A by P@. 10464 10465@item @emph{Standard}: 10466Fortran 77 and later, has overloads that are GNU extensions 10467 10468@item @emph{Class}: 10469Elemental function 10470 10471@item @emph{Syntax}: 10472@code{RESULT = MOD(A, P)} 10473 10474@item @emph{Arguments}: 10475@multitable @columnfractions .15 .70 10476@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10477@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A} 10478and not equal to zero. 10479@end multitable 10480 10481@item @emph{Return value}: 10482The return value is the result of @code{A - (INT(A/P) * P)}. The type 10483and kind of the return value is the same as that of the arguments. The 10484returned value has the same sign as A and a magnitude less than the 10485magnitude of P. 10486 10487@item @emph{Example}: 10488@smallexample 10489program test_mod 10490 print *, mod(17,3) 10491 print *, mod(17.5,5.5) 10492 print *, mod(17.5d0,5.5) 10493 print *, mod(17.5,5.5d0) 10494 10495 print *, mod(-17,3) 10496 print *, mod(-17.5,5.5) 10497 print *, mod(-17.5d0,5.5) 10498 print *, mod(-17.5,5.5d0) 10499 10500 print *, mod(17,-3) 10501 print *, mod(17.5,-5.5) 10502 print *, mod(17.5d0,-5.5) 10503 print *, mod(17.5,-5.5d0) 10504end program test_mod 10505@end smallexample 10506 10507@item @emph{Specific names}: 10508@multitable @columnfractions .20 .20 .20 .25 10509@item Name @tab Arguments @tab Return type @tab Standard 10510@item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later 10511@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later 10512@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later 10513@item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension 10514@item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension 10515@item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension 10516@item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension 10517@end multitable 10518 10519@item @emph{See also}: 10520@ref{MODULO} 10521 10522@end table 10523 10524 10525 10526@node MODULO 10527@section @code{MODULO} --- Modulo function 10528@fnindex MODULO 10529@cindex modulo 10530@cindex division, modulo 10531 10532@table @asis 10533@item @emph{Description}: 10534@code{MODULO(A,P)} computes the @var{A} modulo @var{P}. 10535 10536@item @emph{Standard}: 10537Fortran 95 and later 10538 10539@item @emph{Class}: 10540Elemental function 10541 10542@item @emph{Syntax}: 10543@code{RESULT = MODULO(A, P)} 10544 10545@item @emph{Arguments}: 10546@multitable @columnfractions .15 .70 10547@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10548@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}. 10549It shall not be zero. 10550@end multitable 10551 10552@item @emph{Return value}: 10553The type and kind of the result are those of the arguments. 10554@table @asis 10555@item If @var{A} and @var{P} are of type @code{INTEGER}: 10556@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where 10557@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P} 10558(exclusive). 10559@item If @var{A} and @var{P} are of type @code{REAL}: 10560@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}. 10561@end table 10562The returned value has the same sign as P and a magnitude less than 10563the magnitude of P. 10564 10565@item @emph{Example}: 10566@smallexample 10567program test_modulo 10568 print *, modulo(17,3) 10569 print *, modulo(17.5,5.5) 10570 10571 print *, modulo(-17,3) 10572 print *, modulo(-17.5,5.5) 10573 10574 print *, modulo(17,-3) 10575 print *, modulo(17.5,-5.5) 10576end program 10577@end smallexample 10578 10579@item @emph{See also}: 10580@ref{MOD} 10581 10582@end table 10583 10584 10585 10586@node MOVE_ALLOC 10587@section @code{MOVE_ALLOC} --- Move allocation from one object to another 10588@fnindex MOVE_ALLOC 10589@cindex moving allocation 10590@cindex allocation, moving 10591 10592@table @asis 10593@item @emph{Description}: 10594@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to 10595@var{TO}. @var{FROM} will become deallocated in the process. 10596 10597@item @emph{Standard}: 10598Fortran 2003 and later 10599 10600@item @emph{Class}: 10601Pure subroutine 10602 10603@item @emph{Syntax}: 10604@code{CALL MOVE_ALLOC(FROM, TO)} 10605 10606@item @emph{Arguments}: 10607@multitable @columnfractions .15 .70 10608@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be 10609of any type and kind. 10610@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be 10611of the same type, kind and rank as @var{FROM}. 10612@end multitable 10613 10614@item @emph{Return value}: 10615None 10616 10617@item @emph{Example}: 10618@smallexample 10619program test_move_alloc 10620 integer, allocatable :: a(:), b(:) 10621 10622 allocate(a(3)) 10623 a = [ 1, 2, 3 ] 10624 call move_alloc(a, b) 10625 print *, allocated(a), allocated(b) 10626 print *, b 10627end program test_move_alloc 10628@end smallexample 10629@end table 10630 10631 10632 10633@node MVBITS 10634@section @code{MVBITS} --- Move bits from one integer to another 10635@fnindex MVBITS 10636@fnindex BMVBITS 10637@fnindex IMVBITS 10638@fnindex JMVBITS 10639@fnindex KMVBITS 10640@cindex bits, move 10641 10642@table @asis 10643@item @emph{Description}: 10644Moves @var{LEN} bits from positions @var{FROMPOS} through 10645@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through 10646@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not 10647affected by the movement of bits is unchanged. The values of 10648@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than 10649@code{BIT_SIZE(FROM)}. 10650 10651@item @emph{Standard}: 10652Fortran 95 and later, has overloads that are GNU extensions 10653 10654@item @emph{Class}: 10655Elemental subroutine 10656 10657@item @emph{Syntax}: 10658@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)} 10659 10660@item @emph{Arguments}: 10661@multitable @columnfractions .15 .70 10662@item @var{FROM} @tab The type shall be @code{INTEGER}. 10663@item @var{FROMPOS} @tab The type shall be @code{INTEGER}. 10664@item @var{LEN} @tab The type shall be @code{INTEGER}. 10665@item @var{TO} @tab The type shall be @code{INTEGER}, of the 10666same kind as @var{FROM}. 10667@item @var{TOPOS} @tab The type shall be @code{INTEGER}. 10668@end multitable 10669 10670@item @emph{Specific names}: 10671@multitable @columnfractions .20 .20 .20 .25 10672@item Name @tab Argument @tab Return type @tab Standard 10673@item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 10674@item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 10675@item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 10676@item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 10677@item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 10678@end multitable 10679 10680@item @emph{See also}: 10681@ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR} 10682@end table 10683 10684 10685 10686@node NEAREST 10687@section @code{NEAREST} --- Nearest representable number 10688@fnindex NEAREST 10689@cindex real number, nearest different 10690@cindex floating point, nearest different 10691 10692@table @asis 10693@item @emph{Description}: 10694@code{NEAREST(X, S)} returns the processor-representable number nearest 10695to @code{X} in the direction indicated by the sign of @code{S}. 10696 10697@item @emph{Standard}: 10698Fortran 95 and later 10699 10700@item @emph{Class}: 10701Elemental function 10702 10703@item @emph{Syntax}: 10704@code{RESULT = NEAREST(X, S)} 10705 10706@item @emph{Arguments}: 10707@multitable @columnfractions .15 .70 10708@item @var{X} @tab Shall be of type @code{REAL}. 10709@item @var{S} @tab Shall be of type @code{REAL} and 10710not equal to zero. 10711@end multitable 10712 10713@item @emph{Return value}: 10714The return value is of the same type as @code{X}. If @code{S} is 10715positive, @code{NEAREST} returns the processor-representable number 10716greater than @code{X} and nearest to it. If @code{S} is negative, 10717@code{NEAREST} returns the processor-representable number smaller than 10718@code{X} and nearest to it. 10719 10720@item @emph{Example}: 10721@smallexample 10722program test_nearest 10723 real :: x, y 10724 x = nearest(42.0, 1.0) 10725 y = nearest(42.0, -1.0) 10726 write (*,"(3(G20.15))") x, y, x - y 10727end program test_nearest 10728@end smallexample 10729@end table 10730 10731 10732 10733@node NEW_LINE 10734@section @code{NEW_LINE} --- New line character 10735@fnindex NEW_LINE 10736@cindex newline 10737@cindex output, newline 10738 10739@table @asis 10740@item @emph{Description}: 10741@code{NEW_LINE(C)} returns the new-line character. 10742 10743@item @emph{Standard}: 10744Fortran 2003 and later 10745 10746@item @emph{Class}: 10747Inquiry function 10748 10749@item @emph{Syntax}: 10750@code{RESULT = NEW_LINE(C)} 10751 10752@item @emph{Arguments}: 10753@multitable @columnfractions .15 .70 10754@item @var{C} @tab The argument shall be a scalar or array of the 10755type @code{CHARACTER}. 10756@end multitable 10757 10758@item @emph{Return value}: 10759Returns a @var{CHARACTER} scalar of length one with the new-line character of 10760the same kind as parameter @var{C}. 10761 10762@item @emph{Example}: 10763@smallexample 10764program newline 10765 implicit none 10766 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' 10767end program newline 10768@end smallexample 10769@end table 10770 10771 10772 10773@node NINT 10774@section @code{NINT} --- Nearest whole number 10775@fnindex NINT 10776@fnindex IDNINT 10777@cindex rounding, nearest whole number 10778 10779@table @asis 10780@item @emph{Description}: 10781@code{NINT(A)} rounds its argument to the nearest whole number. 10782 10783@item @emph{Standard}: 10784Fortran 77 and later, with @var{KIND} argument Fortran 90 and later 10785 10786@item @emph{Class}: 10787Elemental function 10788 10789@item @emph{Syntax}: 10790@code{RESULT = NINT(A [, KIND])} 10791 10792@item @emph{Arguments}: 10793@multitable @columnfractions .15 .70 10794@item @var{A} @tab The type of the argument shall be @code{REAL}. 10795@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10796expression indicating the kind parameter of the result. 10797@end multitable 10798 10799@item @emph{Return value}: 10800Returns @var{A} with the fractional portion of its magnitude eliminated by 10801rounding to the nearest whole number and with its sign preserved, 10802converted to an @code{INTEGER} of the default kind. 10803 10804@item @emph{Example}: 10805@smallexample 10806program test_nint 10807 real(4) x4 10808 real(8) x8 10809 x4 = 1.234E0_4 10810 x8 = 4.321_8 10811 print *, nint(x4), idnint(x8) 10812end program test_nint 10813@end smallexample 10814 10815@item @emph{Specific names}: 10816@multitable @columnfractions .20 .20 .20 .25 10817@item Name @tab Argument @tab Return Type @tab Standard 10818@item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later 10819@item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later 10820@end multitable 10821 10822@item @emph{See also}: 10823@ref{CEILING}, @ref{FLOOR} 10824 10825@end table 10826 10827 10828 10829@node NORM2 10830@section @code{NORM2} --- Euclidean vector norms 10831@fnindex NORM2 10832@cindex Euclidean vector norm 10833@cindex L2 vector norm 10834@cindex norm, Euclidean 10835 10836@table @asis 10837@item @emph{Description}: 10838Calculates the Euclidean vector norm (@math{L_2} norm) of 10839of @var{ARRAY} along dimension @var{DIM}. 10840 10841@item @emph{Standard}: 10842Fortran 2008 and later 10843 10844@item @emph{Class}: 10845Transformational function 10846 10847@item @emph{Syntax}: 10848@multitable @columnfractions .80 10849@item @code{RESULT = NORM2(ARRAY[, DIM])} 10850@end multitable 10851 10852@item @emph{Arguments}: 10853@multitable @columnfractions .15 .70 10854@item @var{ARRAY} @tab Shall be an array of type @code{REAL} 10855@item @var{DIM} @tab (Optional) shall be a scalar of type 10856@code{INTEGER} with a value in the range from 1 to n, where n 10857equals the rank of @var{ARRAY}. 10858@end multitable 10859 10860@item @emph{Return value}: 10861The result is of the same type as @var{ARRAY}. 10862 10863If @var{DIM} is absent, a scalar with the square root of the sum of all 10864elements in @var{ARRAY} squared is returned. Otherwise, an array of 10865rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a 10866shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped 10867is returned. 10868 10869@item @emph{Example}: 10870@smallexample 10871PROGRAM test_sum 10872 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] 10873 print *, NORM2(x) ! = sqrt(55.) ~ 7.416 10874END PROGRAM 10875@end smallexample 10876@end table 10877 10878 10879 10880@node NOT 10881@section @code{NOT} --- Logical negation 10882@fnindex NOT 10883@fnindex BNOT 10884@fnindex INOT 10885@fnindex JNOT 10886@fnindex KNOT 10887@cindex bits, negate 10888@cindex bitwise logical not 10889@cindex logical not, bitwise 10890 10891@table @asis 10892@item @emph{Description}: 10893@code{NOT} returns the bitwise Boolean inverse of @var{I}. 10894 10895@item @emph{Standard}: 10896Fortran 95 and later, has overloads that are GNU extensions 10897 10898@item @emph{Class}: 10899Elemental function 10900 10901@item @emph{Syntax}: 10902@code{RESULT = NOT(I)} 10903 10904@item @emph{Arguments}: 10905@multitable @columnfractions .15 .70 10906@item @var{I} @tab The type shall be @code{INTEGER}. 10907@end multitable 10908 10909@item @emph{Return value}: 10910The return type is @code{INTEGER}, of the same kind as the 10911argument. 10912 10913@item @emph{Specific names}: 10914@multitable @columnfractions .20 .20 .20 .25 10915@item Name @tab Argument @tab Return type @tab Standard 10916@item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 10917@item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 10918@item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 10919@item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 10920@item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 10921@end multitable 10922 10923@item @emph{See also}: 10924@ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR} 10925 10926@end table 10927 10928 10929 10930@node NULL 10931@section @code{NULL} --- Function that returns an disassociated pointer 10932@fnindex NULL 10933@cindex pointer, status 10934@cindex pointer, disassociated 10935 10936@table @asis 10937@item @emph{Description}: 10938Returns a disassociated pointer. 10939 10940If @var{MOLD} is present, a disassociated pointer of the same type is 10941returned, otherwise the type is determined by context. 10942 10943In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003 10944includes cases where it is required. 10945 10946@item @emph{Standard}: 10947Fortran 95 and later 10948 10949@item @emph{Class}: 10950Transformational function 10951 10952@item @emph{Syntax}: 10953@code{PTR => NULL([MOLD])} 10954 10955@item @emph{Arguments}: 10956@multitable @columnfractions .15 .70 10957@item @var{MOLD} @tab (Optional) shall be a pointer of any association 10958status and of any type. 10959@end multitable 10960 10961@item @emph{Return value}: 10962A disassociated pointer. 10963 10964@item @emph{Example}: 10965@smallexample 10966REAL, POINTER, DIMENSION(:) :: VEC => NULL () 10967@end smallexample 10968 10969@item @emph{See also}: 10970@ref{ASSOCIATED} 10971@end table 10972 10973 10974 10975@node NUM_IMAGES 10976@section @code{NUM_IMAGES} --- Function that returns the number of images 10977@fnindex NUM_IMAGES 10978@cindex coarray, @code{NUM_IMAGES} 10979@cindex images, number of 10980 10981@table @asis 10982@item @emph{Description}: 10983Returns the number of images. 10984 10985@item @emph{Standard}: 10986Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument, 10987Technical Specification (TS) 18508 or later 10988 10989 10990@item @emph{Class}: 10991Transformational function 10992 10993@item @emph{Syntax}: 10994@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} 10995 10996@item @emph{Arguments}: 10997@multitable @columnfractions .15 .70 10998@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 10999@item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression 11000@end multitable 11001 11002@item @emph{Return value}: 11003Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, 11004the number of images in the current team is returned. For values smaller or 11005equal distance to the initial team, it returns the number of images index 11006on the ancestor team which has a distance of @var{DISTANCE} from the invoking 11007team. If @var{DISTANCE} is larger than the distance to the initial team, the 11008number of images of the initial team is returned. If @var{FAILED} is not present 11009the total number of images is returned; if it has the value @code{.TRUE.}, 11010the number of failed images is returned, otherwise, the number of images which 11011do have not the failed status. 11012 11013@item @emph{Example}: 11014@smallexample 11015INTEGER :: value[*] 11016INTEGER :: i 11017value = THIS_IMAGE() 11018SYNC ALL 11019IF (THIS_IMAGE() == 1) THEN 11020 DO i = 1, NUM_IMAGES() 11021 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 11022 END DO 11023END IF 11024@end smallexample 11025 11026@item @emph{See also}: 11027@ref{THIS_IMAGE}, @ref{IMAGE_INDEX} 11028@end table 11029 11030 11031 11032@node OR 11033@section @code{OR} --- Bitwise logical OR 11034@fnindex OR 11035@cindex bitwise logical or 11036@cindex logical or, bitwise 11037 11038@table @asis 11039@item @emph{Description}: 11040Bitwise logical @code{OR}. 11041 11042This intrinsic routine is provided for backwards compatibility with 11043GNU Fortran 77. For integer arguments, programmers should consider 11044the use of the @ref{IOR} intrinsic defined by the Fortran standard. 11045 11046@item @emph{Standard}: 11047GNU extension 11048 11049@item @emph{Class}: 11050Function 11051 11052@item @emph{Syntax}: 11053@code{RESULT = OR(I, J)} 11054 11055@item @emph{Arguments}: 11056@multitable @columnfractions .15 .70 11057@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 11058type or a scalar @code{LOGICAL} type. 11059@item @var{J} @tab The type shall be the same as the type of @var{J}. 11060@end multitable 11061 11062@item @emph{Return value}: 11063The return type is either a scalar @code{INTEGER} or a scalar 11064@code{LOGICAL}. If the kind type parameters differ, then the 11065smaller kind type is implicitly converted to larger kind, and the 11066return has the larger kind. 11067 11068@item @emph{Example}: 11069@smallexample 11070PROGRAM test_or 11071 LOGICAL :: T = .TRUE., F = .FALSE. 11072 INTEGER :: a, b 11073 DATA a / Z'F' /, b / Z'3' / 11074 11075 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F) 11076 WRITE (*,*) OR(a, b) 11077END PROGRAM 11078@end smallexample 11079 11080@item @emph{See also}: 11081Fortran 95 elemental function: @ref{IOR} 11082@end table 11083 11084 11085 11086@node PACK 11087@section @code{PACK} --- Pack an array into an array of rank one 11088@fnindex PACK 11089@cindex array, packing 11090@cindex array, reduce dimension 11091@cindex array, gather elements 11092 11093@table @asis 11094@item @emph{Description}: 11095Stores the elements of @var{ARRAY} in an array of rank one. 11096 11097The beginning of the resulting array is made up of elements whose @var{MASK} 11098equals @code{TRUE}. Afterwards, positions are filled with elements taken from 11099@var{VECTOR}. 11100 11101@item @emph{Standard}: 11102Fortran 95 and later 11103 11104@item @emph{Class}: 11105Transformational function 11106 11107@item @emph{Syntax}: 11108@code{RESULT = PACK(ARRAY, MASK[,VECTOR])} 11109 11110@item @emph{Arguments}: 11111@multitable @columnfractions .15 .70 11112@item @var{ARRAY} @tab Shall be an array of any type. 11113@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and 11114of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} 11115scalar. 11116@item @var{VECTOR} @tab (Optional) shall be an array of the same type 11117as @var{ARRAY} and of rank one. If present, the number of elements in 11118@var{VECTOR} shall be equal to or greater than the number of true elements 11119in @var{MASK}. If @var{MASK} is scalar, the number of elements in 11120@var{VECTOR} shall be equal to or greater than the number of elements in 11121@var{ARRAY}. 11122@end multitable 11123 11124@item @emph{Return value}: 11125The result is an array of rank one and the same type as that of @var{ARRAY}. 11126If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the 11127number of @code{TRUE} values in @var{MASK} otherwise. 11128 11129@item @emph{Example}: 11130Gathering nonzero elements from an array: 11131@smallexample 11132PROGRAM test_pack_1 11133 INTEGER :: m(6) 11134 m = (/ 1, 0, 0, 0, 5, 0 /) 11135 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5" 11136END PROGRAM 11137@end smallexample 11138 11139Gathering nonzero elements from an array and appending elements from @var{VECTOR}: 11140@smallexample 11141PROGRAM test_pack_2 11142 INTEGER :: m(4) 11143 m = (/ 1, 0, 0, 2 /) 11144 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4" 11145END PROGRAM 11146@end smallexample 11147 11148@item @emph{See also}: 11149@ref{UNPACK} 11150@end table 11151 11152 11153 11154@node PARITY 11155@section @code{PARITY} --- Reduction with exclusive OR 11156@fnindex PARITY 11157@cindex Parity 11158@cindex Reduction, XOR 11159@cindex XOR reduction 11160 11161@table @asis 11162@item @emph{Description}: 11163Calculates the parity, i.e. the reduction using @code{.XOR.}, 11164of @var{MASK} along dimension @var{DIM}. 11165 11166@item @emph{Standard}: 11167Fortran 2008 and later 11168 11169@item @emph{Class}: 11170Transformational function 11171 11172@item @emph{Syntax}: 11173@multitable @columnfractions .80 11174@item @code{RESULT = PARITY(MASK[, DIM])} 11175@end multitable 11176 11177@item @emph{Arguments}: 11178@multitable @columnfractions .15 .70 11179@item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL} 11180@item @var{DIM} @tab (Optional) shall be a scalar of type 11181@code{INTEGER} with a value in the range from 1 to n, where n 11182equals the rank of @var{MASK}. 11183@end multitable 11184 11185@item @emph{Return value}: 11186The result is of the same type as @var{MASK}. 11187 11188If @var{DIM} is absent, a scalar with the parity of all elements in 11189@var{MASK} is returned, i.e. true if an odd number of elements is 11190@code{.true.} and false otherwise. If @var{DIM} is present, an array 11191of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, 11192and a shape similar to that of @var{MASK} with dimension @var{DIM} 11193dropped is returned. 11194 11195@item @emph{Example}: 11196@smallexample 11197PROGRAM test_sum 11198 LOGICAL :: x(2) = [ .true., .false. ] 11199 print *, PARITY(x) ! prints "T" (true). 11200END PROGRAM 11201@end smallexample 11202@end table 11203 11204 11205 11206@node PERROR 11207@section @code{PERROR} --- Print system error message 11208@fnindex PERROR 11209@cindex system, error handling 11210 11211@table @asis 11212@item @emph{Description}: 11213Prints (on the C @code{stderr} stream) a newline-terminated error 11214message corresponding to the last system error. This is prefixed by 11215@var{STRING}, a colon and a space. See @code{perror(3)}. 11216 11217@item @emph{Standard}: 11218GNU extension 11219 11220@item @emph{Class}: 11221Subroutine 11222 11223@item @emph{Syntax}: 11224@code{CALL PERROR(STRING)} 11225 11226@item @emph{Arguments}: 11227@multitable @columnfractions .15 .70 11228@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the 11229default kind. 11230@end multitable 11231 11232@item @emph{See also}: 11233@ref{IERRNO} 11234@end table 11235 11236 11237 11238@node POPCNT 11239@section @code{POPCNT} --- Number of bits set 11240@fnindex POPCNT 11241@cindex binary representation 11242@cindex bits set 11243 11244@table @asis 11245@item @emph{Description}: 11246@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary 11247representation of @code{I}. 11248 11249@item @emph{Standard}: 11250Fortran 2008 and later 11251 11252@item @emph{Class}: 11253Elemental function 11254 11255@item @emph{Syntax}: 11256@code{RESULT = POPCNT(I)} 11257 11258@item @emph{Arguments}: 11259@multitable @columnfractions .15 .70 11260@item @var{I} @tab Shall be of type @code{INTEGER}. 11261@end multitable 11262 11263@item @emph{Return value}: 11264The return value is of type @code{INTEGER} and of the default integer 11265kind. 11266 11267@item @emph{See also}: 11268@ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ} 11269 11270@item @emph{Example}: 11271@smallexample 11272program test_population 11273 print *, popcnt(127), poppar(127) 11274 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11275 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11276end program test_population 11277@end smallexample 11278@end table 11279 11280 11281@node POPPAR 11282@section @code{POPPAR} --- Parity of the number of bits set 11283@fnindex POPPAR 11284@cindex binary representation 11285@cindex parity 11286 11287@table @asis 11288@item @emph{Description}: 11289@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity 11290of the number of bits set ('1' bits) in the binary representation of 11291@code{I}. It is equal to 0 if @code{I} has an even number of bits set, 11292and 1 for an odd number of '1' bits. 11293 11294@item @emph{Standard}: 11295Fortran 2008 and later 11296 11297@item @emph{Class}: 11298Elemental function 11299 11300@item @emph{Syntax}: 11301@code{RESULT = POPPAR(I)} 11302 11303@item @emph{Arguments}: 11304@multitable @columnfractions .15 .70 11305@item @var{I} @tab Shall be of type @code{INTEGER}. 11306@end multitable 11307 11308@item @emph{Return value}: 11309The return value is of type @code{INTEGER} and of the default integer 11310kind. 11311 11312@item @emph{See also}: 11313@ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ} 11314 11315@item @emph{Example}: 11316@smallexample 11317program test_population 11318 print *, popcnt(127), poppar(127) 11319 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11320 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11321end program test_population 11322@end smallexample 11323@end table 11324 11325 11326 11327@node PRECISION 11328@section @code{PRECISION} --- Decimal precision of a real kind 11329@fnindex PRECISION 11330@cindex model representation, precision 11331 11332@table @asis 11333@item @emph{Description}: 11334@code{PRECISION(X)} returns the decimal precision in the model of the 11335type of @code{X}. 11336 11337@item @emph{Standard}: 11338Fortran 95 and later 11339 11340@item @emph{Class}: 11341Inquiry function 11342 11343@item @emph{Syntax}: 11344@code{RESULT = PRECISION(X)} 11345 11346@item @emph{Arguments}: 11347@multitable @columnfractions .15 .70 11348@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. 11349@end multitable 11350 11351@item @emph{Return value}: 11352The return value is of type @code{INTEGER} and of the default integer 11353kind. 11354 11355@item @emph{See also}: 11356@ref{SELECTED_REAL_KIND}, @ref{RANGE} 11357 11358@item @emph{Example}: 11359@smallexample 11360program prec_and_range 11361 real(kind=4) :: x(2) 11362 complex(kind=8) :: y 11363 11364 print *, precision(x), range(x) 11365 print *, precision(y), range(y) 11366end program prec_and_range 11367@end smallexample 11368@end table 11369 11370 11371 11372@node PRESENT 11373@section @code{PRESENT} --- Determine whether an optional dummy argument is specified 11374@fnindex PRESENT 11375 11376@table @asis 11377@item @emph{Description}: 11378Determines whether an optional dummy argument is present. 11379 11380@item @emph{Standard}: 11381Fortran 95 and later 11382 11383@item @emph{Class}: 11384Inquiry function 11385 11386@item @emph{Syntax}: 11387@code{RESULT = PRESENT(A)} 11388 11389@item @emph{Arguments}: 11390@multitable @columnfractions .15 .70 11391@item @var{A} @tab May be of any type and may be a pointer, scalar or array 11392value, or a dummy procedure. It shall be the name of an optional dummy argument 11393accessible within the current subroutine or function. 11394@end multitable 11395 11396@item @emph{Return value}: 11397Returns either @code{TRUE} if the optional argument @var{A} is present, or 11398@code{FALSE} otherwise. 11399 11400@item @emph{Example}: 11401@smallexample 11402PROGRAM test_present 11403 WRITE(*,*) f(), f(42) ! "F T" 11404CONTAINS 11405 LOGICAL FUNCTION f(x) 11406 INTEGER, INTENT(IN), OPTIONAL :: x 11407 f = PRESENT(x) 11408 END FUNCTION 11409END PROGRAM 11410@end smallexample 11411@end table 11412 11413 11414 11415@node PRODUCT 11416@section @code{PRODUCT} --- Product of array elements 11417@fnindex PRODUCT 11418@cindex array, product 11419@cindex array, multiply elements 11420@cindex array, conditionally multiply elements 11421@cindex multiply array elements 11422 11423@table @asis 11424@item @emph{Description}: 11425Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if 11426the corresponding element in @var{MASK} is @code{TRUE}. 11427 11428@item @emph{Standard}: 11429Fortran 95 and later 11430 11431@item @emph{Class}: 11432Transformational function 11433 11434@item @emph{Syntax}: 11435@multitable @columnfractions .80 11436@item @code{RESULT = PRODUCT(ARRAY[, MASK])} 11437@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])} 11438@end multitable 11439 11440@item @emph{Arguments}: 11441@multitable @columnfractions .15 .70 11442@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 11443@code{REAL} or @code{COMPLEX}. 11444@item @var{DIM} @tab (Optional) shall be a scalar of type 11445@code{INTEGER} with a value in the range from 1 to n, where n 11446equals the rank of @var{ARRAY}. 11447@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 11448and either be a scalar or an array of the same shape as @var{ARRAY}. 11449@end multitable 11450 11451@item @emph{Return value}: 11452The result is of the same type as @var{ARRAY}. 11453 11454If @var{DIM} is absent, a scalar with the product of all elements in 11455@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 11456the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 11457dimension @var{DIM} dropped is returned. 11458 11459 11460@item @emph{Example}: 11461@smallexample 11462PROGRAM test_product 11463 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 11464 print *, PRODUCT(x) ! all elements, product = 120 11465 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15 11466END PROGRAM 11467@end smallexample 11468 11469@item @emph{See also}: 11470@ref{SUM} 11471@end table 11472 11473 11474 11475@node RADIX 11476@section @code{RADIX} --- Base of a model number 11477@fnindex RADIX 11478@cindex model representation, base 11479@cindex model representation, radix 11480 11481@table @asis 11482@item @emph{Description}: 11483@code{RADIX(X)} returns the base of the model representing the entity @var{X}. 11484 11485@item @emph{Standard}: 11486Fortran 95 and later 11487 11488@item @emph{Class}: 11489Inquiry function 11490 11491@item @emph{Syntax}: 11492@code{RESULT = RADIX(X)} 11493 11494@item @emph{Arguments}: 11495@multitable @columnfractions .15 .70 11496@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL} 11497@end multitable 11498 11499@item @emph{Return value}: 11500The return value is a scalar of type @code{INTEGER} and of the default 11501integer kind. 11502 11503@item @emph{See also}: 11504@ref{SELECTED_REAL_KIND} 11505 11506@item @emph{Example}: 11507@smallexample 11508program test_radix 11509 print *, "The radix for the default integer kind is", radix(0) 11510 print *, "The radix for the default real kind is", radix(0.0) 11511end program test_radix 11512@end smallexample 11513 11514@end table 11515 11516 11517 11518@node RAN 11519@section @code{RAN} --- Real pseudo-random number 11520@fnindex RAN 11521@cindex random number generation 11522 11523@table @asis 11524@item @emph{Description}: 11525For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is 11526provided as an alias for @code{RAND}. See @ref{RAND} for complete 11527documentation. 11528 11529@item @emph{Standard}: 11530GNU extension 11531 11532@item @emph{Class}: 11533Function 11534 11535@item @emph{See also}: 11536@ref{RAND}, @ref{RANDOM_NUMBER} 11537@end table 11538 11539 11540 11541@node RAND 11542@section @code{RAND} --- Real pseudo-random number 11543@fnindex RAND 11544@cindex random number generation 11545 11546@table @asis 11547@item @emph{Description}: 11548@code{RAND(FLAG)} returns a pseudo-random number from a uniform 11549distribution between 0 and 1. If @var{FLAG} is 0, the next number 11550in the current sequence is returned; if @var{FLAG} is 1, the generator 11551is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 11552it is used as a new seed with @code{SRAND}. 11553 11554This intrinsic routine is provided for backwards compatibility with 11555GNU Fortran 77. It implements a simple modulo generator as provided 11556by @command{g77}. For new code, one should consider the use of 11557@ref{RANDOM_NUMBER} as it implements a superior algorithm. 11558 11559@item @emph{Standard}: 11560GNU extension 11561 11562@item @emph{Class}: 11563Function 11564 11565@item @emph{Syntax}: 11566@code{RESULT = RAND(I)} 11567 11568@item @emph{Arguments}: 11569@multitable @columnfractions .15 .70 11570@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 11571@end multitable 11572 11573@item @emph{Return value}: 11574The return value is of @code{REAL} type and the default kind. 11575 11576@item @emph{Example}: 11577@smallexample 11578program test_rand 11579 integer,parameter :: seed = 86456 11580 11581 call srand(seed) 11582 print *, rand(), rand(), rand(), rand() 11583 print *, rand(seed), rand(), rand(), rand() 11584end program test_rand 11585@end smallexample 11586 11587@item @emph{See also}: 11588@ref{SRAND}, @ref{RANDOM_NUMBER} 11589 11590@end table 11591 11592 11593 11594@node RANDOM_NUMBER 11595@section @code{RANDOM_NUMBER} --- Pseudo-random number 11596@fnindex RANDOM_NUMBER 11597@cindex random number generation 11598 11599@table @asis 11600@item @emph{Description}: 11601Returns a single pseudorandom number or an array of pseudorandom numbers 11602from the uniform distribution over the range @math{ 0 \leq x < 1}. 11603 11604The runtime-library implements the xorshift1024* random number 11605generator (RNG). This generator has a period of @math{2^{1024} - 1}, 11606and when using multiple threads up to @math{2^{512}} threads can each 11607generate @math{2^{512}} random numbers before any aliasing occurs. 11608 11609Note that in a multi-threaded program (e.g. using OpenMP directives), 11610each thread will have its own random number state. For details of the 11611seeding procedure, see the documentation for the @code{RANDOM_SEED} 11612intrinsic. 11613 11614 11615@item @emph{Standard}: 11616Fortran 95 and later 11617 11618@item @emph{Class}: 11619Subroutine 11620 11621@item @emph{Syntax}: 11622@code{RANDOM_NUMBER(HARVEST)} 11623 11624@item @emph{Arguments}: 11625@multitable @columnfractions .15 .70 11626@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}. 11627@end multitable 11628 11629@item @emph{Example}: 11630@smallexample 11631program test_random_number 11632 REAL :: r(5,5) 11633 CALL RANDOM_NUMBER(r) 11634end program 11635@end smallexample 11636 11637@item @emph{See also}: 11638@ref{RANDOM_SEED} 11639@end table 11640 11641 11642 11643@node RANDOM_SEED 11644@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence 11645@fnindex RANDOM_SEED 11646@cindex random number generation, seeding 11647@cindex seeding a random number generator 11648 11649@table @asis 11650@item @emph{Description}: 11651Restarts or queries the state of the pseudorandom number generator used by 11652@code{RANDOM_NUMBER}. 11653 11654If @code{RANDOM_SEED} is called without arguments, it is seeded with 11655random data retrieved from the operating system. 11656 11657As an extension to the Fortran standard, the GFortran 11658@code{RANDOM_NUMBER} supports multiple threads. Each thread in a 11659multi-threaded program has its own seed. When @code{RANDOM_SEED} is 11660called either without arguments or with the @var{PUT} argument, the 11661given seed is copied into a master seed as well as the seed of the 11662current thread. When a new thread uses @code{RANDOM_NUMBER} for the 11663first time, the seed is copied from the master seed, and forwarded 11664@math{N * 2^{512}} steps to guarantee that the random stream does not 11665alias any other stream in the system, where @var{N} is the number of 11666threads that have used @code{RANDOM_NUMBER} so far during the program 11667execution. 11668 11669@item @emph{Standard}: 11670Fortran 95 and later 11671 11672@item @emph{Class}: 11673Subroutine 11674 11675@item @emph{Syntax}: 11676@code{CALL RANDOM_SEED([SIZE, PUT, GET])} 11677 11678@item @emph{Arguments}: 11679@multitable @columnfractions .15 .70 11680@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default 11681@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size 11682of the arrays used with the @var{PUT} and @var{GET} arguments. 11683@item @var{PUT} @tab (Optional) Shall be an array of type default 11684@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of 11685the array must be larger than or equal to the number returned by the 11686@var{SIZE} argument. 11687@item @var{GET} @tab (Optional) Shall be an array of type default 11688@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size 11689of the array must be larger than or equal to the number returned by 11690the @var{SIZE} argument. 11691@end multitable 11692 11693@item @emph{Example}: 11694@smallexample 11695program test_random_seed 11696 implicit none 11697 integer, allocatable :: seed(:) 11698 integer :: n 11699 11700 call random_seed(size = n) 11701 allocate(seed(n)) 11702 call random_seed(get=seed) 11703 write (*, *) seed 11704end program test_random_seed 11705@end smallexample 11706 11707@item @emph{See also}: 11708@ref{RANDOM_NUMBER} 11709@end table 11710 11711 11712 11713@node RANGE 11714@section @code{RANGE} --- Decimal exponent range 11715@fnindex RANGE 11716@cindex model representation, range 11717 11718@table @asis 11719@item @emph{Description}: 11720@code{RANGE(X)} returns the decimal exponent range in the model of the 11721type of @code{X}. 11722 11723@item @emph{Standard}: 11724Fortran 95 and later 11725 11726@item @emph{Class}: 11727Inquiry function 11728 11729@item @emph{Syntax}: 11730@code{RESULT = RANGE(X)} 11731 11732@item @emph{Arguments}: 11733@multitable @columnfractions .15 .70 11734@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL} 11735or @code{COMPLEX}. 11736@end multitable 11737 11738@item @emph{Return value}: 11739The return value is of type @code{INTEGER} and of the default integer 11740kind. 11741 11742@item @emph{See also}: 11743@ref{SELECTED_REAL_KIND}, @ref{PRECISION} 11744 11745@item @emph{Example}: 11746See @code{PRECISION} for an example. 11747@end table 11748 11749 11750 11751@node RANK 11752@section @code{RANK} --- Rank of a data object 11753@fnindex RANK 11754@cindex rank 11755 11756@table @asis 11757@item @emph{Description}: 11758@code{RANK(A)} returns the rank of a scalar or array data object. 11759 11760@item @emph{Standard}: 11761Technical Specification (TS) 29113 11762 11763@item @emph{Class}: 11764Inquiry function 11765 11766@item @emph{Syntax}: 11767@code{RESULT = RANK(A)} 11768 11769@item @emph{Arguments}: 11770@multitable @columnfractions .15 .70 11771@item @var{A} @tab can be of any type 11772@end multitable 11773 11774@item @emph{Return value}: 11775The return value is of type @code{INTEGER} and of the default integer 11776kind. For arrays, their rank is returned; for scalars zero is returned. 11777 11778@item @emph{Example}: 11779@smallexample 11780program test_rank 11781 integer :: a 11782 real, allocatable :: b(:,:) 11783 11784 print *, rank(a), rank(b) ! Prints: 0 2 11785end program test_rank 11786@end smallexample 11787 11788@end table 11789 11790 11791 11792@node REAL 11793@section @code{REAL} --- Convert to real type 11794@fnindex REAL 11795@fnindex REALPART 11796@fnindex FLOAT 11797@fnindex DFLOAT 11798@fnindex FLOATI 11799@fnindex FLOATJ 11800@fnindex FLOATK 11801@fnindex SNGL 11802@cindex conversion, to real 11803@cindex complex numbers, real part 11804 11805@table @asis 11806@item @emph{Description}: 11807@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The 11808@code{REALPART} function is provided for compatibility with @command{g77}, 11809and its use is strongly discouraged. 11810 11811@item @emph{Standard}: 11812Fortran 77 and later 11813 11814@item @emph{Class}: 11815Elemental function 11816 11817@item @emph{Syntax}: 11818@multitable @columnfractions .80 11819@item @code{RESULT = REAL(A [, KIND])} 11820@item @code{RESULT = REALPART(Z)} 11821@end multitable 11822 11823@item @emph{Arguments}: 11824@multitable @columnfractions .15 .70 11825@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or 11826@code{COMPLEX}. 11827@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 11828expression indicating the kind parameter of the result. 11829@end multitable 11830 11831@item @emph{Return value}: 11832These functions return a @code{REAL} variable or array under 11833the following rules: 11834 11835@table @asis 11836@item (A) 11837@code{REAL(A)} is converted to a default real type if @var{A} is an 11838integer or real variable. 11839@item (B) 11840@code{REAL(A)} is converted to a real type with the kind type parameter 11841of @var{A} if @var{A} is a complex variable. 11842@item (C) 11843@code{REAL(A, KIND)} is converted to a real type with kind type 11844parameter @var{KIND} if @var{A} is a complex, integer, or real 11845variable. 11846@end table 11847 11848@item @emph{Example}: 11849@smallexample 11850program test_real 11851 complex :: x = (1.0, 2.0) 11852 print *, real(x), real(x,8), realpart(x) 11853end program test_real 11854@end smallexample 11855 11856@item @emph{Specific names}: 11857@multitable @columnfractions .20 .20 .20 .25 11858@item Name @tab Argument @tab Return type @tab Standard 11859@item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later 11860@item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension 11861@item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension 11862@item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension 11863@item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension 11864@item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later 11865@end multitable 11866 11867 11868@item @emph{See also}: 11869@ref{DBLE} 11870 11871@end table 11872 11873 11874 11875@node RENAME 11876@section @code{RENAME} --- Rename a file 11877@fnindex RENAME 11878@cindex file system, rename file 11879 11880@table @asis 11881@item @emph{Description}: 11882Renames a file from file @var{PATH1} to @var{PATH2}. A null 11883character (@code{CHAR(0)}) can be used to mark the end of the names in 11884@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 11885names are ignored. If the @var{STATUS} argument is supplied, it 11886contains 0 on success or a nonzero error code upon return; see 11887@code{rename(2)}. 11888 11889This intrinsic is provided in both subroutine and function forms; 11890however, only one form can be used in any given program unit. 11891 11892@item @emph{Standard}: 11893GNU extension 11894 11895@item @emph{Class}: 11896Subroutine, function 11897 11898@item @emph{Syntax}: 11899@multitable @columnfractions .80 11900@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])} 11901@item @code{STATUS = RENAME(PATH1, PATH2)} 11902@end multitable 11903 11904@item @emph{Arguments}: 11905@multitable @columnfractions .15 .70 11906@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 11907@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 11908@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 11909@end multitable 11910 11911@item @emph{See also}: 11912@ref{LINK} 11913 11914@end table 11915 11916 11917 11918@node REPEAT 11919@section @code{REPEAT} --- Repeated string concatenation 11920@fnindex REPEAT 11921@cindex string, repeat 11922@cindex string, concatenate 11923 11924@table @asis 11925@item @emph{Description}: 11926Concatenates @var{NCOPIES} copies of a string. 11927 11928@item @emph{Standard}: 11929Fortran 95 and later 11930 11931@item @emph{Class}: 11932Transformational function 11933 11934@item @emph{Syntax}: 11935@code{RESULT = REPEAT(STRING, NCOPIES)} 11936 11937@item @emph{Arguments}: 11938@multitable @columnfractions .15 .70 11939@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}. 11940@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}. 11941@end multitable 11942 11943@item @emph{Return value}: 11944A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies 11945of @var{STRING}. 11946 11947@item @emph{Example}: 11948@smallexample 11949program test_repeat 11950 write(*,*) repeat("x", 5) ! "xxxxx" 11951end program 11952@end smallexample 11953@end table 11954 11955 11956 11957@node RESHAPE 11958@section @code{RESHAPE} --- Function to reshape an array 11959@fnindex RESHAPE 11960@cindex array, change dimensions 11961@cindex array, transmogrify 11962 11963@table @asis 11964@item @emph{Description}: 11965Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary, 11966the new array may be padded with elements from @var{PAD} or permuted 11967as defined by @var{ORDER}. 11968 11969@item @emph{Standard}: 11970Fortran 95 and later 11971 11972@item @emph{Class}: 11973Transformational function 11974 11975@item @emph{Syntax}: 11976@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])} 11977 11978@item @emph{Arguments}: 11979@multitable @columnfractions .15 .70 11980@item @var{SOURCE} @tab Shall be an array of any type. 11981@item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an 11982array of rank one. Its values must be positive or zero. 11983@item @var{PAD} @tab (Optional) shall be an array of the same 11984type as @var{SOURCE}. 11985@item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER} 11986and an array of the same shape as @var{SHAPE}. Its values shall 11987be a permutation of the numbers from 1 to n, where n is the size of 11988@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall 11989be assumed. 11990@end multitable 11991 11992@item @emph{Return value}: 11993The result is an array of shape @var{SHAPE} with the same type as 11994@var{SOURCE}. 11995 11996@item @emph{Example}: 11997@smallexample 11998PROGRAM test_reshape 11999 INTEGER, DIMENSION(4) :: x 12000 WRITE(*,*) SHAPE(x) ! prints "4" 12001 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" 12002END PROGRAM 12003@end smallexample 12004 12005@item @emph{See also}: 12006@ref{SHAPE} 12007@end table 12008 12009 12010 12011@node RRSPACING 12012@section @code{RRSPACING} --- Reciprocal of the relative spacing 12013@fnindex RRSPACING 12014@cindex real number, relative spacing 12015@cindex floating point, relative spacing 12016 12017 12018@table @asis 12019@item @emph{Description}: 12020@code{RRSPACING(X)} returns the reciprocal of the relative spacing of 12021model numbers near @var{X}. 12022 12023@item @emph{Standard}: 12024Fortran 95 and later 12025 12026@item @emph{Class}: 12027Elemental function 12028 12029@item @emph{Syntax}: 12030@code{RESULT = RRSPACING(X)} 12031 12032@item @emph{Arguments}: 12033@multitable @columnfractions .15 .70 12034@item @var{X} @tab Shall be of type @code{REAL}. 12035@end multitable 12036 12037@item @emph{Return value}: 12038The return value is of the same type and kind as @var{X}. 12039The value returned is equal to 12040@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}. 12041 12042@item @emph{See also}: 12043@ref{SPACING} 12044@end table 12045 12046 12047 12048@node RSHIFT 12049@section @code{RSHIFT} --- Right shift bits 12050@fnindex RSHIFT 12051@cindex bits, shift right 12052 12053@table @asis 12054@item @emph{Description}: 12055@code{RSHIFT} returns a value corresponding to @var{I} with all of the 12056bits shifted right by @var{SHIFT} places. If the absolute value of 12057@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 12058Bits shifted out from the right end are lost. The fill is arithmetic: the 12059bits shifted in from the left end are equal to the leftmost bit, which in 12060two's complement representation is the sign bit. 12061 12062This function has been superseded by the @code{SHIFTA} intrinsic, which 12063is standard in Fortran 2008 and later. 12064 12065@item @emph{Standard}: 12066GNU extension 12067 12068@item @emph{Class}: 12069Elemental function 12070 12071@item @emph{Syntax}: 12072@code{RESULT = RSHIFT(I, SHIFT)} 12073 12074@item @emph{Arguments}: 12075@multitable @columnfractions .15 .70 12076@item @var{I} @tab The type shall be @code{INTEGER}. 12077@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12078@end multitable 12079 12080@item @emph{Return value}: 12081The return value is of type @code{INTEGER} and of the same kind as 12082@var{I}. 12083 12084@item @emph{See also}: 12085@ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR}, 12086@ref{SHIFTL} 12087 12088@end table 12089 12090 12091 12092@node SAME_TYPE_AS 12093@section @code{SAME_TYPE_AS} --- Query dynamic types for equality 12094@fnindex SAME_TYPE_AS 12095 12096@table @asis 12097@item @emph{Description}: 12098Query dynamic types for equality. 12099 12100@item @emph{Standard}: 12101Fortran 2003 and later 12102 12103@item @emph{Class}: 12104Inquiry function 12105 12106@item @emph{Syntax}: 12107@code{RESULT = SAME_TYPE_AS(A, B)} 12108 12109@item @emph{Arguments}: 12110@multitable @columnfractions .15 .70 12111@item @var{A} @tab Shall be an object of extensible declared type or 12112unlimited polymorphic. 12113@item @var{B} @tab Shall be an object of extensible declared type or 12114unlimited polymorphic. 12115@end multitable 12116 12117@item @emph{Return value}: 12118The return value is a scalar of type default logical. It is true if and 12119only if the dynamic type of A is the same as the dynamic type of B. 12120 12121@item @emph{See also}: 12122@ref{EXTENDS_TYPE_OF} 12123 12124@end table 12125 12126 12127 12128@node SCALE 12129@section @code{SCALE} --- Scale a real value 12130@fnindex SCALE 12131@cindex real number, scale 12132@cindex floating point, scale 12133 12134@table @asis 12135@item @emph{Description}: 12136@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}. 12137 12138@item @emph{Standard}: 12139Fortran 95 and later 12140 12141@item @emph{Class}: 12142Elemental function 12143 12144@item @emph{Syntax}: 12145@code{RESULT = SCALE(X, I)} 12146 12147@item @emph{Arguments}: 12148@multitable @columnfractions .15 .70 12149@item @var{X} @tab The type of the argument shall be a @code{REAL}. 12150@item @var{I} @tab The type of the argument shall be a @code{INTEGER}. 12151@end multitable 12152 12153@item @emph{Return value}: 12154The return value is of the same type and kind as @var{X}. 12155Its value is @code{X * RADIX(X)**I}. 12156 12157@item @emph{Example}: 12158@smallexample 12159program test_scale 12160 real :: x = 178.1387e-4 12161 integer :: i = 5 12162 print *, scale(x,i), x*radix(x)**i 12163end program test_scale 12164@end smallexample 12165 12166@end table 12167 12168 12169 12170@node SCAN 12171@section @code{SCAN} --- Scan a string for the presence of a set of characters 12172@fnindex SCAN 12173@cindex string, find subset 12174 12175@table @asis 12176@item @emph{Description}: 12177Scans a @var{STRING} for any of the characters in a @var{SET} 12178of characters. 12179 12180If @var{BACK} is either absent or equals @code{FALSE}, this function 12181returns the position of the leftmost character of @var{STRING} that is 12182in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position 12183is returned. If no character of @var{SET} is found in @var{STRING}, the 12184result is zero. 12185 12186@item @emph{Standard}: 12187Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 12188 12189@item @emph{Class}: 12190Elemental function 12191 12192@item @emph{Syntax}: 12193@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])} 12194 12195@item @emph{Arguments}: 12196@multitable @columnfractions .15 .70 12197@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 12198@item @var{SET} @tab Shall be of type @code{CHARACTER}. 12199@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 12200@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12201expression indicating the kind parameter of the result. 12202@end multitable 12203 12204@item @emph{Return value}: 12205The return value is of type @code{INTEGER} and of kind @var{KIND}. If 12206@var{KIND} is absent, the return value is of default integer kind. 12207 12208@item @emph{Example}: 12209@smallexample 12210PROGRAM test_scan 12211 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O' 12212 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A' 12213 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none 12214END PROGRAM 12215@end smallexample 12216 12217@item @emph{See also}: 12218@ref{INDEX intrinsic}, @ref{VERIFY} 12219@end table 12220 12221 12222 12223@node SECNDS 12224@section @code{SECNDS} --- Time function 12225@fnindex SECNDS 12226@cindex time, elapsed 12227@cindex elapsed time 12228 12229@table @asis 12230@item @emph{Description}: 12231@code{SECNDS(X)} gets the time in seconds from the real-time system clock. 12232@var{X} is a reference time, also in seconds. If this is zero, the time in 12233seconds from midnight is returned. This function is non-standard and its 12234use is discouraged. 12235 12236@item @emph{Standard}: 12237GNU extension 12238 12239@item @emph{Class}: 12240Function 12241 12242@item @emph{Syntax}: 12243@code{RESULT = SECNDS (X)} 12244 12245@item @emph{Arguments}: 12246@multitable @columnfractions .15 .70 12247@item @var{T} @tab Shall be of type @code{REAL(4)}. 12248@item @var{X} @tab Shall be of type @code{REAL(4)}. 12249@end multitable 12250 12251@item @emph{Return value}: 12252None 12253 12254@item @emph{Example}: 12255@smallexample 12256program test_secnds 12257 integer :: i 12258 real(4) :: t1, t2 12259 print *, secnds (0.0) ! seconds since midnight 12260 t1 = secnds (0.0) ! reference time 12261 do i = 1, 10000000 ! do something 12262 end do 12263 t2 = secnds (t1) ! elapsed time 12264 print *, "Something took ", t2, " seconds." 12265end program test_secnds 12266@end smallexample 12267@end table 12268 12269 12270 12271@node SECOND 12272@section @code{SECOND} --- CPU time function 12273@fnindex SECOND 12274@cindex time, elapsed 12275@cindex elapsed time 12276 12277@table @asis 12278@item @emph{Description}: 12279Returns a @code{REAL(4)} value representing the elapsed CPU time in 12280seconds. This provides the same functionality as the standard 12281@code{CPU_TIME} intrinsic, and is only included for backwards 12282compatibility. 12283 12284This intrinsic is provided in both subroutine and function forms; 12285however, only one form can be used in any given program unit. 12286 12287@item @emph{Standard}: 12288GNU extension 12289 12290@item @emph{Class}: 12291Subroutine, function 12292 12293@item @emph{Syntax}: 12294@multitable @columnfractions .80 12295@item @code{CALL SECOND(TIME)} 12296@item @code{TIME = SECOND()} 12297@end multitable 12298 12299@item @emph{Arguments}: 12300@multitable @columnfractions .15 .70 12301@item @var{TIME} @tab Shall be of type @code{REAL(4)}. 12302@end multitable 12303 12304@item @emph{Return value}: 12305In either syntax, @var{TIME} is set to the process's current runtime in 12306seconds. 12307 12308@item @emph{See also}: 12309@ref{CPU_TIME} 12310 12311@end table 12312 12313 12314 12315@node SELECTED_CHAR_KIND 12316@section @code{SELECTED_CHAR_KIND} --- Choose character kind 12317@fnindex SELECTED_CHAR_KIND 12318@cindex character kind 12319@cindex kind, character 12320 12321@table @asis 12322@item @emph{Description}: 12323 12324@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character 12325set named @var{NAME}, if a character set with such a name is supported, 12326or @math{-1} otherwise. Currently, supported character sets include 12327``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646'' 12328(Universal Character Set, UCS-4) which is commonly known as Unicode. 12329 12330@item @emph{Standard}: 12331Fortran 2003 and later 12332 12333@item @emph{Class}: 12334Transformational function 12335 12336@item @emph{Syntax}: 12337@code{RESULT = SELECTED_CHAR_KIND(NAME)} 12338 12339@item @emph{Arguments}: 12340@multitable @columnfractions .15 .70 12341@item @var{NAME} @tab Shall be a scalar and of the default character type. 12342@end multitable 12343 12344@item @emph{Example}: 12345@smallexample 12346program character_kind 12347 use iso_fortran_env 12348 implicit none 12349 integer, parameter :: ascii = selected_char_kind ("ascii") 12350 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646') 12351 12352 character(kind=ascii, len=26) :: alphabet 12353 character(kind=ucs4, len=30) :: hello_world 12354 12355 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz" 12356 hello_world = ucs4_'Hello World and Ni Hao -- ' & 12357 // char (int (z'4F60'), ucs4) & 12358 // char (int (z'597D'), ucs4) 12359 12360 write (*,*) alphabet 12361 12362 open (output_unit, encoding='UTF-8') 12363 write (*,*) trim (hello_world) 12364end program character_kind 12365@end smallexample 12366@end table 12367 12368 12369 12370@node SELECTED_INT_KIND 12371@section @code{SELECTED_INT_KIND} --- Choose integer kind 12372@fnindex SELECTED_INT_KIND 12373@cindex integer kind 12374@cindex kind, integer 12375 12376@table @asis 12377@item @emph{Description}: 12378@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer 12379type that can represent all values ranging from @math{-10^R} (exclusive) 12380to @math{10^R} (exclusive). If there is no integer kind that accommodates 12381this range, @code{SELECTED_INT_KIND} returns @math{-1}. 12382 12383@item @emph{Standard}: 12384Fortran 95 and later 12385 12386@item @emph{Class}: 12387Transformational function 12388 12389@item @emph{Syntax}: 12390@code{RESULT = SELECTED_INT_KIND(R)} 12391 12392@item @emph{Arguments}: 12393@multitable @columnfractions .15 .70 12394@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}. 12395@end multitable 12396 12397@item @emph{Example}: 12398@smallexample 12399program large_integers 12400 integer,parameter :: k5 = selected_int_kind(5) 12401 integer,parameter :: k15 = selected_int_kind(15) 12402 integer(kind=k5) :: i5 12403 integer(kind=k15) :: i15 12404 12405 print *, huge(i5), huge(i15) 12406 12407 ! The following inequalities are always true 12408 print *, huge(i5) >= 10_k5**5-1 12409 print *, huge(i15) >= 10_k15**15-1 12410end program large_integers 12411@end smallexample 12412@end table 12413 12414 12415 12416@node SELECTED_REAL_KIND 12417@section @code{SELECTED_REAL_KIND} --- Choose real kind 12418@fnindex SELECTED_REAL_KIND 12419@cindex real kind 12420@cindex kind, real 12421@cindex radix, real 12422 12423@table @asis 12424@item @emph{Description}: 12425@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type 12426with decimal precision of at least @code{P} digits, exponent range of 12427at least @code{R}, and with a radix of @code{RADIX}. 12428 12429@item @emph{Standard}: 12430Fortran 95 and later, with @code{RADIX} Fortran 2008 or later 12431 12432@item @emph{Class}: 12433Transformational function 12434 12435@item @emph{Syntax}: 12436@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])} 12437 12438@item @emph{Arguments}: 12439@multitable @columnfractions .15 .70 12440@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12441@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12442@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12443@end multitable 12444Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall 12445be present; since Fortran 2008, they are assumed to be zero if absent. 12446 12447@item @emph{Return value}: 12448 12449@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of 12450a real data type with decimal precision of at least @code{P} digits, a 12451decimal exponent range of at least @code{R}, and with the requested 12452@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with 12453any radix can be returned. If more than one real data type meet the 12454criteria, the kind of the data type with the smallest decimal precision 12455is returned. If no real data type matches the criteria, the result is 12456@table @asis 12457@item -1 if the processor does not support a real data type with a 12458precision greater than or equal to @code{P}, but the @code{R} and 12459@code{RADIX} requirements can be fulfilled 12460@item -2 if the processor does not support a real type with an exponent 12461range greater than or equal to @code{R}, but @code{P} and @code{RADIX} 12462are fulfillable 12463@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements 12464are fulfillable 12465@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements 12466are fulfillable 12467@item -5 if there is no real type with the given @code{RADIX} 12468@end table 12469 12470@item @emph{See also}: 12471@ref{PRECISION}, @ref{RANGE}, @ref{RADIX} 12472 12473@item @emph{Example}: 12474@smallexample 12475program real_kinds 12476 integer,parameter :: p6 = selected_real_kind(6) 12477 integer,parameter :: p10r100 = selected_real_kind(10,100) 12478 integer,parameter :: r400 = selected_real_kind(r=400) 12479 real(kind=p6) :: x 12480 real(kind=p10r100) :: y 12481 real(kind=r400) :: z 12482 12483 print *, precision(x), range(x) 12484 print *, precision(y), range(y) 12485 print *, precision(z), range(z) 12486end program real_kinds 12487@end smallexample 12488@end table 12489 12490 12491 12492@node SET_EXPONENT 12493@section @code{SET_EXPONENT} --- Set the exponent of the model 12494@fnindex SET_EXPONENT 12495@cindex real number, set exponent 12496@cindex floating point, set exponent 12497 12498@table @asis 12499@item @emph{Description}: 12500@code{SET_EXPONENT(X, I)} returns the real number whose fractional part 12501is that that of @var{X} and whose exponent part is @var{I}. 12502 12503@item @emph{Standard}: 12504Fortran 95 and later 12505 12506@item @emph{Class}: 12507Elemental function 12508 12509@item @emph{Syntax}: 12510@code{RESULT = SET_EXPONENT(X, I)} 12511 12512@item @emph{Arguments}: 12513@multitable @columnfractions .15 .70 12514@item @var{X} @tab Shall be of type @code{REAL}. 12515@item @var{I} @tab Shall be of type @code{INTEGER}. 12516@end multitable 12517 12518@item @emph{Return value}: 12519The return value is of the same type and kind as @var{X}. 12520The real number whose fractional part 12521is that that of @var{X} and whose exponent part if @var{I} is returned; 12522it is @code{FRACTION(X) * RADIX(X)**I}. 12523 12524@item @emph{Example}: 12525@smallexample 12526PROGRAM test_setexp 12527 REAL :: x = 178.1387e-4 12528 INTEGER :: i = 17 12529 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i 12530END PROGRAM 12531@end smallexample 12532 12533@end table 12534 12535 12536 12537@node SHAPE 12538@section @code{SHAPE} --- Determine the shape of an array 12539@fnindex SHAPE 12540@cindex array, shape 12541 12542@table @asis 12543@item @emph{Description}: 12544Determines the shape of an array. 12545 12546@item @emph{Standard}: 12547Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 12548 12549@item @emph{Class}: 12550Inquiry function 12551 12552@item @emph{Syntax}: 12553@code{RESULT = SHAPE(SOURCE [, KIND])} 12554 12555@item @emph{Arguments}: 12556@multitable @columnfractions .15 .70 12557@item @var{SOURCE} @tab Shall be an array or scalar of any type. 12558If @var{SOURCE} is a pointer it must be associated and allocatable 12559arrays must be allocated. 12560@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12561expression indicating the kind parameter of the result. 12562@end multitable 12563 12564@item @emph{Return value}: 12565An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 12566has dimensions. The elements of the resulting array correspond to the extend 12567of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar, 12568the result is the rank one array of size zero. If @var{KIND} is absent, the 12569return value has the default integer kind otherwise the specified kind. 12570 12571@item @emph{Example}: 12572@smallexample 12573PROGRAM test_shape 12574 INTEGER, DIMENSION(-1:1, -1:2) :: A 12575 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) 12576 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) 12577END PROGRAM 12578@end smallexample 12579 12580@item @emph{See also}: 12581@ref{RESHAPE}, @ref{SIZE} 12582@end table 12583 12584 12585 12586@node SHIFTA 12587@section @code{SHIFTA} --- Right shift with fill 12588@fnindex SHIFTA 12589@cindex bits, shift right 12590@cindex shift, right with fill 12591 12592@table @asis 12593@item @emph{Description}: 12594@code{SHIFTA} returns a value corresponding to @var{I} with all of the 12595bits shifted right by @var{SHIFT} places. If the absolute value of 12596@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 12597Bits shifted out from the right end are lost. The fill is arithmetic: the 12598bits shifted in from the left end are equal to the leftmost bit, which in 12599two's complement representation is the sign bit. 12600 12601@item @emph{Standard}: 12602Fortran 2008 and later 12603 12604@item @emph{Class}: 12605Elemental function 12606 12607@item @emph{Syntax}: 12608@code{RESULT = SHIFTA(I, SHIFT)} 12609 12610@item @emph{Arguments}: 12611@multitable @columnfractions .15 .70 12612@item @var{I} @tab The type shall be @code{INTEGER}. 12613@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12614@end multitable 12615 12616@item @emph{Return value}: 12617The return value is of type @code{INTEGER} and of the same kind as 12618@var{I}. 12619 12620@item @emph{See also}: 12621@ref{SHIFTL}, @ref{SHIFTR} 12622@end table 12623 12624 12625 12626@node SHIFTL 12627@section @code{SHIFTL} --- Left shift 12628@fnindex SHIFTL 12629@cindex bits, shift left 12630@cindex shift, left 12631 12632@table @asis 12633@item @emph{Description}: 12634@code{SHIFTL} returns a value corresponding to @var{I} with all of the 12635bits shifted left by @var{SHIFT} places. If the absolute value of 12636@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 12637Bits shifted out from the left end are lost, and bits shifted in from 12638the right end are set to 0. 12639 12640@item @emph{Standard}: 12641Fortran 2008 and later 12642 12643@item @emph{Class}: 12644Elemental function 12645 12646@item @emph{Syntax}: 12647@code{RESULT = SHIFTL(I, SHIFT)} 12648 12649@item @emph{Arguments}: 12650@multitable @columnfractions .15 .70 12651@item @var{I} @tab The type shall be @code{INTEGER}. 12652@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12653@end multitable 12654 12655@item @emph{Return value}: 12656The return value is of type @code{INTEGER} and of the same kind as 12657@var{I}. 12658 12659@item @emph{See also}: 12660@ref{SHIFTA}, @ref{SHIFTR} 12661@end table 12662 12663 12664 12665@node SHIFTR 12666@section @code{SHIFTR} --- Right shift 12667@fnindex SHIFTR 12668@cindex bits, shift right 12669@cindex shift, right 12670 12671@table @asis 12672@item @emph{Description}: 12673@code{SHIFTR} returns a value corresponding to @var{I} with all of the 12674bits shifted right by @var{SHIFT} places. If the absolute value of 12675@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 12676Bits shifted out from the right end are lost, and bits shifted in from 12677the left end are set to 0. 12678 12679@item @emph{Standard}: 12680Fortran 2008 and later 12681 12682@item @emph{Class}: 12683Elemental function 12684 12685@item @emph{Syntax}: 12686@code{RESULT = SHIFTR(I, SHIFT)} 12687 12688@item @emph{Arguments}: 12689@multitable @columnfractions .15 .70 12690@item @var{I} @tab The type shall be @code{INTEGER}. 12691@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12692@end multitable 12693 12694@item @emph{Return value}: 12695The return value is of type @code{INTEGER} and of the same kind as 12696@var{I}. 12697 12698@item @emph{See also}: 12699@ref{SHIFTA}, @ref{SHIFTL} 12700@end table 12701 12702 12703 12704@node SIGN 12705@section @code{SIGN} --- Sign copying function 12706@fnindex SIGN 12707@fnindex ISIGN 12708@fnindex DSIGN 12709@cindex sign copying 12710 12711@table @asis 12712@item @emph{Description}: 12713@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}. 12714 12715@item @emph{Standard}: 12716Fortran 77 and later 12717 12718@item @emph{Class}: 12719Elemental function 12720 12721@item @emph{Syntax}: 12722@code{RESULT = SIGN(A, B)} 12723 12724@item @emph{Arguments}: 12725@multitable @columnfractions .15 .70 12726@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL} 12727@item @var{B} @tab Shall be of the same type and kind as @var{A} 12728@end multitable 12729 12730@item @emph{Return value}: 12731The kind of the return value is that of @var{A} and @var{B}. 12732If @math{B\ge 0} then the result is @code{ABS(A)}, else 12733it is @code{-ABS(A)}. 12734 12735@item @emph{Example}: 12736@smallexample 12737program test_sign 12738 print *, sign(-12,1) 12739 print *, sign(-12,0) 12740 print *, sign(-12,-1) 12741 12742 print *, sign(-12.,1.) 12743 print *, sign(-12.,0.) 12744 print *, sign(-12.,-1.) 12745end program test_sign 12746@end smallexample 12747 12748@item @emph{Specific names}: 12749@multitable @columnfractions .20 .20 .20 .25 12750@item Name @tab Arguments @tab Return type @tab Standard 12751@item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu 12752@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu 12753@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu 12754@end multitable 12755@end table 12756 12757 12758 12759@node SIGNAL 12760@section @code{SIGNAL} --- Signal handling subroutine (or function) 12761@fnindex SIGNAL 12762@cindex system, signal handling 12763 12764@table @asis 12765@item @emph{Description}: 12766@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine 12767@var{HANDLER} to be executed with a single integer argument when signal 12768@var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to 12769turn off handling of signal @var{NUMBER} or revert to its default 12770action. See @code{signal(2)}. 12771 12772If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument 12773is supplied, it is set to the value returned by @code{signal(2)}. 12774 12775@item @emph{Standard}: 12776GNU extension 12777 12778@item @emph{Class}: 12779Subroutine, function 12780 12781@item @emph{Syntax}: 12782@multitable @columnfractions .80 12783@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])} 12784@item @code{STATUS = SIGNAL(NUMBER, HANDLER)} 12785@end multitable 12786 12787@item @emph{Arguments}: 12788@multitable @columnfractions .15 .70 12789@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)} 12790@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or 12791@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. 12792@code{INTEGER}. It is @code{INTENT(IN)}. 12793@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 12794integer. It has @code{INTENT(OUT)}. 12795@end multitable 12796@c TODO: What should the interface of the handler be? Does it take arguments? 12797 12798@item @emph{Return value}: 12799The @code{SIGNAL} function returns the value returned by @code{signal(2)}. 12800 12801@item @emph{Example}: 12802@smallexample 12803program test_signal 12804 intrinsic signal 12805 external handler_print 12806 12807 call signal (12, handler_print) 12808 call signal (10, 1) 12809 12810 call sleep (30) 12811end program test_signal 12812@end smallexample 12813@end table 12814 12815 12816 12817@node SIN 12818@section @code{SIN} --- Sine function 12819@fnindex SIN 12820@fnindex DSIN 12821@fnindex CSIN 12822@fnindex ZSIN 12823@fnindex CDSIN 12824@cindex trigonometric function, sine 12825@cindex sine 12826 12827@table @asis 12828@item @emph{Description}: 12829@code{SIN(X)} computes the sine of @var{X}. 12830 12831@item @emph{Standard}: 12832Fortran 77 and later 12833 12834@item @emph{Class}: 12835Elemental function 12836 12837@item @emph{Syntax}: 12838@code{RESULT = SIN(X)} 12839 12840@item @emph{Arguments}: 12841@multitable @columnfractions .15 .70 12842@item @var{X} @tab The type shall be @code{REAL} or 12843@code{COMPLEX}. 12844@end multitable 12845 12846@item @emph{Return value}: 12847The return value has same type and kind as @var{X}. 12848 12849@item @emph{Example}: 12850@smallexample 12851program test_sin 12852 real :: x = 0.0 12853 x = sin(x) 12854end program test_sin 12855@end smallexample 12856 12857@item @emph{Specific names}: 12858@multitable @columnfractions .20 .20 .20 .25 12859@item Name @tab Argument @tab Return type @tab Standard 12860@item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu 12861@item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu 12862@item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu 12863@item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 12864@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 12865@end multitable 12866 12867@item @emph{See also}: 12868Inverse function: @ref{ASIN} 12869Degrees function: @ref{SIND} 12870@end table 12871 12872 12873 12874@node SIND 12875@section @code{SIND} --- Sine function, degrees 12876@fnindex SIND 12877@fnindex DSIND 12878@fnindex CSIND 12879@fnindex ZSIND 12880@fnindex CDSIND 12881@cindex trigonometric function, sine, degrees 12882@cindex sine, degrees 12883 12884@table @asis 12885@item @emph{Description}: 12886@code{SIND(X)} computes the sine of @var{X} in degrees. 12887 12888This function is for compatibility only and should be avoided in favor of 12889standard constructs wherever possible. 12890 12891@item @emph{Standard}: 12892GNU Extension, enabled with @option{-fdec-math}. 12893 12894@item @emph{Class}: 12895Elemental function 12896 12897@item @emph{Syntax}: 12898@code{RESULT = SIND(X)} 12899 12900@item @emph{Arguments}: 12901@multitable @columnfractions .15 .70 12902@item @var{X} @tab The type shall be @code{REAL} or 12903@code{COMPLEX}. 12904@end multitable 12905 12906@item @emph{Return value}: 12907The return value has same type and kind as @var{X}, and its value is in degrees. 12908 12909@item @emph{Example}: 12910@smallexample 12911program test_sind 12912 real :: x = 0.0 12913 x = sind(x) 12914end program test_sind 12915@end smallexample 12916 12917@item @emph{Specific names}: 12918@multitable @columnfractions .20 .20 .20 .25 12919@item Name @tab Argument @tab Return type @tab Standard 12920@item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 12921@item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 12922@item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension 12923@item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension 12924@item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension 12925@end multitable 12926 12927@item @emph{See also}: 12928Inverse function: @ref{ASIND} 12929Radians function: @ref{SIN} 12930 12931@end table 12932 12933 12934 12935@node SINH 12936@section @code{SINH} --- Hyperbolic sine function 12937@fnindex SINH 12938@fnindex DSINH 12939@cindex hyperbolic sine 12940@cindex hyperbolic function, sine 12941@cindex sine, hyperbolic 12942 12943@table @asis 12944@item @emph{Description}: 12945@code{SINH(X)} computes the hyperbolic sine of @var{X}. 12946 12947@item @emph{Standard}: 12948Fortran 95 and later, for a complex argument Fortran 2008 or later 12949 12950@item @emph{Class}: 12951Elemental function 12952 12953@item @emph{Syntax}: 12954@code{RESULT = SINH(X)} 12955 12956@item @emph{Arguments}: 12957@multitable @columnfractions .15 .70 12958@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 12959@end multitable 12960 12961@item @emph{Return value}: 12962The return value has same type and kind as @var{X}. 12963 12964@item @emph{Example}: 12965@smallexample 12966program test_sinh 12967 real(8) :: x = - 1.0_8 12968 x = sinh(x) 12969end program test_sinh 12970@end smallexample 12971 12972@item @emph{Specific names}: 12973@multitable @columnfractions .20 .20 .20 .25 12974@item Name @tab Argument @tab Return type @tab Standard 12975@item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 12976@item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 12977@end multitable 12978 12979@item @emph{See also}: 12980@ref{ASINH} 12981@end table 12982 12983 12984 12985@node SIZE 12986@section @code{SIZE} --- Determine the size of an array 12987@fnindex SIZE 12988@cindex array, size 12989@cindex array, number of elements 12990@cindex array, count elements 12991 12992@table @asis 12993@item @emph{Description}: 12994Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}, 12995or the total number of elements in @var{ARRAY} if @var{DIM} is absent. 12996 12997@item @emph{Standard}: 12998Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 12999 13000@item @emph{Class}: 13001Inquiry function 13002 13003@item @emph{Syntax}: 13004@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])} 13005 13006@item @emph{Arguments}: 13007@multitable @columnfractions .15 .70 13008@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is 13009a pointer it must be associated and allocatable arrays must be allocated. 13010@item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} 13011and its value shall be in the range from 1 to n, where n equals the rank 13012of @var{ARRAY}. 13013@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13014expression indicating the kind parameter of the result. 13015@end multitable 13016 13017@item @emph{Return value}: 13018The return value is of type @code{INTEGER} and of kind @var{KIND}. If 13019@var{KIND} is absent, the return value is of default integer kind. 13020 13021@item @emph{Example}: 13022@smallexample 13023PROGRAM test_size 13024 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 13025END PROGRAM 13026@end smallexample 13027 13028@item @emph{See also}: 13029@ref{SHAPE}, @ref{RESHAPE} 13030@end table 13031 13032 13033@node SIZEOF 13034@section @code{SIZEOF} --- Size in bytes of an expression 13035@fnindex SIZEOF 13036@cindex expression size 13037@cindex size of an expression 13038 13039@table @asis 13040@item @emph{Description}: 13041@code{SIZEOF(X)} calculates the number of bytes of storage the 13042expression @code{X} occupies. 13043 13044@item @emph{Standard}: 13045GNU extension 13046 13047@item @emph{Class}: 13048Inquiry function 13049 13050@item @emph{Syntax}: 13051@code{N = SIZEOF(X)} 13052 13053@item @emph{Arguments}: 13054@multitable @columnfractions .15 .70 13055@item @var{X} @tab The argument shall be of any type, rank or shape. 13056@end multitable 13057 13058@item @emph{Return value}: 13059The return value is of type integer and of the system-dependent kind 13060@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the 13061number of bytes occupied by the argument. If the argument has the 13062@code{POINTER} attribute, the number of bytes of the storage area pointed 13063to is returned. If the argument is of a derived type with @code{POINTER} 13064or @code{ALLOCATABLE} components, the return value does not account for 13065the sizes of the data pointed to by these components. If the argument is 13066polymorphic, the size according to the dynamic type is returned. The argument 13067may not be a procedure or procedure pointer. Note that the code assumes for 13068arrays that those are contiguous; for contiguous arrays, it returns the 13069storage or an array element multiplied by the size of the array. 13070 13071@item @emph{Example}: 13072@smallexample 13073 integer :: i 13074 real :: r, s(5) 13075 print *, (sizeof(s)/sizeof(r) == 5) 13076 end 13077@end smallexample 13078The example will print @code{.TRUE.} unless you are using a platform 13079where default @code{REAL} variables are unusually padded. 13080 13081@item @emph{See also}: 13082@ref{C_SIZEOF}, @ref{STORAGE_SIZE} 13083@end table 13084 13085 13086@node SLEEP 13087@section @code{SLEEP} --- Sleep for the specified number of seconds 13088@fnindex SLEEP 13089@cindex delayed execution 13090 13091@table @asis 13092@item @emph{Description}: 13093Calling this subroutine causes the process to pause for @var{SECONDS} seconds. 13094 13095@item @emph{Standard}: 13096GNU extension 13097 13098@item @emph{Class}: 13099Subroutine 13100 13101@item @emph{Syntax}: 13102@code{CALL SLEEP(SECONDS)} 13103 13104@item @emph{Arguments}: 13105@multitable @columnfractions .15 .70 13106@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}. 13107@end multitable 13108 13109@item @emph{Example}: 13110@smallexample 13111program test_sleep 13112 call sleep(5) 13113end 13114@end smallexample 13115@end table 13116 13117 13118 13119@node SPACING 13120@section @code{SPACING} --- Smallest distance between two numbers of a given type 13121@fnindex SPACING 13122@cindex real number, relative spacing 13123@cindex floating point, relative spacing 13124 13125@table @asis 13126@item @emph{Description}: 13127Determines the distance between the argument @var{X} and the nearest 13128adjacent number of the same type. 13129 13130@item @emph{Standard}: 13131Fortran 95 and later 13132 13133@item @emph{Class}: 13134Elemental function 13135 13136@item @emph{Syntax}: 13137@code{RESULT = SPACING(X)} 13138 13139@item @emph{Arguments}: 13140@multitable @columnfractions .15 .70 13141@item @var{X} @tab Shall be of type @code{REAL}. 13142@end multitable 13143 13144@item @emph{Return value}: 13145The result is of the same type as the input argument @var{X}. 13146 13147@item @emph{Example}: 13148@smallexample 13149PROGRAM test_spacing 13150 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37) 13151 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200) 13152 13153 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686 13154 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686 13155END PROGRAM 13156@end smallexample 13157 13158@item @emph{See also}: 13159@ref{RRSPACING} 13160@end table 13161 13162 13163 13164@node SPREAD 13165@section @code{SPREAD} --- Add a dimension to an array 13166@fnindex SPREAD 13167@cindex array, increase dimension 13168@cindex array, duplicate elements 13169@cindex array, duplicate dimensions 13170 13171@table @asis 13172@item @emph{Description}: 13173Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified 13174dimension @var{DIM}. 13175 13176@item @emph{Standard}: 13177Fortran 95 and later 13178 13179@item @emph{Class}: 13180Transformational function 13181 13182@item @emph{Syntax}: 13183@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)} 13184 13185@item @emph{Arguments}: 13186@multitable @columnfractions .15 .70 13187@item @var{SOURCE} @tab Shall be a scalar or an array of any type and 13188a rank less than seven. 13189@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a 13190value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}. 13191@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}. 13192@end multitable 13193 13194@item @emph{Return value}: 13195The result is an array of the same type as @var{SOURCE} and has rank n+1 13196where n equals the rank of @var{SOURCE}. 13197 13198@item @emph{Example}: 13199@smallexample 13200PROGRAM test_spread 13201 INTEGER :: a = 1, b(2) = (/ 1, 2 /) 13202 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1" 13203 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2" 13204END PROGRAM 13205@end smallexample 13206 13207@item @emph{See also}: 13208@ref{UNPACK} 13209@end table 13210 13211 13212 13213@node SQRT 13214@section @code{SQRT} --- Square-root function 13215@fnindex SQRT 13216@fnindex DSQRT 13217@fnindex CSQRT 13218@fnindex ZSQRT 13219@fnindex CDSQRT 13220@cindex root 13221@cindex square-root 13222 13223@table @asis 13224@item @emph{Description}: 13225@code{SQRT(X)} computes the square root of @var{X}. 13226 13227@item @emph{Standard}: 13228Fortran 77 and later 13229 13230@item @emph{Class}: 13231Elemental function 13232 13233@item @emph{Syntax}: 13234@code{RESULT = SQRT(X)} 13235 13236@item @emph{Arguments}: 13237@multitable @columnfractions .15 .70 13238@item @var{X} @tab The type shall be @code{REAL} or 13239@code{COMPLEX}. 13240@end multitable 13241 13242@item @emph{Return value}: 13243The return value is of type @code{REAL} or @code{COMPLEX}. 13244The kind type parameter is the same as @var{X}. 13245 13246@item @emph{Example}: 13247@smallexample 13248program test_sqrt 13249 real(8) :: x = 2.0_8 13250 complex :: z = (1.0, 2.0) 13251 x = sqrt(x) 13252 z = sqrt(z) 13253end program test_sqrt 13254@end smallexample 13255 13256@item @emph{Specific names}: 13257@multitable @columnfractions .20 .20 .20 .25 13258@item Name @tab Argument @tab Return type @tab Standard 13259@item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 13260@item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 13261@item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later 13262@item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13263@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13264@end multitable 13265@end table 13266 13267 13268 13269@node SRAND 13270@section @code{SRAND} --- Reinitialize the random number generator 13271@fnindex SRAND 13272@cindex random number generation, seeding 13273@cindex seeding a random number generator 13274 13275@table @asis 13276@item @emph{Description}: 13277@code{SRAND} reinitializes the pseudo-random number generator 13278called by @code{RAND} and @code{IRAND}. The new seed used by the 13279generator is specified by the required argument @var{SEED}. 13280 13281@item @emph{Standard}: 13282GNU extension 13283 13284@item @emph{Class}: 13285Subroutine 13286 13287@item @emph{Syntax}: 13288@code{CALL SRAND(SEED)} 13289 13290@item @emph{Arguments}: 13291@multitable @columnfractions .15 .70 13292@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}. 13293@end multitable 13294 13295@item @emph{Return value}: 13296Does not return anything. 13297 13298@item @emph{Example}: 13299See @code{RAND} and @code{IRAND} for examples. 13300 13301@item @emph{Notes}: 13302The Fortran standard specifies the intrinsic subroutines 13303@code{RANDOM_SEED} to initialize the pseudo-random number 13304generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers. 13305These subroutines should be used in new codes. 13306 13307Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND}, 13308@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and 13309@code{RANDOM_SEED} on the other hand) access two independent 13310pseudo-random number generators. 13311 13312@item @emph{See also}: 13313@ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER} 13314 13315@end table 13316 13317 13318 13319@node STAT 13320@section @code{STAT} --- Get file status 13321@fnindex STAT 13322@cindex file system, file status 13323 13324@table @asis 13325@item @emph{Description}: 13326This function returns information about a file. No permissions are required on 13327the file itself, but execute (search) permission is required on all of the 13328directories in path that lead to the file. 13329 13330The elements that are obtained and stored in the array @code{VALUES}: 13331@multitable @columnfractions .15 .70 13332@item @code{VALUES(1)} @tab Device ID 13333@item @code{VALUES(2)} @tab Inode number 13334@item @code{VALUES(3)} @tab File mode 13335@item @code{VALUES(4)} @tab Number of links 13336@item @code{VALUES(5)} @tab Owner's uid 13337@item @code{VALUES(6)} @tab Owner's gid 13338@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available) 13339@item @code{VALUES(8)} @tab File size (bytes) 13340@item @code{VALUES(9)} @tab Last access time 13341@item @code{VALUES(10)} @tab Last modification time 13342@item @code{VALUES(11)} @tab Last file status change time 13343@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available) 13344@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available) 13345@end multitable 13346 13347Not all these elements are relevant on all systems. 13348If an element is not relevant, it is returned as 0. 13349 13350This intrinsic is provided in both subroutine and function forms; however, 13351only one form can be used in any given program unit. 13352 13353@item @emph{Standard}: 13354GNU extension 13355 13356@item @emph{Class}: 13357Subroutine, function 13358 13359@item @emph{Syntax}: 13360@multitable @columnfractions .80 13361@item @code{CALL STAT(NAME, VALUES [, STATUS])} 13362@item @code{STATUS = STAT(NAME, VALUES)} 13363@end multitable 13364 13365@item @emph{Arguments}: 13366@multitable @columnfractions .15 .70 13367@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the 13368default kind and a valid path within the file system. 13369@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 13370@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 13371on success and a system specific error code otherwise. 13372@end multitable 13373 13374@item @emph{Example}: 13375@smallexample 13376PROGRAM test_stat 13377 INTEGER, DIMENSION(13) :: buff 13378 INTEGER :: status 13379 13380 CALL STAT("/etc/passwd", buff, status) 13381 13382 IF (status == 0) THEN 13383 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1) 13384 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2) 13385 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3) 13386 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4) 13387 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5) 13388 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6) 13389 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7) 13390 WRITE (*, FMT="('File size:', T30, I19)") buff(8) 13391 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9)) 13392 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10)) 13393 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11)) 13394 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12) 13395 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13) 13396 END IF 13397END PROGRAM 13398@end smallexample 13399 13400@item @emph{See also}: 13401To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT} 13402@end table 13403 13404 13405 13406@node STORAGE_SIZE 13407@section @code{STORAGE_SIZE} --- Storage size in bits 13408@fnindex STORAGE_SIZE 13409@cindex storage size 13410 13411@table @asis 13412@item @emph{Description}: 13413Returns the storage size of argument @var{A} in bits. 13414@item @emph{Standard}: 13415Fortran 2008 and later 13416@item @emph{Class}: 13417Inquiry function 13418@item @emph{Syntax}: 13419@code{RESULT = STORAGE_SIZE(A [, KIND])} 13420 13421@item @emph{Arguments}: 13422@multitable @columnfractions .15 .70 13423@item @var{A} @tab Shall be a scalar or array of any type. 13424@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression. 13425@end multitable 13426 13427@item @emph{Return Value}: 13428The result is a scalar integer with the kind type parameter specified by KIND 13429(or default integer type if KIND is missing). The result value is the size 13430expressed in bits for an element of an array that has the dynamic type and type 13431parameters of A. 13432 13433@item @emph{See also}: 13434@ref{C_SIZEOF}, @ref{SIZEOF} 13435@end table 13436 13437 13438 13439@node SUM 13440@section @code{SUM} --- Sum of array elements 13441@fnindex SUM 13442@cindex array, sum 13443@cindex array, add elements 13444@cindex array, conditionally add elements 13445@cindex sum array elements 13446 13447@table @asis 13448@item @emph{Description}: 13449Adds the elements of @var{ARRAY} along dimension @var{DIM} if 13450the corresponding element in @var{MASK} is @code{TRUE}. 13451 13452@item @emph{Standard}: 13453Fortran 95 and later 13454 13455@item @emph{Class}: 13456Transformational function 13457 13458@item @emph{Syntax}: 13459@multitable @columnfractions .80 13460@item @code{RESULT = SUM(ARRAY[, MASK])} 13461@item @code{RESULT = SUM(ARRAY, DIM[, MASK])} 13462@end multitable 13463 13464@item @emph{Arguments}: 13465@multitable @columnfractions .15 .70 13466@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 13467@code{REAL} or @code{COMPLEX}. 13468@item @var{DIM} @tab (Optional) shall be a scalar of type 13469@code{INTEGER} with a value in the range from 1 to n, where n 13470equals the rank of @var{ARRAY}. 13471@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 13472and either be a scalar or an array of the same shape as @var{ARRAY}. 13473@end multitable 13474 13475@item @emph{Return value}: 13476The result is of the same type as @var{ARRAY}. 13477 13478If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY} 13479is returned. Otherwise, an array of rank n-1, where n equals the rank of 13480@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} 13481dropped is returned. 13482 13483@item @emph{Example}: 13484@smallexample 13485PROGRAM test_sum 13486 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 13487 print *, SUM(x) ! all elements, sum = 15 13488 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9 13489END PROGRAM 13490@end smallexample 13491 13492@item @emph{See also}: 13493@ref{PRODUCT} 13494@end table 13495 13496 13497 13498@node SYMLNK 13499@section @code{SYMLNK} --- Create a symbolic link 13500@fnindex SYMLNK 13501@cindex file system, create link 13502@cindex file system, soft link 13503 13504@table @asis 13505@item @emph{Description}: 13506Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null 13507character (@code{CHAR(0)}) can be used to mark the end of the names in 13508@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 13509names are ignored. If the @var{STATUS} argument is supplied, it 13510contains 0 on success or a nonzero error code upon return; see 13511@code{symlink(2)}. If the system does not supply @code{symlink(2)}, 13512@code{ENOSYS} is returned. 13513 13514This intrinsic is provided in both subroutine and function forms; 13515however, only one form can be used in any given program unit. 13516 13517@item @emph{Standard}: 13518GNU extension 13519 13520@item @emph{Class}: 13521Subroutine, function 13522 13523@item @emph{Syntax}: 13524@multitable @columnfractions .80 13525@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])} 13526@item @code{STATUS = SYMLNK(PATH1, PATH2)} 13527@end multitable 13528 13529@item @emph{Arguments}: 13530@multitable @columnfractions .15 .70 13531@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 13532@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 13533@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13534@end multitable 13535 13536@item @emph{See also}: 13537@ref{LINK}, @ref{UNLINK} 13538 13539@end table 13540 13541 13542 13543@node SYSTEM 13544@section @code{SYSTEM} --- Execute a shell command 13545@fnindex SYSTEM 13546@cindex system, system call 13547 13548@table @asis 13549@item @emph{Description}: 13550Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If 13551argument @var{STATUS} is present, it contains the value returned by 13552@code{system(3)}, which is presumably 0 if the shell command succeeded. 13553Note that which shell is used to invoke the command is system-dependent 13554and environment-dependent. 13555 13556This intrinsic is provided in both subroutine and function forms; 13557however, only one form can be used in any given program unit. 13558 13559Note that the @code{system} function need not be thread-safe. It is 13560the responsibility of the user to ensure that @code{system} is not 13561called concurrently. 13562 13563@item @emph{Standard}: 13564GNU extension 13565 13566@item @emph{Class}: 13567Subroutine, function 13568 13569@item @emph{Syntax}: 13570@multitable @columnfractions .80 13571@item @code{CALL SYSTEM(COMMAND [, STATUS])} 13572@item @code{STATUS = SYSTEM(COMMAND)} 13573@end multitable 13574 13575@item @emph{Arguments}: 13576@multitable @columnfractions .15 .70 13577@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type. 13578@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13579@end multitable 13580 13581@item @emph{See also}: 13582@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard 13583and should considered in new code for future portability. 13584@end table 13585 13586 13587 13588@node SYSTEM_CLOCK 13589@section @code{SYSTEM_CLOCK} --- Time function 13590@fnindex SYSTEM_CLOCK 13591@cindex time, clock ticks 13592@cindex clock ticks 13593 13594@table @asis 13595@item @emph{Description}: 13596Determines the @var{COUNT} of a processor clock since an unspecified 13597time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines 13598the number of clock ticks per second. If the platform supports a 13599monotonic clock, that clock is used and can, depending on the platform 13600clock implementation, provide up to nanosecond resolution. If a 13601monotonic clock is not available, the implementation falls back to a 13602realtime clock. 13603 13604@var{COUNT_RATE} is system dependent and can vary depending on the kind of 13605the arguments. For @var{kind=4} arguments (and smaller integer kinds), 13606@var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and 13607larger integer kinds), @var{COUNT} typically represents micro- or 13608nanoseconds depending on resolution of the underlying platform clock. 13609@var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the 13610millisecond resolution of the @var{kind=4} version implies that the 13611@var{COUNT} will wrap around in roughly 25 days. In order to avoid issues 13612with the wrap around and for more precise timing, please use the 13613@var{kind=8} version. 13614 13615If there is no clock, or querying the clock fails, @var{COUNT} is set 13616to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are 13617set to zero. 13618 13619When running on a platform using the GNU C library (glibc) version 136202.16 or older, or a derivative thereof, the high resolution monotonic 13621clock is available only when linking with the @var{rt} library. This 13622can be done explicitly by adding the @code{-lrt} flag when linking the 13623application, but is also done implicitly when using OpenMP. 13624 13625On the Windows platform, the version with @var{kind=4} arguments uses 13626the @code{GetTickCount} function, whereas the @var{kind=8} version 13627uses @code{QueryPerformanceCounter} and 13628@code{QueryPerformanceCounterFrequency}. For more information, and 13629potential caveats, please see the platform documentation. 13630 13631@item @emph{Standard}: 13632Fortran 95 and later 13633 13634@item @emph{Class}: 13635Subroutine 13636 13637@item @emph{Syntax}: 13638@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} 13639 13640@item @emph{Arguments}: 13641@multitable @columnfractions .15 .70 13642@item @var{COUNT} @tab (Optional) shall be a scalar of type 13643@code{INTEGER} with @code{INTENT(OUT)}. 13644@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type 13645@code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}. 13646@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type 13647@code{INTEGER} with @code{INTENT(OUT)}. 13648@end multitable 13649 13650@item @emph{Example}: 13651@smallexample 13652PROGRAM test_system_clock 13653 INTEGER :: count, count_rate, count_max 13654 CALL SYSTEM_CLOCK(count, count_rate, count_max) 13655 WRITE(*,*) count, count_rate, count_max 13656END PROGRAM 13657@end smallexample 13658 13659@item @emph{See also}: 13660@ref{DATE_AND_TIME}, @ref{CPU_TIME} 13661@end table 13662 13663 13664 13665@node TAN 13666@section @code{TAN} --- Tangent function 13667@fnindex TAN 13668@fnindex DTAN 13669@cindex trigonometric function, tangent 13670@cindex tangent 13671 13672@table @asis 13673@item @emph{Description}: 13674@code{TAN(X)} computes the tangent of @var{X}. 13675 13676@item @emph{Standard}: 13677Fortran 77 and later, for a complex argument Fortran 2008 or later 13678 13679@item @emph{Class}: 13680Elemental function 13681 13682@item @emph{Syntax}: 13683@code{RESULT = TAN(X)} 13684 13685@item @emph{Arguments}: 13686@multitable @columnfractions .15 .70 13687@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13688@end multitable 13689 13690@item @emph{Return value}: 13691The return value has same type and kind as @var{X}, and its value is in radians. 13692 13693@item @emph{Example}: 13694@smallexample 13695program test_tan 13696 real(8) :: x = 0.165_8 13697 x = tan(x) 13698end program test_tan 13699@end smallexample 13700 13701@item @emph{Specific names}: 13702@multitable @columnfractions .20 .20 .20 .25 13703@item Name @tab Argument @tab Return type @tab Standard 13704@item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 13705@item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 13706@end multitable 13707 13708@item @emph{See also}: 13709Inverse function: @ref{ATAN} 13710Degrees function: @ref{TAND} 13711@end table 13712 13713 13714 13715@node TAND 13716@section @code{TAND} --- Tangent function, degrees 13717@fnindex TAND 13718@fnindex DTAND 13719@cindex trigonometric function, tangent, degrees 13720@cindex tangent, degrees 13721 13722@table @asis 13723@item @emph{Description}: 13724@code{TAND(X)} computes the tangent of @var{X} in degrees. 13725 13726This function is for compatibility only and should be avoided in favor of 13727standard constructs wherever possible. 13728 13729@item @emph{Standard}: 13730GNU Extension, enabled with @option{-fdec-math}. 13731 13732@item @emph{Class}: 13733Elemental function 13734 13735@item @emph{Syntax}: 13736@code{RESULT = TAND(X)} 13737 13738@item @emph{Arguments}: 13739@multitable @columnfractions .15 .70 13740@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13741@end multitable 13742 13743@item @emph{Return value}: 13744The return value has same type and kind as @var{X}, and its value is in degrees. 13745 13746@item @emph{Example}: 13747@smallexample 13748program test_tand 13749 real(8) :: x = 0.165_8 13750 x = tand(x) 13751end program test_tand 13752@end smallexample 13753 13754@item @emph{Specific names}: 13755@multitable @columnfractions .20 .20 .20 .25 13756@item Name @tab Argument @tab Return type @tab Standard 13757@item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 13758@item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 13759@end multitable 13760 13761@item @emph{See also}: 13762Inverse function: @ref{ATAND} 13763Radians function: @ref{TAN} 13764@end table 13765 13766 13767 13768@node TANH 13769@section @code{TANH} --- Hyperbolic tangent function 13770@fnindex TANH 13771@fnindex DTANH 13772@cindex hyperbolic tangent 13773@cindex hyperbolic function, tangent 13774@cindex tangent, hyperbolic 13775 13776@table @asis 13777@item @emph{Description}: 13778@code{TANH(X)} computes the hyperbolic tangent of @var{X}. 13779 13780@item @emph{Standard}: 13781Fortran 77 and later, for a complex argument Fortran 2008 or later 13782 13783@item @emph{Class}: 13784Elemental function 13785 13786@item @emph{Syntax}: 13787@code{X = TANH(X)} 13788 13789@item @emph{Arguments}: 13790@multitable @columnfractions .15 .70 13791@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13792@end multitable 13793 13794@item @emph{Return value}: 13795The return value has same type and kind as @var{X}. If @var{X} is 13796complex, the imaginary part of the result is in radians. If @var{X} 13797is @code{REAL}, the return value lies in the range 13798@math{ - 1 \leq tanh(x) \leq 1 }. 13799 13800@item @emph{Example}: 13801@smallexample 13802program test_tanh 13803 real(8) :: x = 2.1_8 13804 x = tanh(x) 13805end program test_tanh 13806@end smallexample 13807 13808@item @emph{Specific names}: 13809@multitable @columnfractions .20 .20 .20 .25 13810@item Name @tab Argument @tab Return type @tab Standard 13811@item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 13812@item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 13813@end multitable 13814 13815@item @emph{See also}: 13816@ref{ATANH} 13817@end table 13818 13819 13820 13821@node THIS_IMAGE 13822@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image 13823@fnindex THIS_IMAGE 13824@cindex coarray, @code{THIS_IMAGE} 13825@cindex images, index of this image 13826 13827@table @asis 13828@item @emph{Description}: 13829Returns the cosubscript for this image. 13830 13831@item @emph{Standard}: 13832Fortran 2008 and later. With @var{DISTANCE} argument, 13833Technical Specification (TS) 18508 or later 13834 13835@item @emph{Class}: 13836Transformational function 13837 13838@item @emph{Syntax}: 13839@multitable @columnfractions .80 13840@item @code{RESULT = THIS_IMAGE()} 13841@item @code{RESULT = THIS_IMAGE(DISTANCE)} 13842@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} 13843@end multitable 13844 13845@item @emph{Arguments}: 13846@multitable @columnfractions .15 .70 13847@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 13848(not permitted together with @var{COARRAY}). 13849@item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} 13850present, required). 13851@item @var{DIM} @tab default integer scalar (optional). If present, 13852@var{DIM} shall be between one and the corank of @var{COARRAY}. 13853@end multitable 13854 13855 13856@item @emph{Return value}: 13857Default integer. If @var{COARRAY} is not present, it is scalar; if 13858@var{DISTANCE} is not present or has value 0, its value is the image index on 13859the invoking image for the current team, for values smaller or equal 13860distance to the initial team, it returns the image index on the ancestor team 13861which has a distance of @var{DISTANCE} from the invoking team. If 13862@var{DISTANCE} is larger than the distance to the initial team, the image 13863index of the initial team is returned. Otherwise when the @var{COARRAY} is 13864present, if @var{DIM} is not present, a rank-1 array with corank elements is 13865returned, containing the cosubscripts for @var{COARRAY} specifying the invoking 13866image. If @var{DIM} is present, a scalar is returned, with the value of 13867the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}. 13868 13869@item @emph{Example}: 13870@smallexample 13871INTEGER :: value[*] 13872INTEGER :: i 13873value = THIS_IMAGE() 13874SYNC ALL 13875IF (THIS_IMAGE() == 1) THEN 13876 DO i = 1, NUM_IMAGES() 13877 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 13878 END DO 13879END IF 13880 13881! Check whether the current image is the initial image 13882IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) 13883 error stop "something is rotten here" 13884@end smallexample 13885 13886@item @emph{See also}: 13887@ref{NUM_IMAGES}, @ref{IMAGE_INDEX} 13888@end table 13889 13890 13891 13892@node TIME 13893@section @code{TIME} --- Time function 13894@fnindex TIME 13895@cindex time, current 13896@cindex current time 13897 13898@table @asis 13899@item @emph{Description}: 13900Returns the current time encoded as an integer (in the manner of the 13901function @code{time(3)} in the C standard library). This value is 13902suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 13903 13904This intrinsic is not fully portable, such as to systems with 32-bit 13905@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 13906the values returned by this intrinsic might be, or become, negative, or 13907numerically less than previous values, during a single run of the 13908compiled program. 13909 13910See @ref{TIME8}, for information on a similar intrinsic that might be 13911portable to more GNU Fortran implementations, though to fewer Fortran 13912compilers. 13913 13914@item @emph{Standard}: 13915GNU extension 13916 13917@item @emph{Class}: 13918Function 13919 13920@item @emph{Syntax}: 13921@code{RESULT = TIME()} 13922 13923@item @emph{Return value}: 13924The return value is a scalar of type @code{INTEGER(4)}. 13925 13926@item @emph{See also}: 13927@ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} 13928 13929@end table 13930 13931 13932 13933@node TIME8 13934@section @code{TIME8} --- Time function (64-bit) 13935@fnindex TIME8 13936@cindex time, current 13937@cindex current time 13938 13939@table @asis 13940@item @emph{Description}: 13941Returns the current time encoded as an integer (in the manner of the 13942function @code{time(3)} in the C standard library). This value is 13943suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 13944 13945@emph{Warning:} this intrinsic does not increase the range of the timing 13946values over that returned by @code{time(3)}. On a system with a 32-bit 13947@code{time(3)}, @code{TIME8} will return a 32-bit value, even though 13948it is converted to a 64-bit @code{INTEGER(8)} value. That means 13949overflows of the 32-bit value can still occur. Therefore, the values 13950returned by this intrinsic might be or become negative or numerically 13951less than previous values during a single run of the compiled program. 13952 13953@item @emph{Standard}: 13954GNU extension 13955 13956@item @emph{Class}: 13957Function 13958 13959@item @emph{Syntax}: 13960@code{RESULT = TIME8()} 13961 13962@item @emph{Return value}: 13963The return value is a scalar of type @code{INTEGER(8)}. 13964 13965@item @emph{See also}: 13966@ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME} 13967 13968@end table 13969 13970 13971 13972@node TINY 13973@section @code{TINY} --- Smallest positive number of a real kind 13974@fnindex TINY 13975@cindex limits, smallest number 13976@cindex model representation, smallest number 13977 13978@table @asis 13979@item @emph{Description}: 13980@code{TINY(X)} returns the smallest positive (non zero) number 13981in the model of the type of @code{X}. 13982 13983@item @emph{Standard}: 13984Fortran 95 and later 13985 13986@item @emph{Class}: 13987Inquiry function 13988 13989@item @emph{Syntax}: 13990@code{RESULT = TINY(X)} 13991 13992@item @emph{Arguments}: 13993@multitable @columnfractions .15 .70 13994@item @var{X} @tab Shall be of type @code{REAL}. 13995@end multitable 13996 13997@item @emph{Return value}: 13998The return value is of the same type and kind as @var{X} 13999 14000@item @emph{Example}: 14001See @code{HUGE} for an example. 14002@end table 14003 14004 14005 14006@node TRAILZ 14007@section @code{TRAILZ} --- Number of trailing zero bits of an integer 14008@fnindex TRAILZ 14009@cindex zero bits 14010 14011@table @asis 14012@item @emph{Description}: 14013@code{TRAILZ} returns the number of trailing zero bits of an integer. 14014 14015@item @emph{Standard}: 14016Fortran 2008 and later 14017 14018@item @emph{Class}: 14019Elemental function 14020 14021@item @emph{Syntax}: 14022@code{RESULT = TRAILZ(I)} 14023 14024@item @emph{Arguments}: 14025@multitable @columnfractions .15 .70 14026@item @var{I} @tab Shall be of type @code{INTEGER}. 14027@end multitable 14028 14029@item @emph{Return value}: 14030The type of the return value is the default @code{INTEGER}. 14031If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 14032 14033@item @emph{Example}: 14034@smallexample 14035PROGRAM test_trailz 14036 WRITE (*,*) TRAILZ(8) ! prints 3 14037END PROGRAM 14038@end smallexample 14039 14040@item @emph{See also}: 14041@ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT} 14042@end table 14043 14044 14045 14046@node TRANSFER 14047@section @code{TRANSFER} --- Transfer bit patterns 14048@fnindex TRANSFER 14049@cindex bits, move 14050@cindex type cast 14051 14052@table @asis 14053@item @emph{Description}: 14054Interprets the bitwise representation of @var{SOURCE} in memory as if it 14055is the representation of a variable or array of the same type and type 14056parameters as @var{MOLD}. 14057 14058This is approximately equivalent to the C concept of @emph{casting} one 14059type to another. 14060 14061@item @emph{Standard}: 14062Fortran 95 and later 14063 14064@item @emph{Class}: 14065Transformational function 14066 14067@item @emph{Syntax}: 14068@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])} 14069 14070@item @emph{Arguments}: 14071@multitable @columnfractions .15 .70 14072@item @var{SOURCE} @tab Shall be a scalar or an array of any type. 14073@item @var{MOLD} @tab Shall be a scalar or an array of any type. 14074@item @var{SIZE} @tab (Optional) shall be a scalar of type 14075@code{INTEGER}. 14076@end multitable 14077 14078@item @emph{Return value}: 14079The result has the same type as @var{MOLD}, with the bit level 14080representation of @var{SOURCE}. If @var{SIZE} is present, the result is 14081a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent 14082but @var{MOLD} is an array (of any size or shape), the result is a one- 14083dimensional array of the minimum length needed to contain the entirety 14084of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent 14085and @var{MOLD} is a scalar, the result is a scalar. 14086 14087If the bitwise representation of the result is longer than that of 14088@var{SOURCE}, then the leading bits of the result correspond to those of 14089@var{SOURCE} and any trailing bits are filled arbitrarily. 14090 14091When the resulting bit representation does not correspond to a valid 14092representation of a variable of the same type as @var{MOLD}, the results 14093are undefined, and subsequent operations on the result cannot be 14094guaranteed to produce sensible behavior. For example, it is possible to 14095create @code{LOGICAL} variables for which @code{@var{VAR}} and 14096@code{.NOT.@var{VAR}} both appear to be true. 14097 14098@item @emph{Example}: 14099@smallexample 14100PROGRAM test_transfer 14101 integer :: x = 2143289344 14102 print *, transfer(x, 1.0) ! prints "NaN" on i686 14103END PROGRAM 14104@end smallexample 14105@end table 14106 14107 14108 14109@node TRANSPOSE 14110@section @code{TRANSPOSE} --- Transpose an array of rank two 14111@fnindex TRANSPOSE 14112@cindex array, transpose 14113@cindex matrix, transpose 14114@cindex transpose 14115 14116@table @asis 14117@item @emph{Description}: 14118Transpose an array of rank two. Element (i, j) of the result has the value 14119@code{MATRIX(j, i)}, for all i, j. 14120 14121@item @emph{Standard}: 14122Fortran 95 and later 14123 14124@item @emph{Class}: 14125Transformational function 14126 14127@item @emph{Syntax}: 14128@code{RESULT = TRANSPOSE(MATRIX)} 14129 14130@item @emph{Arguments}: 14131@multitable @columnfractions .15 .70 14132@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two. 14133@end multitable 14134 14135@item @emph{Return value}: 14136The result has the same type as @var{MATRIX}, and has shape 14137@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}. 14138@end table 14139 14140 14141 14142@node TRIM 14143@section @code{TRIM} --- Remove trailing blank characters of a string 14144@fnindex TRIM 14145@cindex string, remove trailing whitespace 14146 14147@table @asis 14148@item @emph{Description}: 14149Removes trailing blank characters of a string. 14150 14151@item @emph{Standard}: 14152Fortran 95 and later 14153 14154@item @emph{Class}: 14155Transformational function 14156 14157@item @emph{Syntax}: 14158@code{RESULT = TRIM(STRING)} 14159 14160@item @emph{Arguments}: 14161@multitable @columnfractions .15 .70 14162@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}. 14163@end multitable 14164 14165@item @emph{Return value}: 14166A scalar of type @code{CHARACTER} which length is that of @var{STRING} 14167less the number of trailing blanks. 14168 14169@item @emph{Example}: 14170@smallexample 14171PROGRAM test_trim 14172 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " 14173 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks 14174END PROGRAM 14175@end smallexample 14176 14177@item @emph{See also}: 14178@ref{ADJUSTL}, @ref{ADJUSTR} 14179@end table 14180 14181 14182 14183@node TTYNAM 14184@section @code{TTYNAM} --- Get the name of a terminal device. 14185@fnindex TTYNAM 14186@cindex system, terminal 14187 14188@table @asis 14189@item @emph{Description}: 14190Get the name of a terminal device. For more information, 14191see @code{ttyname(3)}. 14192 14193This intrinsic is provided in both subroutine and function forms; 14194however, only one form can be used in any given program unit. 14195 14196@item @emph{Standard}: 14197GNU extension 14198 14199@item @emph{Class}: 14200Subroutine, function 14201 14202@item @emph{Syntax}: 14203@multitable @columnfractions .80 14204@item @code{CALL TTYNAM(UNIT, NAME)} 14205@item @code{NAME = TTYNAM(UNIT)} 14206@end multitable 14207 14208@item @emph{Arguments}: 14209@multitable @columnfractions .15 .70 14210@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 14211@item @var{NAME} @tab Shall be of type @code{CHARACTER}. 14212@end multitable 14213 14214@item @emph{Example}: 14215@smallexample 14216PROGRAM test_ttynam 14217 INTEGER :: unit 14218 DO unit = 1, 10 14219 IF (isatty(unit=unit)) write(*,*) ttynam(unit) 14220 END DO 14221END PROGRAM 14222@end smallexample 14223 14224@item @emph{See also}: 14225@ref{ISATTY} 14226@end table 14227 14228 14229 14230@node UBOUND 14231@section @code{UBOUND} --- Upper dimension bounds of an array 14232@fnindex UBOUND 14233@cindex array, upper bound 14234 14235@table @asis 14236@item @emph{Description}: 14237Returns the upper bounds of an array, or a single upper bound 14238along the @var{DIM} dimension. 14239@item @emph{Standard}: 14240Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 14241 14242@item @emph{Class}: 14243Inquiry function 14244 14245@item @emph{Syntax}: 14246@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])} 14247 14248@item @emph{Arguments}: 14249@multitable @columnfractions .15 .70 14250@item @var{ARRAY} @tab Shall be an array, of any type. 14251@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14252@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization 14253expression indicating the kind parameter of the result. 14254@end multitable 14255 14256@item @emph{Return value}: 14257The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14258@var{KIND} is absent, the return value is of default integer kind. 14259If @var{DIM} is absent, the result is an array of the upper bounds of 14260@var{ARRAY}. If @var{DIM} is present, the result is a scalar 14261corresponding to the upper bound of the array along that dimension. If 14262@var{ARRAY} is an expression rather than a whole array or array 14263structure component, or if it has a zero extent along the relevant 14264dimension, the upper bound is taken to be the number of elements along 14265the relevant dimension. 14266 14267@item @emph{See also}: 14268@ref{LBOUND}, @ref{LCOBOUND} 14269@end table 14270 14271 14272 14273@node UCOBOUND 14274@section @code{UCOBOUND} --- Upper codimension bounds of an array 14275@fnindex UCOBOUND 14276@cindex coarray, upper bound 14277 14278@table @asis 14279@item @emph{Description}: 14280Returns the upper cobounds of a coarray, or a single upper cobound 14281along the @var{DIM} codimension. 14282@item @emph{Standard}: 14283Fortran 2008 and later 14284 14285@item @emph{Class}: 14286Inquiry function 14287 14288@item @emph{Syntax}: 14289@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])} 14290 14291@item @emph{Arguments}: 14292@multitable @columnfractions .15 .70 14293@item @var{ARRAY} @tab Shall be an coarray, of any type. 14294@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14295@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14296expression indicating the kind parameter of the result. 14297@end multitable 14298 14299@item @emph{Return value}: 14300The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14301@var{KIND} is absent, the return value is of default integer kind. 14302If @var{DIM} is absent, the result is an array of the lower cobounds of 14303@var{COARRAY}. If @var{DIM} is present, the result is a scalar 14304corresponding to the lower cobound of the array along that codimension. 14305 14306@item @emph{See also}: 14307@ref{LCOBOUND}, @ref{LBOUND} 14308@end table 14309 14310 14311 14312@node UMASK 14313@section @code{UMASK} --- Set the file creation mask 14314@fnindex UMASK 14315@cindex file system, file creation mask 14316 14317@table @asis 14318@item @emph{Description}: 14319Sets the file creation mask to @var{MASK}. If called as a function, it 14320returns the old value. If called as a subroutine and argument @var{OLD} 14321if it is supplied, it is set to the old value. See @code{umask(2)}. 14322 14323@item @emph{Standard}: 14324GNU extension 14325 14326@item @emph{Class}: 14327Subroutine, function 14328 14329@item @emph{Syntax}: 14330@multitable @columnfractions .80 14331@item @code{CALL UMASK(MASK [, OLD])} 14332@item @code{OLD = UMASK(MASK)} 14333@end multitable 14334 14335@item @emph{Arguments}: 14336@multitable @columnfractions .15 .70 14337@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}. 14338@item @var{OLD} @tab (Optional) Shall be a scalar of type 14339@code{INTEGER}. 14340@end multitable 14341 14342@end table 14343 14344 14345 14346@node UNLINK 14347@section @code{UNLINK} --- Remove a file from the file system 14348@fnindex UNLINK 14349@cindex file system, remove file 14350 14351@table @asis 14352@item @emph{Description}: 14353Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be 14354used to mark the end of the name in @var{PATH}; otherwise, trailing 14355blanks in the file name are ignored. If the @var{STATUS} argument is 14356supplied, it contains 0 on success or a nonzero error code upon return; 14357see @code{unlink(2)}. 14358 14359This intrinsic is provided in both subroutine and function forms; 14360however, only one form can be used in any given program unit. 14361 14362@item @emph{Standard}: 14363GNU extension 14364 14365@item @emph{Class}: 14366Subroutine, function 14367 14368@item @emph{Syntax}: 14369@multitable @columnfractions .80 14370@item @code{CALL UNLINK(PATH [, STATUS])} 14371@item @code{STATUS = UNLINK(PATH)} 14372@end multitable 14373 14374@item @emph{Arguments}: 14375@multitable @columnfractions .15 .70 14376@item @var{PATH} @tab Shall be of default @code{CHARACTER} type. 14377@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 14378@end multitable 14379 14380@item @emph{See also}: 14381@ref{LINK}, @ref{SYMLNK} 14382@end table 14383 14384 14385 14386@node UNPACK 14387@section @code{UNPACK} --- Unpack an array of rank one into an array 14388@fnindex UNPACK 14389@cindex array, unpacking 14390@cindex array, increase dimension 14391@cindex array, scatter elements 14392 14393@table @asis 14394@item @emph{Description}: 14395Store the elements of @var{VECTOR} in an array of higher rank. 14396 14397@item @emph{Standard}: 14398Fortran 95 and later 14399 14400@item @emph{Class}: 14401Transformational function 14402 14403@item @emph{Syntax}: 14404@code{RESULT = UNPACK(VECTOR, MASK, FIELD)} 14405 14406@item @emph{Arguments}: 14407@multitable @columnfractions .15 .70 14408@item @var{VECTOR} @tab Shall be an array of any type and rank one. It 14409shall have at least as many elements as @var{MASK} has @code{TRUE} values. 14410@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}. 14411@item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have 14412the same shape as @var{MASK}. 14413@end multitable 14414 14415@item @emph{Return value}: 14416The resulting array corresponds to @var{FIELD} with @code{TRUE} elements 14417of @var{MASK} replaced by values from @var{VECTOR} in array element order. 14418 14419@item @emph{Example}: 14420@smallexample 14421PROGRAM test_unpack 14422 integer :: vector(2) = (/1,1/) 14423 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /) 14424 integer :: field(2,2) = 0, unity(2,2) 14425 14426 ! result: unity matrix 14427 unity = unpack(vector, reshape(mask, (/2,2/)), field) 14428END PROGRAM 14429@end smallexample 14430 14431@item @emph{See also}: 14432@ref{PACK}, @ref{SPREAD} 14433@end table 14434 14435 14436 14437@node VERIFY 14438@section @code{VERIFY} --- Scan a string for characters not a given set 14439@fnindex VERIFY 14440@cindex string, find missing set 14441 14442@table @asis 14443@item @emph{Description}: 14444Verifies that all the characters in @var{STRING} belong to the set of 14445characters in @var{SET}. 14446 14447If @var{BACK} is either absent or equals @code{FALSE}, this function 14448returns the position of the leftmost character of @var{STRING} that is 14449not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost 14450position is returned. If all characters of @var{STRING} are found in 14451@var{SET}, the result is zero. 14452 14453@item @emph{Standard}: 14454Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 14455 14456@item @emph{Class}: 14457Elemental function 14458 14459@item @emph{Syntax}: 14460@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])} 14461 14462@item @emph{Arguments}: 14463@multitable @columnfractions .15 .70 14464@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 14465@item @var{SET} @tab Shall be of type @code{CHARACTER}. 14466@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 14467@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14468expression indicating the kind parameter of the result. 14469@end multitable 14470 14471@item @emph{Return value}: 14472The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14473@var{KIND} is absent, the return value is of default integer kind. 14474 14475@item @emph{Example}: 14476@smallexample 14477PROGRAM test_verify 14478 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F' 14479 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R' 14480 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F' 14481 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N' 14482 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none 14483END PROGRAM 14484@end smallexample 14485 14486@item @emph{See also}: 14487@ref{SCAN}, @ref{INDEX intrinsic} 14488@end table 14489 14490 14491 14492@node XOR 14493@section @code{XOR} --- Bitwise logical exclusive OR 14494@fnindex XOR 14495@cindex bitwise logical exclusive or 14496@cindex logical exclusive or, bitwise 14497 14498@table @asis 14499@item @emph{Description}: 14500Bitwise logical exclusive or. 14501 14502This intrinsic routine is provided for backwards compatibility with 14503GNU Fortran 77. For integer arguments, programmers should consider 14504the use of the @ref{IEOR} intrinsic and for logical arguments the 14505@code{.NEQV.} operator, which are both defined by the Fortran standard. 14506 14507@item @emph{Standard}: 14508GNU extension 14509 14510@item @emph{Class}: 14511Function 14512 14513@item @emph{Syntax}: 14514@code{RESULT = XOR(I, J)} 14515 14516@item @emph{Arguments}: 14517@multitable @columnfractions .15 .70 14518@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 14519type or a scalar @code{LOGICAL} type. 14520@item @var{J} @tab The type shall be the same as the type of @var{I}. 14521@end multitable 14522 14523@item @emph{Return value}: 14524The return type is either a scalar @code{INTEGER} or a scalar 14525@code{LOGICAL}. If the kind type parameters differ, then the 14526smaller kind type is implicitly converted to larger kind, and the 14527return has the larger kind. 14528 14529@item @emph{Example}: 14530@smallexample 14531PROGRAM test_xor 14532 LOGICAL :: T = .TRUE., F = .FALSE. 14533 INTEGER :: a, b 14534 DATA a / Z'F' /, b / Z'3' / 14535 14536 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F) 14537 WRITE (*,*) XOR(a, b) 14538END PROGRAM 14539@end smallexample 14540 14541@item @emph{See also}: 14542Fortran 95 elemental function: @ref{IEOR} 14543@end table 14544 14545 14546 14547@node Intrinsic Modules 14548@chapter Intrinsic Modules 14549@cindex intrinsic Modules 14550 14551@menu 14552* ISO_FORTRAN_ENV:: 14553* ISO_C_BINDING:: 14554* IEEE modules:: 14555* OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: 14556* OpenACC Module OPENACC:: 14557@end menu 14558 14559@node ISO_FORTRAN_ENV 14560@section @code{ISO_FORTRAN_ENV} 14561@table @asis 14562@item @emph{Standard}: 14563Fortran 2003 and later, except when otherwise noted 14564@end table 14565 14566The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer 14567named constants: 14568 14569@table @asis 14570@item @code{ATOMIC_INT_KIND}: 14571Default-kind integer constant to be used as kind parameter when defining 14572integer variables used in atomic operations. (Fortran 2008 or later.) 14573 14574@item @code{ATOMIC_LOGICAL_KIND}: 14575Default-kind integer constant to be used as kind parameter when defining 14576logical variables used in atomic operations. (Fortran 2008 or later.) 14577 14578@item @code{CHARACTER_KINDS}: 14579Default-kind integer constant array of rank one containing the supported kind 14580parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) 14581 14582@item @code{CHARACTER_STORAGE_SIZE}: 14583Size in bits of the character storage unit. 14584 14585@item @code{ERROR_UNIT}: 14586Identifies the preconnected unit used for error reporting. 14587 14588@item @code{FILE_STORAGE_SIZE}: 14589Size in bits of the file-storage unit. 14590 14591@item @code{INPUT_UNIT}: 14592Identifies the preconnected unit identified by the asterisk 14593(@code{*}) in @code{READ} statement. 14594 14595@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}: 14596Kind type parameters to specify an INTEGER type with a storage 14597size of 16, 32, and 64 bits. It is negative if a target platform 14598does not support the particular kind. (Fortran 2008 or later.) 14599 14600@item @code{INTEGER_KINDS}: 14601Default-kind integer constant array of rank one containing the supported kind 14602parameters of the @code{INTEGER} type. (Fortran 2008 or later.) 14603 14604@item @code{IOSTAT_END}: 14605The value assigned to the variable passed to the @code{IOSTAT=} specifier of 14606an input/output statement if an end-of-file condition occurred. 14607 14608@item @code{IOSTAT_EOR}: 14609The value assigned to the variable passed to the @code{IOSTAT=} specifier of 14610an input/output statement if an end-of-record condition occurred. 14611 14612@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}: 14613Scalar default-integer constant, used by @code{INQUIRE} for the 14614@code{IOSTAT=} specifier to denote an that a unit number identifies an 14615internal unit. (Fortran 2008 or later.) 14616 14617@item @code{NUMERIC_STORAGE_SIZE}: 14618The size in bits of the numeric storage unit. 14619 14620@item @code{LOGICAL_KINDS}: 14621Default-kind integer constant array of rank one containing the supported kind 14622parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) 14623 14624@item @code{OUTPUT_UNIT}: 14625Identifies the preconnected unit identified by the asterisk 14626(@code{*}) in @code{WRITE} statement. 14627 14628@item @code{REAL32}, @code{REAL64}, @code{REAL128}: 14629Kind type parameters to specify a REAL type with a storage 14630size of 32, 64, and 128 bits. It is negative if a target platform 14631does not support the particular kind. (Fortran 2008 or later.) 14632 14633@item @code{REAL_KINDS}: 14634Default-kind integer constant array of rank one containing the supported kind 14635parameters of the @code{REAL} type. (Fortran 2008 or later.) 14636 14637@item @code{STAT_LOCKED}: 14638Scalar default-integer constant used as STAT= return value by @code{LOCK} to 14639denote that the lock variable is locked by the executing image. (Fortran 2008 14640or later.) 14641 14642@item @code{STAT_LOCKED_OTHER_IMAGE}: 14643Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 14644denote that the lock variable is locked by another image. (Fortran 2008 or 14645later.) 14646 14647@item @code{STAT_STOPPED_IMAGE}: 14648Positive, scalar default-integer constant used as STAT= return value if the 14649argument in the statement requires synchronisation with an image, which has 14650initiated the termination of the execution. (Fortran 2008 or later.) 14651 14652@item @code{STAT_FAILED_IMAGE}: 14653Positive, scalar default-integer constant used as STAT= return value if the 14654argument in the statement requires communication with an image, which has 14655is in the failed state. (TS 18508 or later.) 14656 14657@item @code{STAT_UNLOCKED}: 14658Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 14659denote that the lock variable is unlocked. (Fortran 2008 or later.) 14660@end table 14661 14662The module provides the following derived type: 14663 14664@table @asis 14665@item @code{LOCK_TYPE}: 14666Derived type with private components to be use with the @code{LOCK} and 14667@code{UNLOCK} statement. A variable of its type has to be always declared 14668as coarray and may not appear in a variable-definition context. 14669(Fortran 2008 or later.) 14670@end table 14671 14672The module also provides the following intrinsic procedures: 14673@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}. 14674 14675 14676 14677@node ISO_C_BINDING 14678@section @code{ISO_C_BINDING} 14679@table @asis 14680@item @emph{Standard}: 14681Fortran 2003 and later, GNU extensions 14682@end table 14683 14684The following intrinsic procedures are provided by the module; their 14685definition can be found in the section Intrinsic Procedures of this 14686manual. 14687 14688@table @asis 14689@item @code{C_ASSOCIATED} 14690@item @code{C_F_POINTER} 14691@item @code{C_F_PROCPOINTER} 14692@item @code{C_FUNLOC} 14693@item @code{C_LOC} 14694@item @code{C_SIZEOF} 14695@end table 14696@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF, 14697@c don't really know why. 14698 14699The @code{ISO_C_BINDING} module provides the following named constants of 14700type default integer, which can be used as KIND type parameters. 14701 14702In addition to the integer named constants required by the Fortran 2003 14703standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an 14704extension named constants for the 128-bit integer types supported by the 14705C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}. 14706Furthermore, if @code{__float128} is supported in C, the named constants 14707@code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined. 14708 14709@multitable @columnfractions .15 .35 .35 .35 14710@item Fortran Type @tab Named constant @tab C type @tab Extension 14711@item @code{INTEGER}@tab @code{C_INT} @tab @code{int} 14712@item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int} 14713@item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int} 14714@item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int} 14715@item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char} 14716@item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t} 14717@item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t} 14718@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t} 14719@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t} 14720@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t} 14721@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext. 14722@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t} 14723@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t} 14724@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t} 14725@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t} 14726@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext. 14727@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t} 14728@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t} 14729@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t} 14730@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t} 14731@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext. 14732@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t} 14733@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t} 14734@item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113 14735@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float} 14736@item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double} 14737@item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double} 14738@item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext. 14739@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex} 14740@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex} 14741@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex} 14742@item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext. 14743@item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool} 14744@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char} 14745@end multitable 14746 14747Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)} 14748are defined. 14749 14750@multitable @columnfractions .20 .45 .15 14751@item Name @tab C definition @tab Value 14752@item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'} 14753@item @code{C_ALERT} @tab alert @tab @code{'\a'} 14754@item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'} 14755@item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'} 14756@item @code{C_NEW_LINE} @tab new line @tab @code{'\n'} 14757@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'} 14758@item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'} 14759@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'} 14760@end multitable 14761 14762Moreover, the following two named constants are defined: 14763 14764@multitable @columnfractions .20 .80 14765@item Name @tab Type 14766@item @code{C_NULL_PTR} @tab @code{C_PTR} 14767@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR} 14768@end multitable 14769 14770Both are equivalent to the value @code{NULL} in C. 14771 14772 14773 14774@node IEEE modules 14775@section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 14776@table @asis 14777@item @emph{Standard}: 14778Fortran 2003 and later 14779@end table 14780 14781The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 14782intrinsic modules provide support for exceptions and IEEE arithmetic, as 14783defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard 14784(@emph{Binary floating-point arithmetic for microprocessor systems}). These 14785modules are only provided on the following supported platforms: 14786 14787@itemize @bullet 14788@item i386 and x86_64 processors 14789@item platforms which use the GNU C Library (glibc) 14790@item platforms with support for SysV/386 routines for floating point 14791interface (including Solaris and BSDs) 14792@item platforms with the AIX OS 14793@end itemize 14794 14795For full compliance with the Fortran standards, code using the 14796@code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled 14797with the following options: @code{-fno-unsafe-math-optimizations 14798-frounding-math -fsignaling-nans}. 14799 14800 14801 14802@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS 14803@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS} 14804@table @asis 14805@item @emph{Standard}: 14806OpenMP Application Program Interface v4.5 14807@end table 14808 14809 14810The OpenMP Fortran runtime library routines are provided both in 14811a form of two Fortran 90 modules, named @code{OMP_LIB} and 14812@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named 14813@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found 14814in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi 14815Processing Runtime Library} manual, 14816the named constants defined in the modules are listed 14817below. 14818 14819For details refer to the actual 14820@uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf, 14821OpenMP Application Program Interface v4.5}. 14822 14823@code{OMP_LIB_KINDS} provides the following scalar default-integer 14824named constants: 14825 14826@table @asis 14827@item @code{omp_lock_kind} 14828@item @code{omp_lock_hint_kind} 14829@item @code{omp_nest_lock_kind} 14830@item @code{omp_proc_bind_kind} 14831@item @code{omp_sched_kind} 14832@end table 14833 14834@code{OMP_LIB} provides the scalar default-integer 14835named constant @code{openmp_version} with a value of the form 14836@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 14837of the OpenMP version; for OpenMP v4.5 the value is @code{201511}. 14838 14839The following scalar integer named constants of the 14840kind @code{omp_sched_kind}: 14841 14842@table @asis 14843@item @code{omp_sched_static} 14844@item @code{omp_sched_dynamic} 14845@item @code{omp_sched_guided} 14846@item @code{omp_sched_auto} 14847@end table 14848 14849And the following scalar integer named constants of the 14850kind @code{omp_proc_bind_kind}: 14851 14852@table @asis 14853@item @code{omp_proc_bind_false} 14854@item @code{omp_proc_bind_true} 14855@item @code{omp_proc_bind_master} 14856@item @code{omp_proc_bind_close} 14857@item @code{omp_proc_bind_spread} 14858@end table 14859 14860The following scalar integer named constants are of the 14861kind @code{omp_lock_hint_kind}: 14862 14863@table @asis 14864@item @code{omp_lock_hint_none} 14865@item @code{omp_lock_hint_uncontended} 14866@item @code{omp_lock_hint_contended} 14867@item @code{omp_lock_hint_nonspeculative} 14868@item @code{omp_lock_hint_speculative} 14869@end table 14870 14871 14872@node OpenACC Module OPENACC 14873@section OpenACC Module @code{OPENACC} 14874@table @asis 14875@item @emph{Standard}: 14876OpenACC Application Programming Interface v2.0 14877@end table 14878 14879 14880The OpenACC Fortran runtime library routines are provided both in a 14881form of a Fortran 90 module, named @code{OPENACC}, and in form of a 14882Fortran @code{include} file named @file{openacc_lib.h}. The 14883procedures provided by @code{OPENACC} can be found in the 14884@ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing 14885Runtime Library} manual, the named constants defined in the modules 14886are listed below. 14887 14888For details refer to the actual 14889@uref{http://www.openacc.org/, 14890OpenACC Application Programming Interface v2.0}. 14891 14892@code{OPENACC} provides the scalar default-integer 14893named constant @code{openacc_version} with a value of the form 14894@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 14895of the OpenACC version; for OpenACC v2.0 the value is @code{201306}. 14896