1@ignore 2Copyright (C) 2005-2021 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{FINDLOC}: FINDLOC, Search an array for a value 152* @code{FLOOR}: FLOOR, Integer floor function 153* @code{FLUSH}: FLUSH, Flush I/O unit(s) 154* @code{FNUM}: FNUM, File number function 155* @code{FPUT}: FPUT, Write a single character in stream mode to stdout 156* @code{FPUTC}: FPUTC, Write a single character in stream mode 157* @code{FRACTION}: FRACTION, Fractional part of the model representation 158* @code{FREE}: FREE, Memory de-allocation subroutine 159* @code{FSEEK}: FSEEK, Low level file positioning subroutine 160* @code{FSTAT}: FSTAT, Get file status 161* @code{FTELL}: FTELL, Current stream position 162* @code{GAMMA}: GAMMA, Gamma function 163* @code{GERROR}: GERROR, Get last system error message 164* @code{GETARG}: GETARG, Get command line arguments 165* @code{GET_COMMAND}: GET_COMMAND, Get the entire command line 166* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments 167* @code{GETCWD}: GETCWD, Get current working directory 168* @code{GETENV}: GETENV, Get an environmental variable 169* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable 170* @code{GETGID}: GETGID, Group ID function 171* @code{GETLOG}: GETLOG, Get login name 172* @code{GETPID}: GETPID, Process ID function 173* @code{GETUID}: GETUID, User ID function 174* @code{GMTIME}: GMTIME, Convert time to GMT info 175* @code{HOSTNM}: HOSTNM, Get system host name 176* @code{HUGE}: HUGE, Largest number of a kind 177* @code{HYPOT}: HYPOT, Euclidean distance function 178* @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence 179* @code{IALL}: IALL, Bitwise AND of array elements 180* @code{IAND}: IAND, Bitwise logical and 181* @code{IANY}: IANY, Bitwise OR of array elements 182* @code{IARGC}: IARGC, Get the number of command line arguments 183* @code{IBCLR}: IBCLR, Clear bit 184* @code{IBITS}: IBITS, Bit extraction 185* @code{IBSET}: IBSET, Set bit 186* @code{ICHAR}: ICHAR, Character-to-integer conversion function 187* @code{IDATE}: IDATE, Current local time (day/month/year) 188* @code{IEOR}: IEOR, Bitwise logical exclusive or 189* @code{IERRNO}: IERRNO, Function to get the last system error number 190* @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion 191* @code{INDEX}: INDEX intrinsic, Position of a substring within a string 192* @code{INT}: INT, Convert to integer type 193* @code{INT2}: INT2, Convert to 16-bit integer type 194* @code{INT8}: INT8, Convert to 64-bit integer type 195* @code{IOR}: IOR, Bitwise logical or 196* @code{IPARITY}: IPARITY, Bitwise XOR of array elements 197* @code{IRAND}: IRAND, Integer pseudo-random number 198* @code{IS_CONTIGUOUS}: IS_CONTIGUOUS, Test whether an array is contiguous 199* @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value 200* @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value 201* @code{ISATTY}: ISATTY, Whether a unit is a terminal device 202* @code{ISHFT}: ISHFT, Shift bits 203* @code{ISHFTC}: ISHFTC, Shift bits circularly 204* @code{ISNAN}: ISNAN, Tests for a NaN 205* @code{ITIME}: ITIME, Current local time (hour/minutes/seconds) 206* @code{KILL}: KILL, Send a signal to a process 207* @code{KIND}: KIND, Kind of an entity 208* @code{LBOUND}: LBOUND, Lower dimension bounds of an array 209* @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array 210* @code{LEADZ}: LEADZ, Number of leading zero bits of an integer 211* @code{LEN}: LEN, Length of a character entity 212* @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters 213* @code{LGE}: LGE, Lexical greater than or equal 214* @code{LGT}: LGT, Lexical greater than 215* @code{LINK}: LINK, Create a hard link 216* @code{LLE}: LLE, Lexical less than or equal 217* @code{LLT}: LLT, Lexical less than 218* @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string 219* @code{LOC}: LOC, Returns the address of a variable 220* @code{LOG}: LOG, Logarithm function 221* @code{LOG10}: LOG10, Base 10 logarithm function 222* @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function 223* @code{LOGICAL}: LOGICAL, Convert to logical type 224* @code{LONG}: LONG, Convert to integer type 225* @code{LSHIFT}: LSHIFT, Left shift bits 226* @code{LSTAT}: LSTAT, Get file status 227* @code{LTIME}: LTIME, Convert time to local time info 228* @code{MALLOC}: MALLOC, Dynamic memory allocation function 229* @code{MASKL}: MASKL, Left justified mask 230* @code{MASKR}: MASKR, Right justified mask 231* @code{MATMUL}: MATMUL, matrix multiplication 232* @code{MAX}: MAX, Maximum value of an argument list 233* @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind 234* @code{MAXLOC}: MAXLOC, Location of the maximum value within an array 235* @code{MAXVAL}: MAXVAL, Maximum value of an array 236* @code{MCLOCK}: MCLOCK, Time function 237* @code{MCLOCK8}: MCLOCK8, Time function (64-bit) 238* @code{MERGE}: MERGE, Merge arrays 239* @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask 240* @code{MIN}: MIN, Minimum value of an argument list 241* @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind 242* @code{MINLOC}: MINLOC, Location of the minimum value within an array 243* @code{MINVAL}: MINVAL, Minimum value of an array 244* @code{MOD}: MOD, Remainder function 245* @code{MODULO}: MODULO, Modulo function 246* @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another 247* @code{MVBITS}: MVBITS, Move bits from one integer to another 248* @code{NEAREST}: NEAREST, Nearest representable number 249* @code{NEW_LINE}: NEW_LINE, New line character 250* @code{NINT}: NINT, Nearest whole number 251* @code{NORM2}: NORM2, Euclidean vector norm 252* @code{NOT}: NOT, Logical negation 253* @code{NULL}: NULL, Function that returns an disassociated pointer 254* @code{NUM_IMAGES}: NUM_IMAGES, Number of images 255* @code{OR}: OR, Bitwise logical OR 256* @code{PACK}: PACK, Pack an array into an array of rank one 257* @code{PARITY}: PARITY, Reduction with exclusive OR 258* @code{PERROR}: PERROR, Print system error message 259* @code{POPCNT}: POPCNT, Number of bits set 260* @code{POPPAR}: POPPAR, Parity of the number of bits set 261* @code{PRECISION}: PRECISION, Decimal precision of a real kind 262* @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified 263* @code{PRODUCT}: PRODUCT, Product of array elements 264* @code{RADIX}: RADIX, Base of a data model 265* @code{RAN}: RAN, Real pseudo-random number 266* @code{RAND}: RAND, Real pseudo-random number 267* @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator 268* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number 269* @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence 270* @code{RANGE}: RANGE, Decimal exponent range 271* @code{RANK} : RANK, Rank of a data object 272* @code{REAL}: REAL, Convert to real type 273* @code{RENAME}: RENAME, Rename a file 274* @code{REPEAT}: REPEAT, Repeated string concatenation 275* @code{RESHAPE}: RESHAPE, Function to reshape an array 276* @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing 277* @code{RSHIFT}: RSHIFT, Right shift bits 278* @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality 279* @code{SCALE}: SCALE, Scale a real value 280* @code{SCAN}: SCAN, Scan a string for the presence of a set of characters 281* @code{SECNDS}: SECNDS, Time function 282* @code{SECOND}: SECOND, CPU time function 283* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind 284* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind 285* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind 286* @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model 287* @code{SHAPE}: SHAPE, Determine the shape of an array 288* @code{SHIFTA}: SHIFTA, Right shift with fill 289* @code{SHIFTL}: SHIFTL, Left shift 290* @code{SHIFTR}: SHIFTR, Right shift 291* @code{SIGN}: SIGN, Sign copying function 292* @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function) 293* @code{SIN}: SIN, Sine function 294* @code{SIND}: SIND, Sine function, degrees 295* @code{SINH}: SINH, Hyperbolic sine function 296* @code{SIZE}: SIZE, Function to determine the size of an array 297* @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression 298* @code{SLEEP}: SLEEP, Sleep for the specified number of seconds 299* @code{SPACING}: SPACING, Smallest distance between two numbers of a given type 300* @code{SPREAD}: SPREAD, Add a dimension to an array 301* @code{SQRT}: SQRT, Square-root function 302* @code{SRAND}: SRAND, Reinitialize the random number generator 303* @code{STAT}: STAT, Get file status 304* @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits 305* @code{SUM}: SUM, Sum of array elements 306* @code{SYMLNK}: SYMLNK, Create a symbolic link 307* @code{SYSTEM}: SYSTEM, Execute a shell command 308* @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function 309* @code{TAN}: TAN, Tangent function 310* @code{TAND}: TAND, Tangent function, degrees 311* @code{TANH}: TANH, Hyperbolic tangent function 312* @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image 313* @code{TIME}: TIME, Time function 314* @code{TIME8}: TIME8, Time function (64-bit) 315* @code{TINY}: TINY, Smallest positive number of a real kind 316* @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer 317* @code{TRANSFER}: TRANSFER, Transfer bit patterns 318* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two 319* @code{TRIM}: TRIM, Remove trailing blank characters of a string 320* @code{TTYNAM}: TTYNAM, Get the name of a terminal device. 321* @code{UBOUND}: UBOUND, Upper dimension bounds of an array 322* @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array 323* @code{UMASK}: UMASK, Set the file creation mask 324* @code{UNLINK}: UNLINK, Remove a file from the file system 325* @code{UNPACK}: UNPACK, Unpack an array of rank one into an array 326* @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters 327* @code{XOR}: XOR, Bitwise logical exclusive or 328@end menu 329 330@node Introduction to Intrinsics 331@section Introduction to intrinsic procedures 332 333The intrinsic procedures provided by GNU Fortran include all of the 334intrinsic procedures required by the Fortran 95 standard, a set of 335intrinsic procedures for backwards compatibility with G77, and a 336selection of intrinsic procedures from the Fortran 2003 and Fortran 2008 337standards. Any conflict between a description here and a description in 338either the Fortran 95 standard, the Fortran 2003 standard or the Fortran 3392008 standard is unintentional, and the standard(s) should be considered 340authoritative. 341 342The enumeration of the @code{KIND} type parameter is processor defined in 343the Fortran 95 standard. GNU Fortran defines the default integer type and 344default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)}, 345respectively. The standard mandates that both data types shall have 346another kind, which have more precision. On typical target architectures 347supported by @command{gfortran}, this kind type parameter is @code{KIND=8}. 348Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent. 349In the description of generic intrinsic procedures, the kind type parameter 350will be specified by @code{KIND=*}, and in the description of specific 351names for an intrinsic procedure the kind type parameter will be explicitly 352given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for 353brevity the optional @code{KIND=} syntax will be omitted. 354 355Many of the intrinsic procedures take one or more optional arguments. 356This document follows the convention used in the Fortran 95 standard, 357and denotes such arguments by square brackets. 358 359GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options, 360which can be used to restrict the set of intrinsic procedures to a 361given standard. By default, @command{gfortran} sets the @option{-std=gnu} 362option, and so all intrinsic procedures described here are accepted. There 363is one caveat. For a select group of intrinsic procedures, @command{g77} 364implemented both a function and a subroutine. Both classes 365have been implemented in @command{gfortran} for backwards compatibility 366with @command{g77}. It is noted here that these functions and subroutines 367cannot be intermixed in a given subprogram. In the descriptions that follow, 368the applicable standard for each intrinsic procedure is noted. 369 370 371 372@node ABORT 373@section @code{ABORT} --- Abort the program 374@fnindex ABORT 375@cindex program termination, with core dump 376@cindex terminate program, with core dump 377@cindex core, dump 378 379@table @asis 380@item @emph{Description}: 381@code{ABORT} causes immediate termination of the program. On operating 382systems that support a core dump, @code{ABORT} will produce a core dump. 383It will also print a backtrace, unless @code{-fno-backtrace} is given. 384 385@item @emph{Standard}: 386GNU extension 387 388@item @emph{Class}: 389Subroutine 390 391@item @emph{Syntax}: 392@code{CALL ABORT} 393 394@item @emph{Return value}: 395Does not return. 396 397@item @emph{Example}: 398@smallexample 399program test_abort 400 integer :: i = 1, j = 2 401 if (i /= j) call abort 402end program test_abort 403@end smallexample 404 405@item @emph{See also}: 406@ref{EXIT}, @gol 407@ref{KILL}, @gol 408@ref{BACKTRACE} 409@end table 410 411 412 413@node ABS 414@section @code{ABS} --- Absolute value 415@fnindex ABS 416@fnindex CABS 417@fnindex DABS 418@fnindex IABS 419@fnindex ZABS 420@fnindex CDABS 421@fnindex BABS 422@fnindex IIABS 423@fnindex JIABS 424@fnindex KIABS 425@cindex absolute value 426 427@table @asis 428@item @emph{Description}: 429@code{ABS(A)} computes the absolute value of @code{A}. 430 431@item @emph{Standard}: 432Fortran 77 and later, has overloads that are GNU extensions 433 434@item @emph{Class}: 435Elemental function 436 437@item @emph{Syntax}: 438@code{RESULT = ABS(A)} 439 440@item @emph{Arguments}: 441@multitable @columnfractions .15 .70 442@item @var{A} @tab The type of the argument shall be an @code{INTEGER}, 443@code{REAL}, or @code{COMPLEX}. 444@end multitable 445 446@item @emph{Return value}: 447The return value is of the same type and 448kind as the argument except the return value is @code{REAL} for a 449@code{COMPLEX} argument. 450 451@item @emph{Example}: 452@smallexample 453program test_abs 454 integer :: i = -1 455 real :: x = -1.e0 456 complex :: z = (-1.e0,0.e0) 457 i = abs(i) 458 x = abs(x) 459 x = abs(z) 460end program test_abs 461@end smallexample 462 463@item @emph{Specific names}: 464@multitable @columnfractions .20 .20 .20 .25 465@item Name @tab Argument @tab Return type @tab Standard 466@item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 467@item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 468@item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 469@item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later 470@item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 471@item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 472@item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 473@item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 474@item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension 475@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension 476@end multitable 477@end table 478 479 480 481@node ACCESS 482@section @code{ACCESS} --- Checks file access modes 483@fnindex ACCESS 484@cindex file system, access mode 485 486@table @asis 487@item @emph{Description}: 488@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 489exists, is readable, writable or executable. Except for the 490executable check, @code{ACCESS} can be replaced by 491Fortran 95's @code{INQUIRE}. 492 493@item @emph{Standard}: 494GNU extension 495 496@item @emph{Class}: 497Inquiry function 498 499@item @emph{Syntax}: 500@code{RESULT = ACCESS(NAME, MODE)} 501 502@item @emph{Arguments}: 503@multitable @columnfractions .15 .70 504@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 505file name. Tailing blank are ignored unless the character @code{achar(0)} 506is present, then all characters up to and excluding @code{achar(0)} are 507used as file name. 508@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the 509file access mode, may be any concatenation of @code{"r"} (readable), 510@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check 511for existence. 512@end multitable 513 514@item @emph{Return value}: 515Returns a scalar @code{INTEGER}, which is @code{0} if the file is 516accessible in the given mode; otherwise or if an invalid argument 517has been given for @code{MODE} the value @code{1} is returned. 518 519@item @emph{Example}: 520@smallexample 521program access_test 522 implicit none 523 character(len=*), parameter :: file = 'test.dat' 524 character(len=*), parameter :: file2 = 'test.dat '//achar(0) 525 if(access(file,' ') == 0) print *, trim(file),' is exists' 526 if(access(file,'r') == 0) print *, trim(file),' is readable' 527 if(access(file,'w') == 0) print *, trim(file),' is writable' 528 if(access(file,'x') == 0) print *, trim(file),' is executable' 529 if(access(file2,'rwx') == 0) & 530 print *, trim(file2),' is readable, writable and executable' 531end program access_test 532@end smallexample 533@end table 534 535 536 537@node ACHAR 538@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 539@fnindex ACHAR 540@cindex @acronym{ASCII} collating sequence 541@cindex collating sequence, @acronym{ASCII} 542 543@table @asis 544@item @emph{Description}: 545@code{ACHAR(I)} returns the character located at position @code{I} 546in the @acronym{ASCII} collating sequence. 547 548@item @emph{Standard}: 549Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 550 551@item @emph{Class}: 552Elemental function 553 554@item @emph{Syntax}: 555@code{RESULT = ACHAR(I [, KIND])} 556 557@item @emph{Arguments}: 558@multitable @columnfractions .15 .70 559@item @var{I} @tab The type shall be @code{INTEGER}. 560@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 561expression indicating the kind parameter of the result. 562@end multitable 563 564@item @emph{Return value}: 565The return value is of type @code{CHARACTER} with a length of one. 566If the @var{KIND} argument is present, the return value is of the 567specified kind and of the default kind otherwise. 568 569@item @emph{Example}: 570@smallexample 571program test_achar 572 character c 573 c = achar(32) 574end program test_achar 575@end smallexample 576 577@item @emph{Note}: 578See @ref{ICHAR} for a discussion of converting between numerical values 579and formatted string representations. 580 581@item @emph{See also}: 582@ref{CHAR}, @gol 583@ref{IACHAR}, @gol 584@ref{ICHAR} 585@end table 586 587 588 589@node ACOS 590@section @code{ACOS} --- Arccosine function 591@fnindex ACOS 592@fnindex DACOS 593@cindex trigonometric function, cosine, inverse 594@cindex cosine, inverse 595 596@table @asis 597@item @emph{Description}: 598@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}). 599 600@item @emph{Standard}: 601Fortran 77 and later, for a complex argument Fortran 2008 or later 602 603@item @emph{Class}: 604Elemental function 605 606@item @emph{Syntax}: 607@code{RESULT = ACOS(X)} 608 609@item @emph{Arguments}: 610@multitable @columnfractions .15 .70 611@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 612less than or equal to one - or the type shall be @code{COMPLEX}. 613@end multitable 614 615@item @emph{Return value}: 616The return value is of the same type and kind as @var{X}. 617The real part of the result is in radians and lies in the range 618@math{0 \leq \Re \acos(x) \leq \pi}. 619 620@item @emph{Example}: 621@smallexample 622program test_acos 623 real(8) :: x = 0.866_8 624 x = acos(x) 625end program test_acos 626@end smallexample 627 628@item @emph{Specific names}: 629@multitable @columnfractions .20 .20 .20 .25 630@item Name @tab Argument @tab Return type @tab Standard 631@item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 632@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 633@end multitable 634 635@item @emph{See also}: 636Inverse function: @gol 637@ref{COS} @gol 638Degrees function: @gol 639@ref{ACOSD} 640@end table 641 642 643 644@node ACOSD 645@section @code{ACOSD} --- Arccosine function, degrees 646@fnindex ACOSD 647@fnindex DACOSD 648@cindex trigonometric function, cosine, inverse, degrees 649@cindex cosine, inverse, degrees 650 651@table @asis 652@item @emph{Description}: 653@code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of 654@code{COSD(X)}). 655 656This function is for compatibility only and should be avoided in favor of 657standard constructs wherever possible. 658 659@item @emph{Standard}: 660GNU extension, enabled with @option{-fdec-math} 661 662@item @emph{Class}: 663Elemental function 664 665@item @emph{Syntax}: 666@code{RESULT = ACOSD(X)} 667 668@item @emph{Arguments}: 669@multitable @columnfractions .15 .70 670@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 671less than or equal to one - or the type shall be @code{COMPLEX}. 672@end multitable 673 674@item @emph{Return value}: 675The return value is of the same type and kind as @var{X}. 676The real part of the result is in degrees and lies in the range 677@math{0 \leq \Re \acos(x) \leq 180}. 678 679@item @emph{Example}: 680@smallexample 681program test_acosd 682 real(8) :: x = 0.866_8 683 x = acosd(x) 684end program test_acosd 685@end smallexample 686 687@item @emph{Specific names}: 688@multitable @columnfractions .20 .20 .20 .25 689@item Name @tab Argument @tab Return type @tab Standard 690@item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 691@item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 692@end multitable 693 694@item @emph{See also}: 695Inverse function: @gol 696@ref{COSD} @gol 697Radians function: @gol 698@ref{ACOS} @gol 699@end table 700 701 702 703@node ACOSH 704@section @code{ACOSH} --- Inverse hyperbolic cosine function 705@fnindex ACOSH 706@fnindex DACOSH 707@cindex area hyperbolic cosine 708@cindex inverse hyperbolic cosine 709@cindex hyperbolic function, cosine, inverse 710@cindex cosine, hyperbolic, inverse 711 712@table @asis 713@item @emph{Description}: 714@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}. 715 716@item @emph{Standard}: 717Fortran 2008 and later 718 719@item @emph{Class}: 720Elemental function 721 722@item @emph{Syntax}: 723@code{RESULT = ACOSH(X)} 724 725@item @emph{Arguments}: 726@multitable @columnfractions .15 .70 727@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 728@end multitable 729 730@item @emph{Return value}: 731The return value has the same type and kind as @var{X}. If @var{X} is 732complex, the imaginary part of the result is in radians and lies between 733@math{ 0 \leq \Im \acosh(x) \leq \pi}. 734 735@item @emph{Example}: 736@smallexample 737PROGRAM test_acosh 738 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) 739 WRITE (*,*) ACOSH(x) 740END PROGRAM 741@end smallexample 742 743@item @emph{Specific names}: 744@multitable @columnfractions .20 .20 .20 .25 745@item Name @tab Argument @tab Return type @tab Standard 746@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 747@end multitable 748 749@item @emph{See also}: 750Inverse function: @gol 751@ref{COSH} 752@end table 753 754 755 756@node ADJUSTL 757@section @code{ADJUSTL} --- Left adjust a string 758@fnindex ADJUSTL 759@cindex string, adjust left 760@cindex adjust string 761 762@table @asis 763@item @emph{Description}: 764@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces. 765Spaces are inserted at the end of the string as needed. 766 767@item @emph{Standard}: 768Fortran 90 and later 769 770@item @emph{Class}: 771Elemental function 772 773@item @emph{Syntax}: 774@code{RESULT = ADJUSTL(STRING)} 775 776@item @emph{Arguments}: 777@multitable @columnfractions .15 .70 778@item @var{STRING} @tab The type shall be @code{CHARACTER}. 779@end multitable 780 781@item @emph{Return value}: 782The return value is of type @code{CHARACTER} and of the same kind as 783@var{STRING} where leading spaces are removed and the same number of 784spaces are inserted on the end of @var{STRING}. 785 786@item @emph{Example}: 787@smallexample 788program test_adjustl 789 character(len=20) :: str = ' gfortran' 790 str = adjustl(str) 791 print *, str 792end program test_adjustl 793@end smallexample 794 795@item @emph{See also}: 796@ref{ADJUSTR}, @gol 797@ref{TRIM} 798@end table 799 800 801 802@node ADJUSTR 803@section @code{ADJUSTR} --- Right adjust a string 804@fnindex ADJUSTR 805@cindex string, adjust right 806@cindex adjust string 807 808@table @asis 809@item @emph{Description}: 810@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces. 811Spaces are inserted at the start of the string as needed. 812 813@item @emph{Standard}: 814Fortran 90 and later 815 816@item @emph{Class}: 817Elemental function 818 819@item @emph{Syntax}: 820@code{RESULT = ADJUSTR(STRING)} 821 822@item @emph{Arguments}: 823@multitable @columnfractions .15 .70 824@item @var{STR} @tab The type shall be @code{CHARACTER}. 825@end multitable 826 827@item @emph{Return value}: 828The return value is of type @code{CHARACTER} and of the same kind as 829@var{STRING} where trailing spaces are removed and the same number of 830spaces are inserted at the start of @var{STRING}. 831 832@item @emph{Example}: 833@smallexample 834program test_adjustr 835 character(len=20) :: str = 'gfortran' 836 str = adjustr(str) 837 print *, str 838end program test_adjustr 839@end smallexample 840 841@item @emph{See also}: 842@ref{ADJUSTL}, @gol 843@ref{TRIM} 844@end table 845 846 847 848@node AIMAG 849@section @code{AIMAG} --- Imaginary part of complex number 850@fnindex AIMAG 851@fnindex DIMAG 852@fnindex IMAG 853@fnindex IMAGPART 854@cindex complex numbers, imaginary part 855 856@table @asis 857@item @emph{Description}: 858@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}. 859The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided 860for compatibility with @command{g77}, and their use in new code is 861strongly discouraged. 862 863@item @emph{Standard}: 864Fortran 77 and later, has overloads that are GNU extensions 865 866@item @emph{Class}: 867Elemental function 868 869@item @emph{Syntax}: 870@code{RESULT = AIMAG(Z)} 871 872@item @emph{Arguments}: 873@multitable @columnfractions .15 .70 874@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}. 875@end multitable 876 877@item @emph{Return value}: 878The return value is of type @code{REAL} with the 879kind type parameter of the argument. 880 881@item @emph{Example}: 882@smallexample 883program test_aimag 884 complex(4) z4 885 complex(8) z8 886 z4 = cmplx(1.e0_4, 0.e0_4) 887 z8 = cmplx(0.e0_8, 1.e0_8) 888 print *, aimag(z4), dimag(z8) 889end program test_aimag 890@end smallexample 891 892@item @emph{Specific names}: 893@multitable @columnfractions .20 .20 .20 .25 894@item Name @tab Argument @tab Return type @tab Standard 895@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later 896@item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension 897@item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 898@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 899@end multitable 900@end table 901 902 903 904@node AINT 905@section @code{AINT} --- Truncate to a whole number 906@fnindex AINT 907@fnindex DINT 908@cindex floor 909@cindex rounding, floor 910 911@table @asis 912@item @emph{Description}: 913@code{AINT(A [, KIND])} truncates its argument to a whole number. 914 915@item @emph{Standard}: 916Fortran 77 and later 917 918@item @emph{Class}: 919Elemental function 920 921@item @emph{Syntax}: 922@code{RESULT = AINT(A [, KIND])} 923 924@item @emph{Arguments}: 925@multitable @columnfractions .15 .70 926@item @var{A} @tab The type of the argument shall be @code{REAL}. 927@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 928expression indicating the kind parameter of the result. 929@end multitable 930 931@item @emph{Return value}: 932The return value is of type @code{REAL} with the kind type parameter of the 933argument if the optional @var{KIND} is absent; otherwise, the kind 934type parameter will be given by @var{KIND}. If the magnitude of 935@var{X} is less than one, @code{AINT(X)} returns zero. If the 936magnitude is equal to or greater than one then it returns the largest 937whole number that does not exceed its magnitude. The sign is the same 938as the sign of @var{X}. 939 940@item @emph{Example}: 941@smallexample 942program test_aint 943 real(4) x4 944 real(8) x8 945 x4 = 1.234E0_4 946 x8 = 4.321_8 947 print *, aint(x4), dint(x8) 948 x8 = aint(x4,8) 949end program test_aint 950@end smallexample 951 952@item @emph{Specific names}: 953@multitable @columnfractions .20 .20 .20 .25 954@item Name @tab Argument @tab Return type @tab Standard 955@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 956@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 957@end multitable 958@end table 959 960 961 962@node ALARM 963@section @code{ALARM} --- Execute a routine after a given delay 964@fnindex ALARM 965@cindex delayed execution 966 967@table @asis 968@item @emph{Description}: 969@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} 970to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to 971set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is 972supplied, it will be returned with the number of seconds remaining until 973any previously scheduled alarm was due to be delivered, or zero if there 974was no previously scheduled alarm. 975 976@item @emph{Standard}: 977GNU extension 978 979@item @emph{Class}: 980Subroutine 981 982@item @emph{Syntax}: 983@code{CALL ALARM(SECONDS, HANDLER [, STATUS])} 984 985@item @emph{Arguments}: 986@multitable @columnfractions .15 .70 987@item @var{SECONDS} @tab The type of the argument shall be a scalar 988@code{INTEGER}. It is @code{INTENT(IN)}. 989@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or 990@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 991values may be either @code{SIG_IGN=1} to ignore the alarm generated 992or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}. 993@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 994variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}. 995@end multitable 996 997@item @emph{Example}: 998@smallexample 999program test_alarm 1000 external handler_print 1001 integer i 1002 call alarm (3, handler_print, i) 1003 print *, i 1004 call sleep(10) 1005end program test_alarm 1006@end smallexample 1007This will cause the external routine @var{handler_print} to be called 1008after 3 seconds. 1009@end table 1010 1011 1012 1013@node ALL 1014@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 1015@fnindex ALL 1016@cindex array, apply condition 1017@cindex array, condition testing 1018 1019@table @asis 1020@item @emph{Description}: 1021@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK} 1022in the array along dimension @var{DIM}. 1023 1024@item @emph{Standard}: 1025Fortran 90 and later 1026 1027@item @emph{Class}: 1028Transformational function 1029 1030@item @emph{Syntax}: 1031@code{RESULT = ALL(MASK [, DIM])} 1032 1033@item @emph{Arguments}: 1034@multitable @columnfractions .15 .70 1035@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1036it shall not be scalar. 1037@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1038with a value that lies between one and the rank of @var{MASK}. 1039@end multitable 1040 1041@item @emph{Return value}: 1042@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where 1043the kind type parameter is the same as the kind type parameter of 1044@var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns 1045an array with the rank of @var{MASK} minus 1. The shape is determined from 1046the shape of @var{MASK} where the @var{DIM} dimension is elided. 1047 1048@table @asis 1049@item (A) 1050@code{ALL(MASK)} is true if all elements of @var{MASK} are true. 1051It also is true if @var{MASK} has zero size; otherwise, it is false. 1052@item (B) 1053If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent 1054to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)} 1055is determined by applying @code{ALL} to the array sections. 1056@end table 1057 1058@item @emph{Example}: 1059@smallexample 1060program test_all 1061 logical l 1062 l = all((/.true., .true., .true./)) 1063 print *, l 1064 call section 1065 contains 1066 subroutine section 1067 integer a(2,3), b(2,3) 1068 a = 1 1069 b = 1 1070 b(2,2) = 2 1071 print *, all(a .eq. b, 1) 1072 print *, all(a .eq. b, 2) 1073 end subroutine section 1074end program test_all 1075@end smallexample 1076@end table 1077 1078 1079 1080@node ALLOCATED 1081@section @code{ALLOCATED} --- Status of an allocatable entity 1082@fnindex ALLOCATED 1083@cindex allocation, status 1084 1085@table @asis 1086@item @emph{Description}: 1087@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation 1088status of @var{ARRAY} and @var{SCALAR}, respectively. 1089 1090@item @emph{Standard}: 1091Fortran 90 and later. Note, the @code{SCALAR=} keyword and allocatable 1092scalar entities are available in Fortran 2003 and later. 1093 1094@item @emph{Class}: 1095Inquiry function 1096 1097@item @emph{Syntax}: 1098@multitable @columnfractions .80 1099@item @code{RESULT = ALLOCATED(ARRAY)} 1100@item @code{RESULT = ALLOCATED(SCALAR)} 1101@end multitable 1102 1103@item @emph{Arguments}: 1104@multitable @columnfractions .15 .70 1105@item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array. 1106@item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar. 1107@end multitable 1108 1109@item @emph{Return value}: 1110The return value is a scalar @code{LOGICAL} with the default logical 1111kind type parameter. If the argument is allocated, then the result is 1112@code{.TRUE.}; otherwise, it returns @code{.FALSE.} 1113 1114@item @emph{Example}: 1115@smallexample 1116program test_allocated 1117 integer :: i = 4 1118 real(4), allocatable :: x(:) 1119 if (.not. allocated(x)) allocate(x(i)) 1120end program test_allocated 1121@end smallexample 1122@end table 1123 1124 1125 1126@node AND 1127@section @code{AND} --- Bitwise logical AND 1128@fnindex AND 1129@cindex bitwise logical and 1130@cindex logical and, bitwise 1131 1132@table @asis 1133@item @emph{Description}: 1134Bitwise logical @code{AND}. 1135 1136This intrinsic routine is provided for backwards compatibility with 1137GNU Fortran 77. For integer arguments, programmers should consider 1138the use of the @ref{IAND} intrinsic defined by the Fortran standard. 1139 1140@item @emph{Standard}: 1141GNU extension 1142 1143@item @emph{Class}: 1144Function 1145 1146@item @emph{Syntax}: 1147@code{RESULT = AND(I, J)} 1148 1149@item @emph{Arguments}: 1150@multitable @columnfractions .15 .70 1151@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 1152type or a scalar @code{LOGICAL} type or a boz-literal-constant. 1153@item @var{J} @tab The type shall be the same as the type of @var{I} or 1154a boz-literal-constant. @var{I} and @var{J} shall not both be 1155boz-literal-constants. If either @var{I} or @var{J} is a 1156boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 1157@end multitable 1158 1159@item @emph{Return value}: 1160The return type is either a scalar @code{INTEGER} or a scalar 1161@code{LOGICAL}. If the kind type parameters differ, then the 1162smaller kind type is implicitly converted to larger kind, and the 1163return has the larger kind. A boz-literal-constant is 1164converted to an @code{INTEGER} with the kind type parameter of 1165the other argument as-if a call to @ref{INT} occurred. 1166 1167@item @emph{Example}: 1168@smallexample 1169PROGRAM test_and 1170 LOGICAL :: T = .TRUE., F = .FALSE. 1171 INTEGER :: a, b 1172 DATA a / Z'F' /, b / Z'3' / 1173 1174 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F) 1175 WRITE (*,*) AND(a, b) 1176END PROGRAM 1177@end smallexample 1178 1179@item @emph{See also}: 1180Fortran 95 elemental function: @gol 1181@ref{IAND} 1182@end table 1183 1184 1185 1186@node ANINT 1187@section @code{ANINT} --- Nearest whole number 1188@fnindex ANINT 1189@fnindex DNINT 1190@cindex ceiling 1191@cindex rounding, ceiling 1192 1193@table @asis 1194@item @emph{Description}: 1195@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number. 1196 1197@item @emph{Standard}: 1198Fortran 77 and later 1199 1200@item @emph{Class}: 1201Elemental function 1202 1203@item @emph{Syntax}: 1204@code{RESULT = ANINT(A [, KIND])} 1205 1206@item @emph{Arguments}: 1207@multitable @columnfractions .15 .70 1208@item @var{A} @tab The type of the argument shall be @code{REAL}. 1209@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 1210expression indicating the kind parameter of the result. 1211@end multitable 1212 1213@item @emph{Return value}: 1214The return value is of type real with the kind type parameter of the 1215argument if the optional @var{KIND} is absent; otherwise, the kind 1216type parameter will be given by @var{KIND}. If @var{A} is greater than 1217zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is 1218less than or equal to zero then it returns @code{AINT(X-0.5)}. 1219 1220@item @emph{Example}: 1221@smallexample 1222program test_anint 1223 real(4) x4 1224 real(8) x8 1225 x4 = 1.234E0_4 1226 x8 = 4.321_8 1227 print *, anint(x4), dnint(x8) 1228 x8 = anint(x4,8) 1229end program test_anint 1230@end smallexample 1231 1232@item @emph{Specific names}: 1233@multitable @columnfractions .20 .20 .20 .25 1234@item Name @tab Argument @tab Return type @tab Standard 1235@item @code{ANINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 1236@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 1237@end multitable 1238@end table 1239 1240 1241 1242@node ANY 1243@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 1244@fnindex ANY 1245@cindex array, apply condition 1246@cindex array, condition testing 1247 1248@table @asis 1249@item @emph{Description}: 1250@code{ANY(MASK [, DIM])} determines if any of the values in the logical array 1251@var{MASK} along dimension @var{DIM} are @code{.TRUE.}. 1252 1253@item @emph{Standard}: 1254Fortran 90 and later 1255 1256@item @emph{Class}: 1257Transformational function 1258 1259@item @emph{Syntax}: 1260@code{RESULT = ANY(MASK [, DIM])} 1261 1262@item @emph{Arguments}: 1263@multitable @columnfractions .15 .70 1264@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1265it shall not be scalar. 1266@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1267with a value that lies between one and the rank of @var{MASK}. 1268@end multitable 1269 1270@item @emph{Return value}: 1271@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where 1272the kind type parameter is the same as the kind type parameter of 1273@var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns 1274an array with the rank of @var{MASK} minus 1. The shape is determined from 1275the shape of @var{MASK} where the @var{DIM} dimension is elided. 1276 1277@table @asis 1278@item (A) 1279@code{ANY(MASK)} is true if any element of @var{MASK} is true; 1280otherwise, it is false. It also is false if @var{MASK} has zero size. 1281@item (B) 1282If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent 1283to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)} 1284is determined by applying @code{ANY} to the array sections. 1285@end table 1286 1287@item @emph{Example}: 1288@smallexample 1289program test_any 1290 logical l 1291 l = any((/.true., .true., .true./)) 1292 print *, l 1293 call section 1294 contains 1295 subroutine section 1296 integer a(2,3), b(2,3) 1297 a = 1 1298 b = 1 1299 b(2,2) = 2 1300 print *, any(a .eq. b, 1) 1301 print *, any(a .eq. b, 2) 1302 end subroutine section 1303end program test_any 1304@end smallexample 1305@end table 1306 1307 1308 1309@node ASIN 1310@section @code{ASIN} --- Arcsine function 1311@fnindex ASIN 1312@fnindex DASIN 1313@cindex trigonometric function, sine, inverse 1314@cindex sine, inverse 1315 1316@table @asis 1317@item @emph{Description}: 1318@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}). 1319 1320@item @emph{Standard}: 1321Fortran 77 and later, for a complex argument Fortran 2008 or later 1322 1323@item @emph{Class}: 1324Elemental function 1325 1326@item @emph{Syntax}: 1327@code{RESULT = ASIN(X)} 1328 1329@item @emph{Arguments}: 1330@multitable @columnfractions .15 .70 1331@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1332less than or equal to one - or be @code{COMPLEX}. 1333@end multitable 1334 1335@item @emph{Return value}: 1336The return value is of the same type and kind as @var{X}. 1337The real part of the result is in radians and lies in the range 1338@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}. 1339 1340@item @emph{Example}: 1341@smallexample 1342program test_asin 1343 real(8) :: x = 0.866_8 1344 x = asin(x) 1345end program test_asin 1346@end smallexample 1347 1348@item @emph{Specific names}: 1349@multitable @columnfractions .20 .20 .20 .25 1350@item Name @tab Argument @tab Return type @tab Standard 1351@item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1352@item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1353@end multitable 1354 1355@item @emph{See also}: 1356Inverse function: @gol 1357@ref{SIN} @gol 1358Degrees function: @gol 1359@ref{ASIND} 1360@end table 1361 1362 1363 1364@node ASIND 1365@section @code{ASIND} --- Arcsine function, degrees 1366@fnindex ASIND 1367@fnindex DASIND 1368@cindex trigonometric function, sine, inverse, degrees 1369@cindex sine, inverse, degrees 1370 1371@table @asis 1372@item @emph{Description}: 1373@code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of 1374@code{SIND(X)}). 1375 1376This function is for compatibility only and should be avoided in favor of 1377standard constructs wherever possible. 1378 1379@item @emph{Standard}: 1380GNU extension, enabled with @option{-fdec-math}. 1381 1382@item @emph{Class}: 1383Elemental function 1384 1385@item @emph{Syntax}: 1386@code{RESULT = ASIND(X)} 1387 1388@item @emph{Arguments}: 1389@multitable @columnfractions .15 .70 1390@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1391less than or equal to one - or be @code{COMPLEX}. 1392@end multitable 1393 1394@item @emph{Return value}: 1395The return value is of the same type and kind as @var{X}. 1396The real part of the result is in degrees and lies in the range 1397@math{-90 \leq \Re \asin(x) \leq 90}. 1398 1399@item @emph{Example}: 1400@smallexample 1401program test_asind 1402 real(8) :: x = 0.866_8 1403 x = asind(x) 1404end program test_asind 1405@end smallexample 1406 1407@item @emph{Specific names}: 1408@multitable @columnfractions .20 .20 .20 .25 1409@item Name @tab Argument @tab Return type @tab Standard 1410@item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 1411@item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1412@end multitable 1413 1414@item @emph{See also}: 1415Inverse function: @gol 1416@ref{SIND} @gol 1417Radians function: @gol 1418@ref{ASIN} 1419@end table 1420 1421 1422 1423@node ASINH 1424@section @code{ASINH} --- Inverse hyperbolic sine function 1425@fnindex ASINH 1426@fnindex DASINH 1427@cindex area hyperbolic sine 1428@cindex inverse hyperbolic sine 1429@cindex hyperbolic function, sine, inverse 1430@cindex sine, hyperbolic, inverse 1431 1432@table @asis 1433@item @emph{Description}: 1434@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}. 1435 1436@item @emph{Standard}: 1437Fortran 2008 and later 1438 1439@item @emph{Class}: 1440Elemental function 1441 1442@item @emph{Syntax}: 1443@code{RESULT = ASINH(X)} 1444 1445@item @emph{Arguments}: 1446@multitable @columnfractions .15 .70 1447@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1448@end multitable 1449 1450@item @emph{Return value}: 1451The return value is of the same type and kind as @var{X}. If @var{X} is 1452complex, the imaginary part of the result is in radians and lies between 1453@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}. 1454 1455@item @emph{Example}: 1456@smallexample 1457PROGRAM test_asinh 1458 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1459 WRITE (*,*) ASINH(x) 1460END PROGRAM 1461@end smallexample 1462 1463@item @emph{Specific names}: 1464@multitable @columnfractions .20 .20 .20 .25 1465@item Name @tab Argument @tab Return type @tab Standard 1466@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension. 1467@end multitable 1468 1469@item @emph{See also}: 1470Inverse function: @gol 1471@ref{SINH} 1472@end table 1473 1474 1475 1476@node ASSOCIATED 1477@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 1478@fnindex ASSOCIATED 1479@cindex pointer, status 1480@cindex association status 1481 1482@table @asis 1483@item @emph{Description}: 1484@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer 1485@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}. 1486 1487@item @emph{Standard}: 1488Fortran 90 and later 1489 1490@item @emph{Class}: 1491Inquiry function 1492 1493@item @emph{Syntax}: 1494@code{RESULT = ASSOCIATED(POINTER [, TARGET])} 1495 1496@item @emph{Arguments}: 1497@multitable @columnfractions .15 .70 1498@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute 1499and it can be of any type. 1500@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or 1501a target. It must have the same type, kind type parameter, and 1502array rank as @var{POINTER}. 1503@end multitable 1504The association status of neither @var{POINTER} nor @var{TARGET} shall be 1505undefined. 1506 1507@item @emph{Return value}: 1508@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}. 1509There are several cases: 1510@table @asis 1511@item (A) When the optional @var{TARGET} is not present then 1512@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false. 1513@item (B) If @var{TARGET} is present and a scalar target, the result is true if 1514@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 1515disassociated, the result is false. 1516@item (C) If @var{TARGET} is present and an array target, the result is true if 1517@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays, 1518are arrays whose elements are not zero-sized storage sequences, and 1519@var{TARGET} and @var{POINTER} occupy the same storage units in array element 1520order. 1521As in case(B), the result is false, if @var{POINTER} is disassociated. 1522@item (D) If @var{TARGET} is present and an scalar pointer, the result is true 1523if @var{TARGET} is associated with @var{POINTER}, the target associated with 1524@var{TARGET} are not zero-sized storage sequences and occupy the same storage 1525units. 1526The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1527@item (E) If @var{TARGET} is present and an array pointer, the result is true if 1528target associated with @var{POINTER} and the target associated with @var{TARGET} 1529have the same shape, are not zero-sized arrays, are arrays whose elements are 1530not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy 1531the same storage units in array element order. 1532The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1533@end table 1534 1535@item @emph{Example}: 1536@smallexample 1537program test_associated 1538 implicit none 1539 real, target :: tgt(2) = (/1., 2./) 1540 real, pointer :: ptr(:) 1541 ptr => tgt 1542 if (associated(ptr) .eqv. .false.) call abort 1543 if (associated(ptr,tgt) .eqv. .false.) call abort 1544end program test_associated 1545@end smallexample 1546 1547@item @emph{See also}: 1548@ref{NULL} 1549@end table 1550 1551 1552 1553@node ATAN 1554@section @code{ATAN} --- Arctangent function 1555@fnindex ATAN 1556@fnindex DATAN 1557@cindex trigonometric function, tangent, inverse 1558@cindex tangent, inverse 1559 1560@table @asis 1561@item @emph{Description}: 1562@code{ATAN(X)} computes the arctangent of @var{X}. 1563 1564@item @emph{Standard}: 1565Fortran 77 and later, for a complex argument and for two arguments 1566Fortran 2008 or later 1567 1568@item @emph{Class}: 1569Elemental function 1570 1571@item @emph{Syntax}: 1572@multitable @columnfractions .80 1573@item @code{RESULT = ATAN(X)} 1574@item @code{RESULT = ATAN(Y, X)} 1575@end multitable 1576 1577@item @emph{Arguments}: 1578@multitable @columnfractions .15 .70 1579@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1580if @var{Y} is present, @var{X} shall be REAL. 1581@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. 1582@end multitable 1583 1584@item @emph{Return value}: 1585The return value is of the same type and kind as @var{X}. 1586If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}. 1587Otherwise, it the arcus tangent of @var{X}, where the real part of 1588the result is in radians and lies in the range 1589@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}. 1590 1591@item @emph{Example}: 1592@smallexample 1593program test_atan 1594 real(8) :: x = 2.866_8 1595 x = atan(x) 1596end program test_atan 1597@end smallexample 1598 1599@item @emph{Specific names}: 1600@multitable @columnfractions .20 .20 .20 .25 1601@item Name @tab Argument @tab Return type @tab Standard 1602@item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1603@item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1604@end multitable 1605 1606@item @emph{See also}: 1607Inverse function: @gol 1608@ref{TAN} @gol 1609Degrees function: @gol 1610@ref{ATAND} 1611@end table 1612 1613 1614 1615@node ATAND 1616@section @code{ATAND} --- Arctangent function, degrees 1617@fnindex ATAND 1618@fnindex DATAND 1619@cindex trigonometric function, tangent, inverse, degrees 1620@cindex tangent, inverse, degrees 1621 1622@table @asis 1623@item @emph{Description}: 1624@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of 1625@ref{TAND}). 1626 1627This function is for compatibility only and should be avoided in favor of 1628standard constructs wherever possible. 1629 1630@item @emph{Standard}: 1631GNU extension, enabled with @option{-fdec-math}. 1632 1633@item @emph{Class}: 1634Elemental function 1635 1636@item @emph{Syntax}: 1637@multitable @columnfractions .80 1638@item @code{RESULT = ATAND(X)} 1639@item @code{RESULT = ATAND(Y, X)} 1640@end multitable 1641 1642@item @emph{Arguments}: 1643@multitable @columnfractions .15 .70 1644@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1645if @var{Y} is present, @var{X} shall be REAL. 1646@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. 1647@end multitable 1648 1649@item @emph{Return value}: 1650The return value is of the same type and kind as @var{X}. 1651If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}. 1652Otherwise, it is the arcus tangent of @var{X}, where the real part of 1653the result is in degrees and lies in the range 1654@math{-90 \leq \Re \atand(x) \leq 90}. 1655 1656@item @emph{Example}: 1657@smallexample 1658program test_atand 1659 real(8) :: x = 2.866_8 1660 x = atand(x) 1661end program test_atand 1662@end smallexample 1663 1664@item @emph{Specific names}: 1665@multitable @columnfractions .20 .20 .20 .25 1666@item Name @tab Argument @tab Return type @tab Standard 1667@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 1668@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1669@end multitable 1670 1671@item @emph{See also}: 1672Inverse function: @gol 1673@ref{TAND} @gol 1674Radians function: @gol 1675@ref{ATAN} 1676@end table 1677 1678 1679 1680@node ATAN2 1681@section @code{ATAN2} --- Arctangent function 1682@fnindex ATAN2 1683@fnindex DATAN2 1684@cindex trigonometric function, tangent, inverse 1685@cindex tangent, inverse 1686 1687@table @asis 1688@item @emph{Description}: 1689@code{ATAN2(Y, X)} computes the principal value of the argument 1690function of the complex number @math{X + i Y}. This function can 1691be used to transform from Cartesian into polar coordinates and 1692allows to determine the angle in the correct quadrant. 1693 1694@item @emph{Standard}: 1695Fortran 77 and later 1696 1697@item @emph{Class}: 1698Elemental function 1699 1700@item @emph{Syntax}: 1701@code{RESULT = ATAN2(Y, X)} 1702 1703@item @emph{Arguments}: 1704@multitable @columnfractions .15 .70 1705@item @var{Y} @tab The type shall be @code{REAL}. 1706@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1707If @var{Y} is zero, then @var{X} must be nonzero. 1708@end multitable 1709 1710@item @emph{Return value}: 1711The return value has the same type and kind type parameter as @var{Y}. It 1712is the principal value of the complex number @math{X + i Y}. If @var{X} 1713is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}. 1714The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1715the return value is zero if @var{X} is strictly positive, @math{\pi} if 1716@var{X} is negative and @var{Y} is positive zero (or the processor does 1717not handle signed zeros), and @math{-\pi} if @var{X} is negative and 1718@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1719magnitude of the result is @math{\pi/2}. 1720 1721@item @emph{Example}: 1722@smallexample 1723program test_atan2 1724 real(4) :: x = 1.e0_4, y = 0.5e0_4 1725 x = atan2(y,x) 1726end program test_atan2 1727@end smallexample 1728 1729@item @emph{Specific names}: 1730@multitable @columnfractions .20 .20 .20 .25 1731@item Name @tab Argument @tab Return type @tab Standard 1732@item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 1733@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 1734@end multitable 1735 1736@item @emph{See also}: 1737Alias: @gol 1738@ref{ATAN} @gol 1739Degrees function: @gol 1740@ref{ATAN2D} 1741@end table 1742 1743 1744 1745@node ATAN2D 1746@section @code{ATAN2D} --- Arctangent function, degrees 1747@fnindex ATAN2D 1748@fnindex DATAN2D 1749@cindex trigonometric function, tangent, inverse, degrees 1750@cindex tangent, inverse, degrees 1751 1752@table @asis 1753@item @emph{Description}: 1754@code{ATAN2D(Y, X)} computes the principal value of the argument 1755function of the complex number @math{X + i Y} in degrees. This function can 1756be used to transform from Cartesian into polar coordinates and 1757allows to determine the angle in the correct quadrant. 1758 1759This function is for compatibility only and should be avoided in favor of 1760standard constructs wherever possible. 1761 1762@item @emph{Standard}: 1763GNU extension, enabled with @option{-fdec-math}. 1764 1765@item @emph{Class}: 1766Elemental function 1767 1768@item @emph{Syntax}: 1769@code{RESULT = ATAN2D(Y, X)} 1770 1771@item @emph{Arguments}: 1772@multitable @columnfractions .15 .70 1773@item @var{Y} @tab The type shall be @code{REAL}. 1774@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1775If @var{Y} is zero, then @var{X} must be nonzero. 1776@end multitable 1777 1778@item @emph{Return value}: 1779The return value has the same type and kind type parameter as @var{Y}. It 1780is the principal value of the complex number @math{X + i Y}. If @var{X} 1781is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}. 1782The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1783the return value is zero if @var{X} is strictly positive, @math{180} if 1784@var{X} is negative and @var{Y} is positive zero (or the processor does 1785not handle signed zeros), and @math{-180} if @var{X} is negative and 1786@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1787magnitude of the result is @math{90}. 1788 1789@item @emph{Example}: 1790@smallexample 1791program test_atan2d 1792 real(4) :: x = 1.e0_4, y = 0.5e0_4 1793 x = atan2d(y,x) 1794end program test_atan2d 1795@end smallexample 1796 1797@item @emph{Specific names}: 1798@multitable @columnfractions .20 .20 .20 .25 1799@item Name @tab Argument @tab Return type @tab Standard 1800@item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU extension 1801@item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension 1802@end multitable 1803 1804@item @emph{See also}: 1805Alias: @gol 1806@ref{ATAND} @gol 1807Radians function: @gol 1808@ref{ATAN2} 1809@end table 1810 1811 1812 1813@node ATANH 1814@section @code{ATANH} --- Inverse hyperbolic tangent function 1815@fnindex ATANH 1816@fnindex DATANH 1817@cindex area hyperbolic tangent 1818@cindex inverse hyperbolic tangent 1819@cindex hyperbolic function, tangent, inverse 1820@cindex tangent, hyperbolic, inverse 1821 1822@table @asis 1823@item @emph{Description}: 1824@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}. 1825 1826@item @emph{Standard}: 1827Fortran 2008 and later 1828 1829@item @emph{Class}: 1830Elemental function 1831 1832@item @emph{Syntax}: 1833@code{RESULT = ATANH(X)} 1834 1835@item @emph{Arguments}: 1836@multitable @columnfractions .15 .70 1837@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1838@end multitable 1839 1840@item @emph{Return value}: 1841The return value has same type and kind as @var{X}. If @var{X} is 1842complex, the imaginary part of the result is in radians and lies between 1843@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}. 1844 1845@item @emph{Example}: 1846@smallexample 1847PROGRAM test_atanh 1848 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1849 WRITE (*,*) ATANH(x) 1850END PROGRAM 1851@end smallexample 1852 1853@item @emph{Specific names}: 1854@multitable @columnfractions .20 .20 .20 .25 1855@item Name @tab Argument @tab Return type @tab Standard 1856@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1857@end multitable 1858 1859@item @emph{See also}: 1860Inverse function: @gol 1861@ref{TANH} 1862@end table 1863 1864 1865 1866@node ATOMIC_ADD 1867@section @code{ATOMIC_ADD} --- Atomic ADD operation 1868@fnindex ATOMIC_ADD 1869@cindex Atomic subroutine, add 1870 1871@table @asis 1872@item @emph{Description}: 1873@code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VALUE} to the 1874variable @var{ATOM}. When @var{STAT} is present and the invocation was 1875successful, it is assigned the value 0. If it is present and the invocation 1876has failed, it is assigned a positive value; in particular, for a coindexed 1877@var{ATOM}, if the remote image has stopped, it is assigned the value of 1878@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1879failed, the value @code{STAT_FAILED_IMAGE}. 1880 1881@item @emph{Standard}: 1882TS 18508 or later 1883 1884@item @emph{Class}: 1885Atomic subroutine 1886 1887@item @emph{Syntax}: 1888@code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])} 1889 1890@item @emph{Arguments}: 1891@multitable @columnfractions .15 .70 1892@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1893type with @code{ATOMIC_INT_KIND} kind. 1894@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1895is different, the value is converted to the kind of @var{ATOM}. 1896@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1897@end multitable 1898 1899@item @emph{Example}: 1900@smallexample 1901program atomic 1902 use iso_fortran_env 1903 integer(atomic_int_kind) :: atom[*] 1904 call atomic_add (atom[1], this_image()) 1905end program atomic 1906@end smallexample 1907 1908@item @emph{See also}: 1909@ref{ATOMIC_DEFINE}, @gol 1910@ref{ATOMIC_FETCH_ADD}, @gol 1911@ref{ISO_FORTRAN_ENV}, @gol 1912@ref{ATOMIC_AND}, @gol 1913@ref{ATOMIC_OR}, @gol 1914@ref{ATOMIC_XOR} 1915@end table 1916 1917 1918 1919 1920@node ATOMIC_AND 1921@section @code{ATOMIC_AND} --- Atomic bitwise AND operation 1922@fnindex ATOMIC_AND 1923@cindex Atomic subroutine, AND 1924 1925@table @asis 1926@item @emph{Description}: 1927@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 1928AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 1929and the invocation was successful, it is assigned the value 0. If it is present 1930and the invocation has failed, it is assigned a positive value; in particular, 1931for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 1932value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 1933image has failed, the value @code{STAT_FAILED_IMAGE}. 1934 1935@item @emph{Standard}: 1936TS 18508 or later 1937 1938@item @emph{Class}: 1939Atomic subroutine 1940 1941@item @emph{Syntax}: 1942@code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])} 1943 1944@item @emph{Arguments}: 1945@multitable @columnfractions .15 .70 1946@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1947type with @code{ATOMIC_INT_KIND} kind. 1948@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1949is different, the value is converted to the kind of @var{ATOM}. 1950@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1951@end multitable 1952 1953@item @emph{Example}: 1954@smallexample 1955program atomic 1956 use iso_fortran_env 1957 integer(atomic_int_kind) :: atom[*] 1958 call atomic_and (atom[1], int(b'10100011101')) 1959end program atomic 1960@end smallexample 1961 1962@item @emph{See also}: 1963@ref{ATOMIC_DEFINE}, @gol 1964@ref{ATOMIC_FETCH_AND}, @gol 1965@ref{ISO_FORTRAN_ENV}, @gol 1966@ref{ATOMIC_ADD}, @gol 1967@ref{ATOMIC_OR}, @gol 1968@ref{ATOMIC_XOR} 1969@end table 1970 1971 1972 1973@node ATOMIC_CAS 1974@section @code{ATOMIC_CAS} --- Atomic compare and swap 1975@fnindex ATOMIC_DEFINE 1976@cindex Atomic subroutine, compare and swap 1977 1978@table @asis 1979@item @emph{Description}: 1980@code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of 1981@var{COMPARE}; if the value is the same, @var{ATOM} is set to the value 1982of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM} 1983that was used for the comparison. When @var{STAT} is present and the invocation 1984was successful, it is assigned the value 0. If it is present and the invocation 1985has failed, it is assigned a positive value; in particular, for a coindexed 1986@var{ATOM}, if the remote image has stopped, it is assigned the value of 1987@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1988failed, the value @code{STAT_FAILED_IMAGE}. 1989 1990@item @emph{Standard}: 1991TS 18508 or later 1992 1993@item @emph{Class}: 1994Atomic subroutine 1995 1996@item @emph{Syntax}: 1997@code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])} 1998 1999@item @emph{Arguments}: 2000@multitable @columnfractions .15 .70 2001@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2002type with @code{ATOMIC_INT_KIND} kind or logical type with 2003@code{ATOMIC_LOGICAL_KIND} kind. 2004@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2005@item @var{COMPARE} @tab Scalar variable of the same type and kind as 2006@var{ATOM}. 2007@item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind 2008is different, the value is converted to the kind of @var{ATOM}. 2009@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2010@end multitable 2011 2012@item @emph{Example}: 2013@smallexample 2014program atomic 2015 use iso_fortran_env 2016 logical(atomic_logical_kind) :: atom[*], prev 2017 call atomic_cas (atom[1], prev, .false., .true.)) 2018end program atomic 2019@end smallexample 2020 2021@item @emph{See also}: 2022@ref{ATOMIC_DEFINE}, @gol 2023@ref{ATOMIC_REF}, @gol 2024@ref{ISO_FORTRAN_ENV} 2025@end table 2026 2027 2028 2029@node ATOMIC_DEFINE 2030@section @code{ATOMIC_DEFINE} --- Setting a variable atomically 2031@fnindex ATOMIC_DEFINE 2032@cindex Atomic subroutine, define 2033 2034@table @asis 2035@item @emph{Description}: 2036@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value 2037@var{VALUE} atomically. When @var{STAT} is present and the invocation was 2038successful, it is assigned the value 0. If it is present and the invocation 2039has failed, it is assigned a positive value; in particular, for a coindexed 2040@var{ATOM}, if the remote image has stopped, it is assigned the value of 2041@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2042failed, the value @code{STAT_FAILED_IMAGE}. 2043 2044@item @emph{Standard}: 2045Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2046 2047@item @emph{Class}: 2048Atomic subroutine 2049 2050@item @emph{Syntax}: 2051@code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])} 2052 2053@item @emph{Arguments}: 2054@multitable @columnfractions .15 .70 2055@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2056type with @code{ATOMIC_INT_KIND} kind or logical type with 2057@code{ATOMIC_LOGICAL_KIND} kind. 2058 2059@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2060is different, the value is converted to the kind of @var{ATOM}. 2061@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2062@end multitable 2063 2064@item @emph{Example}: 2065@smallexample 2066program atomic 2067 use iso_fortran_env 2068 integer(atomic_int_kind) :: atom[*] 2069 call atomic_define (atom[1], this_image()) 2070end program atomic 2071@end smallexample 2072 2073@item @emph{See also}: 2074@ref{ATOMIC_REF}, @gol 2075@ref{ATOMIC_CAS}, @gol 2076@ref{ISO_FORTRAN_ENV}, @gol 2077@ref{ATOMIC_ADD}, @gol 2078@ref{ATOMIC_AND}, @gol 2079@ref{ATOMIC_OR}, @gol 2080@ref{ATOMIC_XOR} 2081@end table 2082 2083 2084 2085@node ATOMIC_FETCH_ADD 2086@section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch 2087@fnindex ATOMIC_FETCH_ADD 2088@cindex Atomic subroutine, ADD with fetch 2089 2090@table @asis 2091@item @emph{Description}: 2092@code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of 2093@var{ATOM} in @var{OLD} and adds the value of @var{VALUE} to the 2094variable @var{ATOM}. When @var{STAT} is present and the invocation was 2095successful, it is assigned the value 0. If it is present and the invocation 2096has failed, it is assigned a positive value; in particular, for a coindexed 2097@var{ATOM}, if the remote image has stopped, it is assigned the value of 2098@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2099failed, the value @code{STAT_FAILED_IMAGE}. 2100 2101@item @emph{Standard}: 2102TS 18508 or later 2103 2104@item @emph{Class}: 2105Atomic subroutine 2106 2107@item @emph{Syntax}: 2108@code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])} 2109 2110@item @emph{Arguments}: 2111@multitable @columnfractions .15 .70 2112@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2113type with @code{ATOMIC_INT_KIND} kind. 2114@code{ATOMIC_LOGICAL_KIND} kind. 2115 2116@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2117is different, the value is converted to the kind of @var{ATOM}. 2118@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2119@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2120@end multitable 2121 2122@item @emph{Example}: 2123@smallexample 2124program atomic 2125 use iso_fortran_env 2126 integer(atomic_int_kind) :: atom[*], old 2127 call atomic_add (atom[1], this_image(), old) 2128end program atomic 2129@end smallexample 2130 2131@item @emph{See also}: 2132@ref{ATOMIC_DEFINE}, @gol 2133@ref{ATOMIC_ADD}, @gol 2134@ref{ISO_FORTRAN_ENV}, @gol 2135@ref{ATOMIC_FETCH_AND}, @gol 2136@ref{ATOMIC_FETCH_OR}, @gol 2137@ref{ATOMIC_FETCH_XOR} 2138@end table 2139 2140 2141 2142@node ATOMIC_FETCH_AND 2143@section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch 2144@fnindex ATOMIC_FETCH_AND 2145@cindex Atomic subroutine, AND with fetch 2146 2147@table @asis 2148@item @emph{Description}: 2149@code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2150@var{OLD} and defines @var{ATOM} with the bitwise AND between the values of 2151@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2152successful, it is assigned the value 0. If it is present and the invocation has 2153failed, it is assigned a positive value; in particular, for a coindexed 2154@var{ATOM}, if the remote image has stopped, it is assigned the value of 2155@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2156failed, the value @code{STAT_FAILED_IMAGE}. 2157 2158@item @emph{Standard}: 2159TS 18508 or later 2160 2161@item @emph{Class}: 2162Atomic subroutine 2163 2164@item @emph{Syntax}: 2165@code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])} 2166 2167@item @emph{Arguments}: 2168@multitable @columnfractions .15 .70 2169@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2170type with @code{ATOMIC_INT_KIND} kind. 2171@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2172is different, the value is converted to the kind of @var{ATOM}. 2173@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2174@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2175@end multitable 2176 2177@item @emph{Example}: 2178@smallexample 2179program atomic 2180 use iso_fortran_env 2181 integer(atomic_int_kind) :: atom[*], old 2182 call atomic_fetch_and (atom[1], int(b'10100011101'), old) 2183end program atomic 2184@end smallexample 2185 2186@item @emph{See also}: 2187@ref{ATOMIC_DEFINE}, @gol 2188@ref{ATOMIC_AND}, @gol 2189@ref{ISO_FORTRAN_ENV}, @gol 2190@ref{ATOMIC_FETCH_ADD}, @gol 2191@ref{ATOMIC_FETCH_OR}, @gol 2192@ref{ATOMIC_FETCH_XOR} 2193@end table 2194 2195 2196 2197@node ATOMIC_FETCH_OR 2198@section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch 2199@fnindex ATOMIC_FETCH_OR 2200@cindex Atomic subroutine, OR with fetch 2201 2202@table @asis 2203@item @emph{Description}: 2204@code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2205@var{OLD} and defines @var{ATOM} with the bitwise OR between the values of 2206@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2207successful, it is assigned the value 0. If it is present and the invocation has 2208failed, it is assigned a positive value; in particular, for a coindexed 2209@var{ATOM}, if the remote image has stopped, it is assigned the value of 2210@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2211failed, the value @code{STAT_FAILED_IMAGE}. 2212 2213@item @emph{Standard}: 2214TS 18508 or later 2215 2216@item @emph{Class}: 2217Atomic subroutine 2218 2219@item @emph{Syntax}: 2220@code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])} 2221 2222@item @emph{Arguments}: 2223@multitable @columnfractions .15 .70 2224@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2225type with @code{ATOMIC_INT_KIND} kind. 2226@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2227is different, the value is converted to the kind of @var{ATOM}. 2228@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2229@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2230@end multitable 2231 2232@item @emph{Example}: 2233@smallexample 2234program atomic 2235 use iso_fortran_env 2236 integer(atomic_int_kind) :: atom[*], old 2237 call atomic_fetch_or (atom[1], int(b'10100011101'), old) 2238end program atomic 2239@end smallexample 2240 2241@item @emph{See also}: 2242@ref{ATOMIC_DEFINE}, @gol 2243@ref{ATOMIC_OR}, @gol 2244@ref{ISO_FORTRAN_ENV}, @gol 2245@ref{ATOMIC_FETCH_ADD}, @gol 2246@ref{ATOMIC_FETCH_AND}, @gol 2247@ref{ATOMIC_FETCH_XOR} 2248@end table 2249 2250 2251 2252@node ATOMIC_FETCH_XOR 2253@section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch 2254@fnindex ATOMIC_FETCH_XOR 2255@cindex Atomic subroutine, XOR with fetch 2256 2257@table @asis 2258@item @emph{Description}: 2259@code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2260@var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of 2261@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2262successful, it is assigned the value 0. If it is present and the invocation has 2263failed, it is assigned a positive value; in particular, for a coindexed 2264@var{ATOM}, if the remote image has stopped, it is assigned the value of 2265@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2266failed, the value @code{STAT_FAILED_IMAGE}. 2267 2268@item @emph{Standard}: 2269TS 18508 or later 2270 2271@item @emph{Class}: 2272Atomic subroutine 2273 2274@item @emph{Syntax}: 2275@code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])} 2276 2277@item @emph{Arguments}: 2278@multitable @columnfractions .15 .70 2279@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2280type with @code{ATOMIC_INT_KIND} kind. 2281@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2282is different, the value is converted to the kind of @var{ATOM}. 2283@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2284@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2285@end multitable 2286 2287@item @emph{Example}: 2288@smallexample 2289program atomic 2290 use iso_fortran_env 2291 integer(atomic_int_kind) :: atom[*], old 2292 call atomic_fetch_xor (atom[1], int(b'10100011101'), old) 2293end program atomic 2294@end smallexample 2295 2296@item @emph{See also}: 2297@ref{ATOMIC_DEFINE}, @gol 2298@ref{ATOMIC_XOR}, @gol 2299@ref{ISO_FORTRAN_ENV}, @gol 2300@ref{ATOMIC_FETCH_ADD}, @gol 2301@ref{ATOMIC_FETCH_AND}, @gol 2302@ref{ATOMIC_FETCH_OR} 2303@end table 2304 2305 2306 2307@node ATOMIC_OR 2308@section @code{ATOMIC_OR} --- Atomic bitwise OR operation 2309@fnindex ATOMIC_OR 2310@cindex Atomic subroutine, OR 2311 2312@table @asis 2313@item @emph{Description}: 2314@code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2315AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2316and the invocation was successful, it is assigned the value 0. If it is present 2317and the invocation has failed, it is assigned a positive value; in particular, 2318for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2319value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2320image has failed, the value @code{STAT_FAILED_IMAGE}. 2321 2322@item @emph{Standard}: 2323TS 18508 or later 2324 2325@item @emph{Class}: 2326Atomic subroutine 2327 2328@item @emph{Syntax}: 2329@code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])} 2330 2331@item @emph{Arguments}: 2332@multitable @columnfractions .15 .70 2333@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2334type with @code{ATOMIC_INT_KIND} kind. 2335@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2336is different, the value is converted to the kind of @var{ATOM}. 2337@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2338@end multitable 2339 2340@item @emph{Example}: 2341@smallexample 2342program atomic 2343 use iso_fortran_env 2344 integer(atomic_int_kind) :: atom[*] 2345 call atomic_or (atom[1], int(b'10100011101')) 2346end program atomic 2347@end smallexample 2348 2349@item @emph{See also}: 2350@ref{ATOMIC_DEFINE}, @gol 2351@ref{ATOMIC_FETCH_OR}, @gol 2352@ref{ISO_FORTRAN_ENV}, @gol 2353@ref{ATOMIC_ADD}, @gol 2354@ref{ATOMIC_OR}, @gol 2355@ref{ATOMIC_XOR} 2356@end table 2357 2358 2359 2360@node ATOMIC_REF 2361@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically 2362@fnindex ATOMIC_REF 2363@cindex Atomic subroutine, reference 2364 2365@table @asis 2366@item @emph{Description}: 2367@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the 2368variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the 2369invocation was successful, it is assigned the value 0. If it is present and the 2370invocation has failed, it is assigned a positive value; in particular, for a 2371coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value 2372of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image 2373has failed, the value @code{STAT_FAILED_IMAGE}. 2374 2375 2376@item @emph{Standard}: 2377Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2378 2379@item @emph{Class}: 2380Atomic subroutine 2381 2382@item @emph{Syntax}: 2383@code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])} 2384 2385@item @emph{Arguments}: 2386@multitable @columnfractions .15 .70 2387@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2388is different, the value is converted to the kind of @var{ATOM}. 2389@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2390type with @code{ATOMIC_INT_KIND} kind or logical type with 2391@code{ATOMIC_LOGICAL_KIND} kind. 2392@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2393@end multitable 2394 2395@item @emph{Example}: 2396@smallexample 2397program atomic 2398 use iso_fortran_env 2399 logical(atomic_logical_kind) :: atom[*] 2400 logical :: val 2401 call atomic_ref (atom, .false.) 2402 ! ... 2403 call atomic_ref (atom, val) 2404 if (val) then 2405 print *, "Obtained" 2406 end if 2407end program atomic 2408@end smallexample 2409 2410@item @emph{See also}: 2411@ref{ATOMIC_DEFINE}, @gol 2412@ref{ATOMIC_CAS}, @gol 2413@ref{ISO_FORTRAN_ENV}, @gol 2414@ref{ATOMIC_FETCH_ADD}, @gol 2415@ref{ATOMIC_FETCH_AND}, @gol 2416@ref{ATOMIC_FETCH_OR}, @gol 2417@ref{ATOMIC_FETCH_XOR} 2418@end table 2419 2420 2421@node ATOMIC_XOR 2422@section @code{ATOMIC_XOR} --- Atomic bitwise OR operation 2423@fnindex ATOMIC_XOR 2424@cindex Atomic subroutine, XOR 2425 2426@table @asis 2427@item @emph{Description}: 2428@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2429XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2430and the invocation was successful, it is assigned the value 0. If it is present 2431and the invocation has failed, it is assigned a positive value; in particular, 2432for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2433value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2434image has failed, the value @code{STAT_FAILED_IMAGE}. 2435 2436@item @emph{Standard}: 2437TS 18508 or later 2438 2439@item @emph{Class}: 2440Atomic subroutine 2441 2442@item @emph{Syntax}: 2443@code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])} 2444 2445@item @emph{Arguments}: 2446@multitable @columnfractions .15 .70 2447@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2448type with @code{ATOMIC_INT_KIND} kind. 2449@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2450is different, the value is converted to the kind of @var{ATOM}. 2451@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2452@end multitable 2453 2454@item @emph{Example}: 2455@smallexample 2456program atomic 2457 use iso_fortran_env 2458 integer(atomic_int_kind) :: atom[*] 2459 call atomic_xor (atom[1], int(b'10100011101')) 2460end program atomic 2461@end smallexample 2462 2463@item @emph{See also}: 2464@ref{ATOMIC_DEFINE}, @gol 2465@ref{ATOMIC_FETCH_XOR}, @gol 2466@ref{ISO_FORTRAN_ENV}, @gol 2467@ref{ATOMIC_ADD}, @gol 2468@ref{ATOMIC_OR}, @gol 2469@ref{ATOMIC_XOR} 2470@end table 2471 2472 2473@node BACKTRACE 2474@section @code{BACKTRACE} --- Show a backtrace 2475@fnindex BACKTRACE 2476@cindex backtrace 2477 2478@table @asis 2479@item @emph{Description}: 2480@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program 2481execution continues normally afterwards. The backtrace information is printed 2482to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}. 2483 2484@item @emph{Standard}: 2485GNU extension 2486 2487@item @emph{Class}: 2488Subroutine 2489 2490@item @emph{Syntax}: 2491@code{CALL BACKTRACE} 2492 2493@item @emph{Arguments}: 2494None 2495 2496@item @emph{See also}: 2497@ref{ABORT} 2498@end table 2499 2500 2501 2502@node BESSEL_J0 2503@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0 2504@fnindex BESSEL_J0 2505@fnindex BESJ0 2506@fnindex DBESJ0 2507@cindex Bessel function, first kind 2508 2509@table @asis 2510@item @emph{Description}: 2511@code{BESSEL_J0(X)} computes the Bessel function of the first kind of 2512order 0 of @var{X}. This function is available under the name 2513@code{BESJ0} as a GNU extension. 2514 2515@item @emph{Standard}: 2516Fortran 2008 and later 2517 2518@item @emph{Class}: 2519Elemental function 2520 2521@item @emph{Syntax}: 2522@code{RESULT = BESSEL_J0(X)} 2523 2524@item @emph{Arguments}: 2525@multitable @columnfractions .15 .70 2526@item @var{X} @tab The type shall be @code{REAL}. 2527@end multitable 2528 2529@item @emph{Return value}: 2530The return value is of type @code{REAL} and lies in the 2531range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same 2532kind as @var{X}. 2533 2534@item @emph{Example}: 2535@smallexample 2536program test_besj0 2537 real(8) :: x = 0.0_8 2538 x = bessel_j0(x) 2539end program test_besj0 2540@end smallexample 2541 2542@item @emph{Specific names}: 2543@multitable @columnfractions .20 .20 .20 .25 2544@item Name @tab Argument @tab Return type @tab Standard 2545@item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2546@end multitable 2547@end table 2548 2549 2550 2551@node BESSEL_J1 2552@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1 2553@fnindex BESSEL_J1 2554@fnindex BESJ1 2555@fnindex DBESJ1 2556@cindex Bessel function, first kind 2557 2558@table @asis 2559@item @emph{Description}: 2560@code{BESSEL_J1(X)} computes the Bessel function of the first kind of 2561order 1 of @var{X}. This function is available under the name 2562@code{BESJ1} as a GNU extension. 2563 2564@item @emph{Standard}: 2565Fortran 2008 2566 2567@item @emph{Class}: 2568Elemental function 2569 2570@item @emph{Syntax}: 2571@code{RESULT = BESSEL_J1(X)} 2572 2573@item @emph{Arguments}: 2574@multitable @columnfractions .15 .70 2575@item @var{X} @tab The type shall be @code{REAL}. 2576@end multitable 2577 2578@item @emph{Return value}: 2579The return value is of type @code{REAL} and lies in the 2580range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same 2581kind as @var{X}. 2582 2583@item @emph{Example}: 2584@smallexample 2585program test_besj1 2586 real(8) :: x = 1.0_8 2587 x = bessel_j1(x) 2588end program test_besj1 2589@end smallexample 2590 2591@item @emph{Specific names}: 2592@multitable @columnfractions .20 .20 .20 .25 2593@item Name @tab Argument @tab Return type @tab Standard 2594@item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2595@end multitable 2596@end table 2597 2598 2599 2600@node BESSEL_JN 2601@section @code{BESSEL_JN} --- Bessel function of the first kind 2602@fnindex BESSEL_JN 2603@fnindex BESJN 2604@fnindex DBESJN 2605@cindex Bessel function, first kind 2606 2607@table @asis 2608@item @emph{Description}: 2609@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of 2610order @var{N} of @var{X}. This function is available under the name 2611@code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays, 2612their ranks and shapes shall conform. 2613 2614@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions 2615of the first kind of the orders @var{N1} to @var{N2}. 2616 2617@item @emph{Standard}: 2618Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2619 2620@item @emph{Class}: 2621Elemental function, except for the transformational function 2622@code{BESSEL_JN(N1, N2, X)} 2623 2624@item @emph{Syntax}: 2625@multitable @columnfractions .80 2626@item @code{RESULT = BESSEL_JN(N, X)} 2627@item @code{RESULT = BESSEL_JN(N1, N2, X)} 2628@end multitable 2629 2630@item @emph{Arguments}: 2631@multitable @columnfractions .15 .70 2632@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}. 2633@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2634@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2635@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2636for @code{BESSEL_JN(N1, N2, X)} it shall be scalar. 2637@end multitable 2638 2639@item @emph{Return value}: 2640The return value is a scalar of type @code{REAL}. It has the same 2641kind as @var{X}. 2642 2643@item @emph{Note}: 2644The transformational function uses a recurrence algorithm which might, 2645for some values of @var{X}, lead to different results than calls to 2646the elemental function. 2647 2648@item @emph{Example}: 2649@smallexample 2650program test_besjn 2651 real(8) :: x = 1.0_8 2652 x = bessel_jn(5,x) 2653end program test_besjn 2654@end smallexample 2655 2656@item @emph{Specific names}: 2657@multitable @columnfractions .20 .20 .20 .25 2658@item Name @tab Argument @tab Return type @tab Standard 2659@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2660@item @tab @code{REAL(8) X} @tab @tab 2661@end multitable 2662@end table 2663 2664 2665 2666@node BESSEL_Y0 2667@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0 2668@fnindex BESSEL_Y0 2669@fnindex BESY0 2670@fnindex DBESY0 2671@cindex Bessel function, second kind 2672 2673@table @asis 2674@item @emph{Description}: 2675@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of 2676order 0 of @var{X}. This function is available under the name 2677@code{BESY0} as a GNU extension. 2678 2679@item @emph{Standard}: 2680Fortran 2008 and later 2681 2682@item @emph{Class}: 2683Elemental function 2684 2685@item @emph{Syntax}: 2686@code{RESULT = BESSEL_Y0(X)} 2687 2688@item @emph{Arguments}: 2689@multitable @columnfractions .15 .70 2690@item @var{X} @tab The type shall be @code{REAL}. 2691@end multitable 2692 2693@item @emph{Return value}: 2694The return value is of type @code{REAL}. It has the same kind as @var{X}. 2695 2696@item @emph{Example}: 2697@smallexample 2698program test_besy0 2699 real(8) :: x = 0.0_8 2700 x = bessel_y0(x) 2701end program test_besy0 2702@end smallexample 2703 2704@item @emph{Specific names}: 2705@multitable @columnfractions .20 .20 .20 .25 2706@item Name @tab Argument @tab Return type @tab Standard 2707@item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2708@end multitable 2709@end table 2710 2711 2712 2713@node BESSEL_Y1 2714@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1 2715@fnindex BESSEL_Y1 2716@fnindex BESY1 2717@fnindex DBESY1 2718@cindex Bessel function, second kind 2719 2720@table @asis 2721@item @emph{Description}: 2722@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of 2723order 1 of @var{X}. This function is available under the name 2724@code{BESY1} as a GNU extension. 2725 2726@item @emph{Standard}: 2727Fortran 2008 and later 2728 2729@item @emph{Class}: 2730Elemental function 2731 2732@item @emph{Syntax}: 2733@code{RESULT = BESSEL_Y1(X)} 2734 2735@item @emph{Arguments}: 2736@multitable @columnfractions .15 .70 2737@item @var{X} @tab The type shall be @code{REAL}. 2738@end multitable 2739 2740@item @emph{Return value}: 2741The return value is of type @code{REAL}. It has the same kind as @var{X}. 2742 2743@item @emph{Example}: 2744@smallexample 2745program test_besy1 2746 real(8) :: x = 1.0_8 2747 x = bessel_y1(x) 2748end program test_besy1 2749@end smallexample 2750 2751@item @emph{Specific names}: 2752@multitable @columnfractions .20 .20 .20 .25 2753@item Name @tab Argument @tab Return type @tab Standard 2754@item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2755@end multitable 2756@end table 2757 2758 2759 2760@node BESSEL_YN 2761@section @code{BESSEL_YN} --- Bessel function of the second kind 2762@fnindex BESSEL_YN 2763@fnindex BESYN 2764@fnindex DBESYN 2765@cindex Bessel function, second kind 2766 2767@table @asis 2768@item @emph{Description}: 2769@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of 2770order @var{N} of @var{X}. This function is available under the name 2771@code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays, 2772their ranks and shapes shall conform. 2773 2774@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions 2775of the first kind of the orders @var{N1} to @var{N2}. 2776 2777@item @emph{Standard}: 2778Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2779 2780@item @emph{Class}: 2781Elemental function, except for the transformational function 2782@code{BESSEL_YN(N1, N2, X)} 2783 2784@item @emph{Syntax}: 2785@multitable @columnfractions .80 2786@item @code{RESULT = BESSEL_YN(N, X)} 2787@item @code{RESULT = BESSEL_YN(N1, N2, X)} 2788@end multitable 2789 2790@item @emph{Arguments}: 2791@multitable @columnfractions .15 .70 2792@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} . 2793@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2794@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2795@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2796for @code{BESSEL_YN(N1, N2, X)} it shall be scalar. 2797@end multitable 2798 2799@item @emph{Return value}: 2800The return value is a scalar of type @code{REAL}. It has the same 2801kind as @var{X}. 2802 2803@item @emph{Note}: 2804The transformational function uses a recurrence algorithm which might, 2805for some values of @var{X}, lead to different results than calls to 2806the elemental function. 2807 2808@item @emph{Example}: 2809@smallexample 2810program test_besyn 2811 real(8) :: x = 1.0_8 2812 x = bessel_yn(5,x) 2813end program test_besyn 2814@end smallexample 2815 2816@item @emph{Specific names}: 2817@multitable @columnfractions .20 .20 .20 .25 2818@item Name @tab Argument @tab Return type @tab Standard 2819@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2820@item @tab @code{REAL(8) X} @tab @tab 2821@end multitable 2822@end table 2823 2824 2825 2826@node BGE 2827@section @code{BGE} --- Bitwise greater than or equal to 2828@fnindex BGE 2829@cindex bitwise comparison 2830 2831@table @asis 2832@item @emph{Description}: 2833Determines whether an integral is a bitwise greater than or equal to 2834another. 2835 2836@item @emph{Standard}: 2837Fortran 2008 and later 2838 2839@item @emph{Class}: 2840Elemental function 2841 2842@item @emph{Syntax}: 2843@code{RESULT = BGE(I, J)} 2844 2845@item @emph{Arguments}: 2846@multitable @columnfractions .15 .70 2847@item @var{I} @tab Shall be of @code{INTEGER} type. 2848@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2849as @var{I}. 2850@end multitable 2851 2852@item @emph{Return value}: 2853The return value is of type @code{LOGICAL} and of the default kind. 2854 2855@item @emph{See also}: 2856@ref{BGT}, @gol 2857@ref{BLE}, @gol 2858@ref{BLT} 2859@end table 2860 2861 2862 2863@node BGT 2864@section @code{BGT} --- Bitwise greater than 2865@fnindex BGT 2866@cindex bitwise comparison 2867 2868@table @asis 2869@item @emph{Description}: 2870Determines whether an integral is a bitwise greater than another. 2871 2872@item @emph{Standard}: 2873Fortran 2008 and later 2874 2875@item @emph{Class}: 2876Elemental function 2877 2878@item @emph{Syntax}: 2879@code{RESULT = BGT(I, J)} 2880 2881@item @emph{Arguments}: 2882@multitable @columnfractions .15 .70 2883@item @var{I} @tab Shall be of @code{INTEGER} type. 2884@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2885as @var{I}. 2886@end multitable 2887 2888@item @emph{Return value}: 2889The return value is of type @code{LOGICAL} and of the default kind. 2890 2891@item @emph{See also}: 2892@ref{BGE}, @gol 2893@ref{BLE}, @gol 2894@ref{BLT} 2895@end table 2896 2897 2898 2899@node BIT_SIZE 2900@section @code{BIT_SIZE} --- Bit size inquiry function 2901@fnindex BIT_SIZE 2902@cindex bits, number of 2903@cindex size of a variable, in bits 2904 2905@table @asis 2906@item @emph{Description}: 2907@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) 2908represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is 2909independent of the actual value of @var{I}. 2910 2911@item @emph{Standard}: 2912Fortran 90 and later 2913 2914@item @emph{Class}: 2915Inquiry function 2916 2917@item @emph{Syntax}: 2918@code{RESULT = BIT_SIZE(I)} 2919 2920@item @emph{Arguments}: 2921@multitable @columnfractions .15 .70 2922@item @var{I} @tab The type shall be @code{INTEGER}. 2923@end multitable 2924 2925@item @emph{Return value}: 2926The return value is of type @code{INTEGER} 2927 2928@item @emph{Example}: 2929@smallexample 2930program test_bit_size 2931 integer :: i = 123 2932 integer :: size 2933 size = bit_size(i) 2934 print *, size 2935end program test_bit_size 2936@end smallexample 2937@end table 2938 2939 2940 2941@node BLE 2942@section @code{BLE} --- Bitwise less than or equal to 2943@fnindex BLE 2944@cindex bitwise comparison 2945 2946@table @asis 2947@item @emph{Description}: 2948Determines whether an integral is a bitwise less than or equal to 2949another. 2950 2951@item @emph{Standard}: 2952Fortran 2008 and later 2953 2954@item @emph{Class}: 2955Elemental function 2956 2957@item @emph{Syntax}: 2958@code{RESULT = BLE(I, J)} 2959 2960@item @emph{Arguments}: 2961@multitable @columnfractions .15 .70 2962@item @var{I} @tab Shall be of @code{INTEGER} type. 2963@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2964as @var{I}. 2965@end multitable 2966 2967@item @emph{Return value}: 2968The return value is of type @code{LOGICAL} and of the default kind. 2969 2970@item @emph{See also}: 2971@ref{BGT}, @gol 2972@ref{BGE}, @gol 2973@ref{BLT} 2974@end table 2975 2976 2977 2978@node BLT 2979@section @code{BLT} --- Bitwise less than 2980@fnindex BLT 2981@cindex bitwise comparison 2982 2983@table @asis 2984@item @emph{Description}: 2985Determines whether an integral is a bitwise less than another. 2986 2987@item @emph{Standard}: 2988Fortran 2008 and later 2989 2990@item @emph{Class}: 2991Elemental function 2992 2993@item @emph{Syntax}: 2994@code{RESULT = BLT(I, J)} 2995 2996@item @emph{Arguments}: 2997@multitable @columnfractions .15 .70 2998@item @var{I} @tab Shall be of @code{INTEGER} type. 2999@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 3000as @var{I}. 3001@end multitable 3002 3003@item @emph{Return value}: 3004The return value is of type @code{LOGICAL} and of the default kind. 3005 3006@item @emph{See also}: 3007@ref{BGE}, @gol 3008@ref{BGT}, @gol 3009@ref{BLE} 3010@end table 3011 3012 3013 3014@node BTEST 3015@section @code{BTEST} --- Bit test function 3016@fnindex BTEST 3017@fnindex BBTEST 3018@fnindex BITEST 3019@fnindex BJTEST 3020@fnindex BKTEST 3021@cindex bits, testing 3022 3023@table @asis 3024@item @emph{Description}: 3025@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} 3026in @var{I} is set. The counting of the bits starts at 0. 3027 3028@item @emph{Standard}: 3029Fortran 90 and later, has overloads that are GNU extensions 3030 3031@item @emph{Class}: 3032Elemental function 3033 3034@item @emph{Syntax}: 3035@code{RESULT = BTEST(I, POS)} 3036 3037@item @emph{Arguments}: 3038@multitable @columnfractions .15 .70 3039@item @var{I} @tab The type shall be @code{INTEGER}. 3040@item @var{POS} @tab The type shall be @code{INTEGER}. 3041@end multitable 3042 3043@item @emph{Return value}: 3044The return value is of type @code{LOGICAL} 3045 3046@item @emph{Example}: 3047@smallexample 3048program test_btest 3049 integer :: i = 32768 + 1024 + 64 3050 integer :: pos 3051 logical :: bool 3052 do pos=0,16 3053 bool = btest(i, pos) 3054 print *, pos, bool 3055 end do 3056end program test_btest 3057@end smallexample 3058 3059@item @emph{Specific names}: 3060@multitable @columnfractions .20 .20 .20 .25 3061@item Name @tab Argument @tab Return type @tab Standard 3062@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later 3063@item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension 3064@item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension 3065@item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension 3066@item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension 3067@end multitable 3068@end table 3069 3070@node C_ASSOCIATED 3071@section @code{C_ASSOCIATED} --- Status of a C pointer 3072@fnindex C_ASSOCIATED 3073@cindex association status, C pointer 3074@cindex pointer, C association status 3075 3076@table @asis 3077@item @emph{Description}: 3078@code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer 3079@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}. 3080 3081@item @emph{Standard}: 3082Fortran 2003 and later 3083 3084@item @emph{Class}: 3085Inquiry function 3086 3087@item @emph{Syntax}: 3088@code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])} 3089 3090@item @emph{Arguments}: 3091@multitable @columnfractions .15 .70 3092@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}. 3093@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}. 3094@end multitable 3095 3096@item @emph{Return value}: 3097The return value is of type @code{LOGICAL}; it is @code{.false.} if either 3098@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2} 3099point to different addresses. 3100 3101@item @emph{Example}: 3102@smallexample 3103subroutine association_test(a,b) 3104 use iso_c_binding, only: c_associated, c_loc, c_ptr 3105 implicit none 3106 real, pointer :: a 3107 type(c_ptr) :: b 3108 if(c_associated(b, c_loc(a))) & 3109 stop 'b and a do not point to same target' 3110end subroutine association_test 3111@end smallexample 3112 3113@item @emph{See also}: 3114@ref{C_LOC}, @gol 3115@ref{C_FUNLOC} 3116@end table 3117 3118 3119@node C_F_POINTER 3120@section @code{C_F_POINTER} --- Convert C into Fortran pointer 3121@fnindex C_F_POINTER 3122@cindex pointer, convert C to Fortran 3123 3124@table @asis 3125@item @emph{Description}: 3126@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer 3127@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape. 3128 3129@item @emph{Standard}: 3130Fortran 2003 and later 3131 3132@item @emph{Class}: 3133Subroutine 3134 3135@item @emph{Syntax}: 3136@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])} 3137 3138@item @emph{Arguments}: 3139@multitable @columnfractions .15 .70 3140@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is 3141@code{INTENT(IN)}. 3142@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is 3143@code{INTENT(OUT)}. 3144@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER} 3145with @code{INTENT(IN)}. It shall be present 3146if and only if @var{fptr} is an array. The size 3147must be equal to the rank of @var{fptr}. 3148@end multitable 3149 3150@item @emph{Example}: 3151@smallexample 3152program main 3153 use iso_c_binding 3154 implicit none 3155 interface 3156 subroutine my_routine(p) bind(c,name='myC_func') 3157 import :: c_ptr 3158 type(c_ptr), intent(out) :: p 3159 end subroutine 3160 end interface 3161 type(c_ptr) :: cptr 3162 real,pointer :: a(:) 3163 call my_routine(cptr) 3164 call c_f_pointer(cptr, a, [12]) 3165end program main 3166@end smallexample 3167 3168@item @emph{See also}: 3169@ref{C_LOC}, @gol 3170@ref{C_F_PROCPOINTER} 3171@end table 3172 3173 3174@node C_F_PROCPOINTER 3175@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer 3176@fnindex C_F_PROCPOINTER 3177@cindex pointer, C address of pointers 3178 3179@table @asis 3180@item @emph{Description}: 3181@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer 3182@var{CPTR} to the Fortran procedure pointer @var{FPTR}. 3183 3184@item @emph{Standard}: 3185Fortran 2003 and later 3186 3187@item @emph{Class}: 3188Subroutine 3189 3190@item @emph{Syntax}: 3191@code{CALL C_F_PROCPOINTER(cptr, fptr)} 3192 3193@item @emph{Arguments}: 3194@multitable @columnfractions .15 .70 3195@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is 3196@code{INTENT(IN)}. 3197@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is 3198@code{INTENT(OUT)}. 3199@end multitable 3200 3201@item @emph{Example}: 3202@smallexample 3203program main 3204 use iso_c_binding 3205 implicit none 3206 abstract interface 3207 function func(a) 3208 import :: c_float 3209 real(c_float), intent(in) :: a 3210 real(c_float) :: func 3211 end function 3212 end interface 3213 interface 3214 function getIterFunc() bind(c,name="getIterFunc") 3215 import :: c_funptr 3216 type(c_funptr) :: getIterFunc 3217 end function 3218 end interface 3219 type(c_funptr) :: cfunptr 3220 procedure(func), pointer :: myFunc 3221 cfunptr = getIterFunc() 3222 call c_f_procpointer(cfunptr, myFunc) 3223end program main 3224@end smallexample 3225 3226@item @emph{See also}: 3227@ref{C_LOC}, @gol 3228@ref{C_F_POINTER} 3229@end table 3230 3231 3232@node C_FUNLOC 3233@section @code{C_FUNLOC} --- Obtain the C address of a procedure 3234@fnindex C_FUNLOC 3235@cindex pointer, C address of procedures 3236 3237@table @asis 3238@item @emph{Description}: 3239@code{C_FUNLOC(x)} determines the C address of the argument. 3240 3241@item @emph{Standard}: 3242Fortran 2003 and later 3243 3244@item @emph{Class}: 3245Inquiry function 3246 3247@item @emph{Syntax}: 3248@code{RESULT = C_FUNLOC(x)} 3249 3250@item @emph{Arguments}: 3251@multitable @columnfractions .15 .70 3252@item @var{x} @tab Interoperable function or pointer to such function. 3253@end multitable 3254 3255@item @emph{Return value}: 3256The return value is of type @code{C_FUNPTR} and contains the C address 3257of the argument. 3258 3259@item @emph{Example}: 3260@smallexample 3261module x 3262 use iso_c_binding 3263 implicit none 3264contains 3265 subroutine sub(a) bind(c) 3266 real(c_float) :: a 3267 a = sqrt(a)+5.0 3268 end subroutine sub 3269end module x 3270program main 3271 use iso_c_binding 3272 use x 3273 implicit none 3274 interface 3275 subroutine my_routine(p) bind(c,name='myC_func') 3276 import :: c_funptr 3277 type(c_funptr), intent(in) :: p 3278 end subroutine 3279 end interface 3280 call my_routine(c_funloc(sub)) 3281end program main 3282@end smallexample 3283 3284@item @emph{See also}: 3285@ref{C_ASSOCIATED}, @gol 3286@ref{C_LOC}, @gol 3287@ref{C_F_POINTER}, @gol 3288@ref{C_F_PROCPOINTER} 3289@end table 3290 3291 3292@node C_LOC 3293@section @code{C_LOC} --- Obtain the C address of an object 3294@fnindex C_LOC 3295@cindex procedure pointer, convert C to Fortran 3296 3297@table @asis 3298@item @emph{Description}: 3299@code{C_LOC(X)} determines the C address of the argument. 3300 3301@item @emph{Standard}: 3302Fortran 2003 and later 3303 3304@item @emph{Class}: 3305Inquiry function 3306 3307@item @emph{Syntax}: 3308@code{RESULT = C_LOC(X)} 3309 3310@item @emph{Arguments}: 3311@multitable @columnfractions .10 .75 3312@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. 3313 3314@end multitable 3315 3316@item @emph{Return value}: 3317The return value is of type @code{C_PTR} and contains the C address 3318of the argument. 3319 3320@item @emph{Example}: 3321@smallexample 3322subroutine association_test(a,b) 3323 use iso_c_binding, only: c_associated, c_loc, c_ptr 3324 implicit none 3325 real, pointer :: a 3326 type(c_ptr) :: b 3327 if(c_associated(b, c_loc(a))) & 3328 stop 'b and a do not point to same target' 3329end subroutine association_test 3330@end smallexample 3331 3332@item @emph{See also}: 3333@ref{C_ASSOCIATED}, @gol 3334@ref{C_FUNLOC}, @gol 3335@ref{C_F_POINTER}, @gol 3336@ref{C_F_PROCPOINTER} 3337@end table 3338 3339 3340@node C_SIZEOF 3341@section @code{C_SIZEOF} --- Size in bytes of an expression 3342@fnindex C_SIZEOF 3343@cindex expression size 3344@cindex size of an expression 3345 3346@table @asis 3347@item @emph{Description}: 3348@code{C_SIZEOF(X)} calculates the number of bytes of storage the 3349expression @code{X} occupies. 3350 3351@item @emph{Standard}: 3352Fortran 2008 3353 3354@item @emph{Class}: 3355Inquiry function of the module @code{ISO_C_BINDING} 3356 3357@item @emph{Syntax}: 3358@code{N = C_SIZEOF(X)} 3359 3360@item @emph{Arguments}: 3361@multitable @columnfractions .15 .70 3362@item @var{X} @tab The argument shall be an interoperable data entity. 3363@end multitable 3364 3365@item @emph{Return value}: 3366The return value is of type integer and of the system-dependent kind 3367@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the 3368number of bytes occupied by the argument. If the argument has the 3369@code{POINTER} attribute, the number of bytes of the storage area pointed 3370to is returned. If the argument is of a derived type with @code{POINTER} 3371or @code{ALLOCATABLE} components, the return value does not account for 3372the sizes of the data pointed to by these components. 3373 3374@item @emph{Example}: 3375@smallexample 3376 use iso_c_binding 3377 integer(c_int) :: i 3378 real(c_float) :: r, s(5) 3379 print *, (c_sizeof(s)/c_sizeof(r) == 5) 3380 end 3381@end smallexample 3382The example will print @code{T} unless you are using a platform 3383where default @code{REAL} variables are unusually padded. 3384 3385@item @emph{See also}: 3386@ref{SIZEOF}, @gol 3387@ref{STORAGE_SIZE} 3388@end table 3389 3390 3391@node CEILING 3392@section @code{CEILING} --- Integer ceiling function 3393@fnindex CEILING 3394@cindex ceiling 3395@cindex rounding, ceiling 3396 3397@table @asis 3398@item @emph{Description}: 3399@code{CEILING(A)} returns the least integer greater than or equal to @var{A}. 3400 3401@item @emph{Standard}: 3402Fortran 95 and later 3403 3404@item @emph{Class}: 3405Elemental function 3406 3407@item @emph{Syntax}: 3408@code{RESULT = CEILING(A [, KIND])} 3409 3410@item @emph{Arguments}: 3411@multitable @columnfractions .15 .70 3412@item @var{A} @tab The type shall be @code{REAL}. 3413@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3414expression indicating the kind parameter of the result. 3415@end multitable 3416 3417@item @emph{Return value}: 3418The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 3419and a default-kind @code{INTEGER} otherwise. 3420 3421@item @emph{Example}: 3422@smallexample 3423program test_ceiling 3424 real :: x = 63.29 3425 real :: y = -63.59 3426 print *, ceiling(x) ! returns 64 3427 print *, ceiling(y) ! returns -63 3428end program test_ceiling 3429@end smallexample 3430 3431@item @emph{See also}: 3432@ref{FLOOR}, @gol 3433@ref{NINT} 3434@end table 3435 3436 3437 3438@node CHAR 3439@section @code{CHAR} --- Character conversion function 3440@fnindex CHAR 3441@cindex conversion, to character 3442 3443@table @asis 3444@item @emph{Description}: 3445@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}. 3446 3447@item @emph{Standard}: 3448Fortran 77 and later 3449 3450@item @emph{Class}: 3451Elemental function 3452 3453@item @emph{Syntax}: 3454@code{RESULT = CHAR(I [, KIND])} 3455 3456@item @emph{Arguments}: 3457@multitable @columnfractions .15 .70 3458@item @var{I} @tab The type shall be @code{INTEGER}. 3459@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3460expression indicating the kind parameter of the result. 3461@end multitable 3462 3463@item @emph{Return value}: 3464The return value is of type @code{CHARACTER(1)} 3465 3466@item @emph{Example}: 3467@smallexample 3468program test_char 3469 integer :: i = 74 3470 character(1) :: c 3471 c = char(i) 3472 print *, i, c ! returns 'J' 3473end program test_char 3474@end smallexample 3475 3476@item @emph{Specific names}: 3477@multitable @columnfractions .18 .18 .24 .25 3478@item Name @tab Argument @tab Return type @tab Standard 3479@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later 3480@end multitable 3481 3482@item @emph{Note}: 3483See @ref{ICHAR} for a discussion of converting between numerical values 3484and formatted string representations. 3485 3486@item @emph{See also}: 3487@ref{ACHAR}, @gol 3488@ref{IACHAR}, @gol 3489@ref{ICHAR} 3490 3491@end table 3492 3493 3494 3495@node CHDIR 3496@section @code{CHDIR} --- Change working directory 3497@fnindex CHDIR 3498@cindex system, working directory 3499 3500@table @asis 3501@item @emph{Description}: 3502Change current working directory to a specified path. 3503 3504This intrinsic is provided in both subroutine and function forms; however, 3505only one form can be used in any given program unit. 3506 3507@item @emph{Standard}: 3508GNU extension 3509 3510@item @emph{Class}: 3511Subroutine, function 3512 3513@item @emph{Syntax}: 3514@multitable @columnfractions .80 3515@item @code{CALL CHDIR(NAME [, STATUS])} 3516@item @code{STATUS = CHDIR(NAME)} 3517@end multitable 3518 3519@item @emph{Arguments}: 3520@multitable @columnfractions .15 .70 3521@item @var{NAME} @tab The type shall be @code{CHARACTER} of default 3522kind and shall specify a valid path within the file system. 3523@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default 3524kind. Returns 0 on success, and a system specific and nonzero error code 3525otherwise. 3526@end multitable 3527 3528@item @emph{Example}: 3529@smallexample 3530PROGRAM test_chdir 3531 CHARACTER(len=255) :: path 3532 CALL getcwd(path) 3533 WRITE(*,*) TRIM(path) 3534 CALL chdir("/tmp") 3535 CALL getcwd(path) 3536 WRITE(*,*) TRIM(path) 3537END PROGRAM 3538@end smallexample 3539 3540@item @emph{See also}: 3541@ref{GETCWD} 3542@end table 3543 3544 3545 3546@node CHMOD 3547@section @code{CHMOD} --- Change access permissions of files 3548@fnindex CHMOD 3549@cindex file system, change access mode 3550 3551@table @asis 3552@item @emph{Description}: 3553@code{CHMOD} changes the permissions of a file. 3554 3555This intrinsic is provided in both subroutine and function forms; however, 3556only one form can be used in any given program unit. 3557 3558@item @emph{Standard}: 3559GNU extension 3560 3561@item @emph{Class}: 3562Subroutine, function 3563 3564@item @emph{Syntax}: 3565@multitable @columnfractions .80 3566@item @code{CALL CHMOD(NAME, MODE[, STATUS])} 3567@item @code{STATUS = CHMOD(NAME, MODE)} 3568@end multitable 3569 3570@item @emph{Arguments}: 3571@multitable @columnfractions .15 .70 3572 3573@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 3574file name. Trailing blanks are ignored unless the character 3575@code{achar(0)} is present, then all characters up to and excluding 3576@code{achar(0)} are used as the file name. 3577 3578@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the 3579file permission. @var{MODE} uses the same syntax as the @code{chmod} utility 3580as defined by the POSIX standard. The argument shall either be a string of 3581a nonnegative octal number or a symbolic mode. 3582 3583@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is 3584@code{0} on success and nonzero otherwise. 3585@end multitable 3586 3587@item @emph{Return value}: 3588In either syntax, @var{STATUS} is set to @code{0} on success and nonzero 3589otherwise. 3590 3591@item @emph{Example}: 3592@code{CHMOD} as subroutine 3593@smallexample 3594program chmod_test 3595 implicit none 3596 integer :: status 3597 call chmod('test.dat','u+x',status) 3598 print *, 'Status: ', status 3599end program chmod_test 3600@end smallexample 3601@code{CHMOD} as function: 3602@smallexample 3603program chmod_test 3604 implicit none 3605 integer :: status 3606 status = chmod('test.dat','u+x') 3607 print *, 'Status: ', status 3608end program chmod_test 3609@end smallexample 3610 3611@end table 3612 3613 3614 3615@node CMPLX 3616@section @code{CMPLX} --- Complex conversion function 3617@fnindex CMPLX 3618@cindex complex numbers, conversion to 3619@cindex conversion, to complex 3620 3621@table @asis 3622@item @emph{Description}: 3623@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to 3624the real component. If @var{Y} is present it is converted to the imaginary 3625component. If @var{Y} is not present then the imaginary component is set to 36260.0. If @var{X} is complex then @var{Y} must not be present. 3627 3628@item @emph{Standard}: 3629Fortran 77 and later 3630 3631@item @emph{Class}: 3632Elemental function 3633 3634@item @emph{Syntax}: 3635@code{RESULT = CMPLX(X [, Y [, KIND]])} 3636 3637@item @emph{Arguments}: 3638@multitable @columnfractions .15 .70 3639@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 3640or @code{COMPLEX}. 3641@item @var{Y} @tab (Optional; only allowed if @var{X} is not 3642@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. 3643@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3644expression indicating the kind parameter of the result. 3645@end multitable 3646 3647@item @emph{Return value}: 3648The return value is of @code{COMPLEX} type, with a kind equal to 3649@var{KIND} if it is specified. If @var{KIND} is not specified, the 3650result is of the default @code{COMPLEX} kind, regardless of the kinds of 3651@var{X} and @var{Y}. 3652 3653@item @emph{Example}: 3654@smallexample 3655program test_cmplx 3656 integer :: i = 42 3657 real :: x = 3.14 3658 complex :: z 3659 z = cmplx(i, x) 3660 print *, z, cmplx(x) 3661end program test_cmplx 3662@end smallexample 3663 3664@item @emph{See also}: 3665@ref{COMPLEX} 3666@end table 3667 3668 3669 3670@node CO_BROADCAST 3671@section @code{CO_BROADCAST} --- Copy a value to all images the current set of images 3672@fnindex CO_BROADCAST 3673@cindex Collectives, value broadcasting 3674 3675@table @asis 3676@item @emph{Description}: 3677@code{CO_BROADCAST} copies the value of argument @var{A} on the image with 3678image index @code{SOURCE_IMAGE} to all images in the current team. @var{A} 3679becomes defined as if by intrinsic assignment. If the execution was 3680successful and @var{STAT} is present, it is assigned the value zero. If the 3681execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3682@var{ERRMSG} gets assigned a value describing the occurred error. 3683 3684@item @emph{Standard}: 3685Technical Specification (TS) 18508 or later 3686 3687@item @emph{Class}: 3688Collective subroutine 3689 3690@item @emph{Syntax}: 3691@code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])} 3692 3693@item @emph{Arguments}: 3694@multitable @columnfractions .20 .65 3695@item @var{A} @tab INTENT(INOUT) argument; shall have the same 3696dynamic type and type parameters on all images of the current team. If it 3697is an array, it shall have the same shape on all images. 3698@item @var{SOURCE_IMAGE} @tab a scalar integer expression. 3699It shall have the same value on all images and refer to an 3700image of the current team. 3701@item @var{STAT} @tab (optional) a scalar integer variable 3702@item @var{ERRMSG} @tab (optional) a scalar character variable 3703@end multitable 3704 3705@item @emph{Example}: 3706@smallexample 3707program test 3708 integer :: val(3) 3709 if (this_image() == 1) then 3710 val = [1, 5, 3] 3711 end if 3712 call co_broadcast (val, source_image=1) 3713 print *, this_image, ":", val 3714end program test 3715@end smallexample 3716 3717@item @emph{See also}: 3718@ref{CO_MAX}, @gol 3719@ref{CO_MIN}, @gol 3720@ref{CO_SUM}, @gol 3721@ref{CO_REDUCE} 3722@end table 3723 3724 3725 3726@node CO_MAX 3727@section @code{CO_MAX} --- Maximal value on the current set of images 3728@fnindex CO_MAX 3729@cindex Collectives, maximal value 3730 3731@table @asis 3732@item @emph{Description}: 3733@code{CO_MAX} determines element-wise the maximal value of @var{A} on all 3734images of the current team. If @var{RESULT_IMAGE} is present, the maximum 3735values are returned in @var{A} on the specified image only and the value 3736of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3737not present, the value is returned on all images. If the execution was 3738successful and @var{STAT} is present, it is assigned the value zero. If the 3739execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3740@var{ERRMSG} gets assigned a value describing the occurred error. 3741 3742@item @emph{Standard}: 3743Technical Specification (TS) 18508 or later 3744 3745@item @emph{Class}: 3746Collective subroutine 3747 3748@item @emph{Syntax}: 3749@code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])} 3750 3751@item @emph{Arguments}: 3752@multitable @columnfractions .20 .65 3753@item @var{A} @tab shall be an integer, real or character variable, 3754which has the same type and type parameters on all images of the team. 3755@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3756present, it shall have the same value on all images and refer to an 3757image of the current team. 3758@item @var{STAT} @tab (optional) a scalar integer variable 3759@item @var{ERRMSG} @tab (optional) a scalar character variable 3760@end multitable 3761 3762@item @emph{Example}: 3763@smallexample 3764program test 3765 integer :: val 3766 val = this_image () 3767 call co_max (val, result_image=1) 3768 if (this_image() == 1) then 3769 write(*,*) "Maximal value", val ! prints num_images() 3770 end if 3771end program test 3772@end smallexample 3773 3774@item @emph{See also}: 3775@ref{CO_MIN}, @gol 3776@ref{CO_SUM}, @gol 3777@ref{CO_REDUCE}, @gol 3778@ref{CO_BROADCAST} 3779@end table 3780 3781 3782 3783@node CO_MIN 3784@section @code{CO_MIN} --- Minimal value on the current set of images 3785@fnindex CO_MIN 3786@cindex Collectives, minimal value 3787 3788@table @asis 3789@item @emph{Description}: 3790@code{CO_MIN} determines element-wise the minimal value of @var{A} on all 3791images of the current team. If @var{RESULT_IMAGE} is present, the minimal 3792values are returned in @var{A} on the specified image only and the value 3793of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3794not present, the value is returned on all images. If the execution was 3795successful and @var{STAT} is present, it is assigned the value zero. If the 3796execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3797@var{ERRMSG} gets assigned a value describing the occurred error. 3798 3799@item @emph{Standard}: 3800Technical Specification (TS) 18508 or later 3801 3802@item @emph{Class}: 3803Collective subroutine 3804 3805@item @emph{Syntax}: 3806@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3807 3808@item @emph{Arguments}: 3809@multitable @columnfractions .20 .65 3810@item @var{A} @tab shall be an integer, real or character variable, 3811which has the same type and type parameters on all images of the team. 3812@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3813present, it shall have the same value on all images and refer to an 3814image of the current team. 3815@item @var{STAT} @tab (optional) a scalar integer variable 3816@item @var{ERRMSG} @tab (optional) a scalar character variable 3817@end multitable 3818 3819@item @emph{Example}: 3820@smallexample 3821program test 3822 integer :: val 3823 val = this_image () 3824 call co_min (val, result_image=1) 3825 if (this_image() == 1) then 3826 write(*,*) "Minimal value", val ! prints 1 3827 end if 3828end program test 3829@end smallexample 3830 3831@item @emph{See also}: 3832@ref{CO_MAX}, @gol 3833@ref{CO_SUM}, @gol 3834@ref{CO_REDUCE}, @gol 3835@ref{CO_BROADCAST} 3836@end table 3837 3838 3839 3840@node CO_REDUCE 3841@section @code{CO_REDUCE} --- Reduction of values on the current set of images 3842@fnindex CO_REDUCE 3843@cindex Collectives, generic reduction 3844 3845@table @asis 3846@item @emph{Description}: 3847@code{CO_REDUCE} determines element-wise the reduction of the value of @var{A} 3848on all images of the current team. The pure function passed as @var{OPERATOR} 3849is used to pairwise reduce the values of @var{A} by passing either the value 3850of @var{A} of different images or the result values of such a reduction as 3851argument. If @var{A} is an array, the deduction is done element wise. If 3852@var{RESULT_IMAGE} is present, the result values are returned in @var{A} on 3853the specified image only and the value of @var{A} on the other images become 3854undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all 3855images. If the execution was successful and @var{STAT} is present, it is 3856assigned the value zero. If the execution failed, @var{STAT} gets assigned 3857a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing 3858the occurred error. 3859 3860@item @emph{Standard}: 3861Technical Specification (TS) 18508 or later 3862 3863@item @emph{Class}: 3864Collective subroutine 3865 3866@item @emph{Syntax}: 3867@code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])} 3868 3869@item @emph{Arguments}: 3870@multitable @columnfractions .20 .65 3871@item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be 3872nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, 3873it shall be associated. @var{A} shall have the same type and type parameters on 3874all images of the team; if it is an array, it shall have the same shape on all 3875images. 3876@item @var{OPERATOR} @tab pure function with two scalar nonallocatable 3877arguments, which shall be nonpolymorphic and have the same type and type 3878parameters as @var{A}. The function shall return a nonallocatable scalar of 3879the same type and type parameters as @var{A}. The function shall be the same on 3880all images and with regards to the arguments mathematically commutative and 3881associative. Note that @var{OPERATOR} may not be an elemental function, unless 3882it is an intrisic function. 3883@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3884present, it shall have the same value on all images and refer to an 3885image of the current team. 3886@item @var{STAT} @tab (optional) a scalar integer variable 3887@item @var{ERRMSG} @tab (optional) a scalar character variable 3888@end multitable 3889 3890@item @emph{Example}: 3891@smallexample 3892program test 3893 integer :: val 3894 val = this_image () 3895 call co_reduce (val, result_image=1, operator=myprod) 3896 if (this_image() == 1) then 3897 write(*,*) "Product value", val ! prints num_images() factorial 3898 end if 3899contains 3900 pure function myprod(a, b) 3901 integer, value :: a, b 3902 integer :: myprod 3903 myprod = a * b 3904 end function myprod 3905end program test 3906@end smallexample 3907 3908@item @emph{Note}: 3909While the rules permit in principle an intrinsic function, none of the 3910intrinsics in the standard fulfill the criteria of having a specific 3911function, which takes two arguments of the same type and returning that 3912type as result. 3913 3914@item @emph{See also}: 3915@ref{CO_MIN}, @gol 3916@ref{CO_MAX}, @gol 3917@ref{CO_SUM}, @gol 3918@ref{CO_BROADCAST} 3919@end table 3920 3921 3922 3923@node CO_SUM 3924@section @code{CO_SUM} --- Sum of values on the current set of images 3925@fnindex CO_SUM 3926@cindex Collectives, sum of values 3927 3928@table @asis 3929@item @emph{Description}: 3930@code{CO_SUM} sums up the values of each element of @var{A} on all 3931images of the current team. If @var{RESULT_IMAGE} is present, the summed-up 3932values are returned in @var{A} on the specified image only and the value 3933of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3934not present, the value is returned on all images. If the execution was 3935successful and @var{STAT} is present, it is assigned the value zero. If the 3936execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3937@var{ERRMSG} gets assigned a value describing the occurred error. 3938 3939@item @emph{Standard}: 3940Technical Specification (TS) 18508 or later 3941 3942@item @emph{Class}: 3943Collective subroutine 3944 3945@item @emph{Syntax}: 3946@code{CALL CO_SUM(A [, RESULT_IMAGE, STAT, ERRMSG])} 3947 3948@item @emph{Arguments}: 3949@multitable @columnfractions .20 .65 3950@item @var{A} @tab shall be an integer, real or complex variable, 3951which has the same type and type parameters on all images of the team. 3952@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3953present, it shall have the same value on all images and refer to an 3954image of the current team. 3955@item @var{STAT} @tab (optional) a scalar integer variable 3956@item @var{ERRMSG} @tab (optional) a scalar character variable 3957@end multitable 3958 3959@item @emph{Example}: 3960@smallexample 3961program test 3962 integer :: val 3963 val = this_image () 3964 call co_sum (val, result_image=1) 3965 if (this_image() == 1) then 3966 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, 3967 ! with n = num_images() 3968 end if 3969end program test 3970@end smallexample 3971 3972@item @emph{See also}: 3973@ref{CO_MAX}, @gol 3974@ref{CO_MIN}, @gol 3975@ref{CO_REDUCE}, @gol 3976@ref{CO_BROADCAST} 3977@end table 3978 3979 3980 3981@node COMMAND_ARGUMENT_COUNT 3982@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments 3983@fnindex COMMAND_ARGUMENT_COUNT 3984@cindex command-line arguments 3985@cindex command-line arguments, number of 3986@cindex arguments, to program 3987 3988@table @asis 3989@item @emph{Description}: 3990@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the 3991command line when the containing program was invoked. 3992 3993@item @emph{Standard}: 3994Fortran 2003 and later 3995 3996@item @emph{Class}: 3997Inquiry function 3998 3999@item @emph{Syntax}: 4000@code{RESULT = COMMAND_ARGUMENT_COUNT()} 4001 4002@item @emph{Arguments}: 4003@multitable @columnfractions .15 .70 4004@item None 4005@end multitable 4006 4007@item @emph{Return value}: 4008The return value is an @code{INTEGER} of default kind. 4009 4010@item @emph{Example}: 4011@smallexample 4012program test_command_argument_count 4013 integer :: count 4014 count = command_argument_count() 4015 print *, count 4016end program test_command_argument_count 4017@end smallexample 4018 4019@item @emph{See also}: 4020@ref{GET_COMMAND}, @gol 4021@ref{GET_COMMAND_ARGUMENT} 4022@end table 4023 4024 4025 4026@node COMPILER_OPTIONS 4027@section @code{COMPILER_OPTIONS} --- Options passed to the compiler 4028@fnindex COMPILER_OPTIONS 4029@cindex flags inquiry function 4030@cindex options inquiry function 4031@cindex compiler flags inquiry function 4032 4033@table @asis 4034@item @emph{Description}: 4035@code{COMPILER_OPTIONS} returns a string with the options used for 4036compiling. 4037 4038@item @emph{Standard}: 4039Fortran 2008 4040 4041@item @emph{Class}: 4042Inquiry function of the module @code{ISO_FORTRAN_ENV} 4043 4044@item @emph{Syntax}: 4045@code{STR = COMPILER_OPTIONS()} 4046 4047@item @emph{Arguments}: 4048None 4049 4050@item @emph{Return value}: 4051The return value is a default-kind string with system-dependent length. 4052It contains the compiler flags used to compile the file, which called 4053the @code{COMPILER_OPTIONS} intrinsic. 4054 4055@item @emph{Example}: 4056@smallexample 4057 use iso_fortran_env 4058 print '(4a)', 'This file was compiled by ', & 4059 compiler_version(), ' using the options ', & 4060 compiler_options() 4061 end 4062@end smallexample 4063 4064@item @emph{See also}: 4065@ref{COMPILER_VERSION}, @gol 4066@ref{ISO_FORTRAN_ENV} 4067@end table 4068 4069 4070 4071@node COMPILER_VERSION 4072@section @code{COMPILER_VERSION} --- Compiler version string 4073@fnindex COMPILER_VERSION 4074@cindex compiler, name and version 4075@cindex version of the compiler 4076 4077@table @asis 4078@item @emph{Description}: 4079@code{COMPILER_VERSION} returns a string with the name and the 4080version of the compiler. 4081 4082@item @emph{Standard}: 4083Fortran 2008 4084 4085@item @emph{Class}: 4086Inquiry function of the module @code{ISO_FORTRAN_ENV} 4087 4088@item @emph{Syntax}: 4089@code{STR = COMPILER_VERSION()} 4090 4091@item @emph{Arguments}: 4092None 4093 4094@item @emph{Return value}: 4095The return value is a default-kind string with system-dependent length. 4096It contains the name of the compiler and its version number. 4097 4098@item @emph{Example}: 4099@smallexample 4100 use iso_fortran_env 4101 print '(4a)', 'This file was compiled by ', & 4102 compiler_version(), ' using the options ', & 4103 compiler_options() 4104 end 4105@end smallexample 4106 4107@item @emph{See also}: 4108@ref{COMPILER_OPTIONS}, @gol 4109@ref{ISO_FORTRAN_ENV} 4110@end table 4111 4112 4113 4114@node COMPLEX 4115@section @code{COMPLEX} --- Complex conversion function 4116@fnindex COMPLEX 4117@cindex complex numbers, conversion to 4118@cindex conversion, to complex 4119 4120@table @asis 4121@item @emph{Description}: 4122@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted 4123to the real component and @var{Y} is converted to the imaginary 4124component. 4125 4126@item @emph{Standard}: 4127GNU extension 4128 4129@item @emph{Class}: 4130Elemental function 4131 4132@item @emph{Syntax}: 4133@code{RESULT = COMPLEX(X, Y)} 4134 4135@item @emph{Arguments}: 4136@multitable @columnfractions .15 .70 4137@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4138@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}. 4139@end multitable 4140 4141@item @emph{Return value}: 4142If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return 4143value is of default @code{COMPLEX} type. 4144 4145If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL} 4146type and one is of @code{INTEGER} type, then the return value is of 4147@code{COMPLEX} type with a kind equal to that of the @code{REAL} 4148argument with the highest precision. 4149 4150@item @emph{Example}: 4151@smallexample 4152program test_complex 4153 integer :: i = 42 4154 real :: x = 3.14 4155 print *, complex(i, x) 4156end program test_complex 4157@end smallexample 4158 4159@item @emph{See also}: 4160@ref{CMPLX} 4161@end table 4162 4163 4164 4165@node CONJG 4166@section @code{CONJG} --- Complex conjugate function 4167@fnindex CONJG 4168@fnindex DCONJG 4169@cindex complex conjugate 4170 4171@table @asis 4172@item @emph{Description}: 4173@code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)} 4174then the result is @code{(x, -y)} 4175 4176@item @emph{Standard}: 4177Fortran 77 and later, has an overload that is a GNU extension 4178 4179@item @emph{Class}: 4180Elemental function 4181 4182@item @emph{Syntax}: 4183@code{Z = CONJG(Z)} 4184 4185@item @emph{Arguments}: 4186@multitable @columnfractions .15 .70 4187@item @var{Z} @tab The type shall be @code{COMPLEX}. 4188@end multitable 4189 4190@item @emph{Return value}: 4191The return value is of type @code{COMPLEX}. 4192 4193@item @emph{Example}: 4194@smallexample 4195program test_conjg 4196 complex :: z = (2.0, 3.0) 4197 complex(8) :: dz = (2.71_8, -3.14_8) 4198 z= conjg(z) 4199 print *, z 4200 dz = dconjg(dz) 4201 print *, dz 4202end program test_conjg 4203@end smallexample 4204 4205@item @emph{Specific names}: 4206@multitable @columnfractions .20 .20 .20 .25 4207@item Name @tab Argument @tab Return type @tab Standard 4208@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension 4209@end multitable 4210@end table 4211 4212 4213 4214@node COS 4215@section @code{COS} --- Cosine function 4216@fnindex COS 4217@fnindex DCOS 4218@fnindex CCOS 4219@fnindex ZCOS 4220@fnindex CDCOS 4221@cindex trigonometric function, cosine 4222@cindex cosine 4223 4224@table @asis 4225@item @emph{Description}: 4226@code{COS(X)} computes the cosine of @var{X}. 4227 4228@item @emph{Standard}: 4229Fortran 77 and later, has overloads that are GNU extensions 4230 4231@item @emph{Class}: 4232Elemental function 4233 4234@item @emph{Syntax}: 4235@code{RESULT = COS(X)} 4236 4237@item @emph{Arguments}: 4238@multitable @columnfractions .15 .70 4239@item @var{X} @tab The type shall be @code{REAL} or 4240@code{COMPLEX}. 4241@end multitable 4242 4243@item @emph{Return value}: 4244The return value is of the same type and kind as @var{X}. The real part 4245of the result is in radians. If @var{X} is of the type @code{REAL}, 4246the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}. 4247 4248@item @emph{Example}: 4249@smallexample 4250program test_cos 4251 real :: x = 0.0 4252 x = cos(x) 4253end program test_cos 4254@end smallexample 4255 4256@item @emph{Specific names}: 4257@multitable @columnfractions .20 .20 .20 .25 4258@item Name @tab Argument @tab Return type @tab Standard 4259@item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4260@item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4261@item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 4262@item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4263@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4264@end multitable 4265 4266@item @emph{See also}: 4267Inverse function: @gol 4268@ref{ACOS} @gol 4269Degrees function: @gol 4270@ref{COSD} 4271@end table 4272 4273 4274 4275@node COSD 4276@section @code{COSD} --- Cosine function, degrees 4277@fnindex COSD 4278@fnindex DCOSD 4279@fnindex CCOSD 4280@fnindex ZCOSD 4281@fnindex CDCOSD 4282@cindex trigonometric function, cosine, degrees 4283@cindex cosine, degrees 4284 4285@table @asis 4286@item @emph{Description}: 4287@code{COSD(X)} computes the cosine of @var{X} in degrees. 4288 4289This function is for compatibility only and should be avoided in favor of 4290standard constructs wherever possible. 4291 4292@item @emph{Standard}: 4293GNU extension, enabled with @option{-fdec-math}. 4294 4295@item @emph{Class}: 4296Elemental function 4297 4298@item @emph{Syntax}: 4299@code{RESULT = COSD(X)} 4300 4301@item @emph{Arguments}: 4302@multitable @columnfractions .15 .70 4303@item @var{X} @tab The type shall be @code{REAL} or 4304@code{COMPLEX}. 4305@end multitable 4306 4307@item @emph{Return value}: 4308The return value is of the same type and kind as @var{X}. The real part 4309of the result is in degrees. If @var{X} is of the type @code{REAL}, 4310the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}. 4311 4312@item @emph{Example}: 4313@smallexample 4314program test_cosd 4315 real :: x = 0.0 4316 x = cosd(x) 4317end program test_cosd 4318@end smallexample 4319 4320@item @emph{Specific names}: 4321@multitable @columnfractions .20 .20 .20 .25 4322@item Name @tab Argument @tab Return type @tab Standard 4323@item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4324@item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4325@item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension 4326@item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4327@item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4328@end multitable 4329 4330@item @emph{See also}: 4331Inverse function: @gol 4332@ref{ACOSD} @gol 4333Radians function: @gol 4334@ref{COS} 4335@end table 4336 4337 4338 4339@node COSH 4340@section @code{COSH} --- Hyperbolic cosine function 4341@fnindex COSH 4342@fnindex DCOSH 4343@cindex hyperbolic cosine 4344@cindex hyperbolic function, cosine 4345@cindex cosine, hyperbolic 4346 4347@table @asis 4348@item @emph{Description}: 4349@code{COSH(X)} computes the hyperbolic cosine of @var{X}. 4350 4351@item @emph{Standard}: 4352Fortran 77 and later, for a complex argument Fortran 2008 or later 4353 4354@item @emph{Class}: 4355Elemental function 4356 4357@item @emph{Syntax}: 4358@code{X = COSH(X)} 4359 4360@item @emph{Arguments}: 4361@multitable @columnfractions .15 .70 4362@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4363@end multitable 4364 4365@item @emph{Return value}: 4366The return value has same type and kind as @var{X}. If @var{X} is 4367complex, the imaginary part of the result is in radians. If @var{X} 4368is @code{REAL}, the return value has a lower bound of one, 4369@math{\cosh (x) \geq 1}. 4370 4371@item @emph{Example}: 4372@smallexample 4373program test_cosh 4374 real(8) :: x = 1.0_8 4375 x = cosh(x) 4376end program test_cosh 4377@end smallexample 4378 4379@item @emph{Specific names}: 4380@multitable @columnfractions .20 .20 .20 .25 4381@item Name @tab Argument @tab Return type @tab Standard 4382@item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4383@item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4384@end multitable 4385 4386@item @emph{See also}: 4387Inverse function: @gol 4388@ref{ACOSH} 4389@end table 4390 4391 4392 4393@node COTAN 4394@section @code{COTAN} --- Cotangent function 4395@fnindex COTAN 4396@fnindex DCOTAN 4397@cindex trigonometric function, cotangent 4398@cindex cotangent 4399 4400@table @asis 4401@item @emph{Description}: 4402@code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)} 4403divided by @code{SIN(x)}, or @code{1 / TAN(x)}. 4404 4405This function is for compatibility only and should be avoided in favor of 4406standard constructs wherever possible. 4407 4408@item @emph{Standard}: 4409GNU extension, enabled with @option{-fdec-math}. 4410 4411@item @emph{Class}: 4412Elemental function 4413 4414@item @emph{Syntax}: 4415@code{RESULT = COTAN(X)} 4416 4417@item @emph{Arguments}: 4418@multitable @columnfractions .15 .70 4419@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4420@end multitable 4421 4422@item @emph{Return value}: 4423The return value has same type and kind as @var{X}, and its value is in radians. 4424 4425@item @emph{Example}: 4426@smallexample 4427program test_cotan 4428 real(8) :: x = 0.165_8 4429 x = cotan(x) 4430end program test_cotan 4431@end smallexample 4432 4433@item @emph{Specific names}: 4434@multitable @columnfractions .20 .20 .20 .25 4435@item Name @tab Argument @tab Return type @tab Standard 4436@item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4437@item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4438@end multitable 4439 4440@item @emph{See also}: 4441Converse function: @gol 4442@ref{TAN} @gol 4443Degrees function: @gol 4444@ref{COTAND} 4445@end table 4446 4447 4448 4449@node COTAND 4450@section @code{COTAND} --- Cotangent function, degrees 4451@fnindex COTAND 4452@fnindex DCOTAND 4453@cindex trigonometric function, cotangent, degrees 4454@cindex cotangent, degrees 4455 4456@table @asis 4457@item @emph{Description}: 4458@code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to 4459@code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}. 4460 4461@item @emph{Standard}: 4462GNU extension, enabled with @option{-fdec-math}. 4463 4464This function is for compatibility only and should be avoided in favor of 4465standard constructs wherever possible. 4466 4467@item @emph{Class}: 4468Elemental function 4469 4470@item @emph{Syntax}: 4471@code{RESULT = COTAND(X)} 4472 4473@item @emph{Arguments}: 4474@multitable @columnfractions .15 .70 4475@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4476@end multitable 4477 4478@item @emph{Return value}: 4479The return value has same type and kind as @var{X}, and its value is in degrees. 4480 4481@item @emph{Example}: 4482@smallexample 4483program test_cotand 4484 real(8) :: x = 0.165_8 4485 x = cotand(x) 4486end program test_cotand 4487@end smallexample 4488 4489@item @emph{Specific names}: 4490@multitable @columnfractions .20 .20 .20 .25 4491@item Name @tab Argument @tab Return type @tab Standard 4492@item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4493@item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4494@end multitable 4495 4496@item @emph{See also}: 4497Converse function: @gol 4498@ref{TAND} @gol 4499Radians function: @gol 4500@ref{COTAN} 4501@end table 4502 4503 4504 4505@node COUNT 4506@section @code{COUNT} --- Count function 4507@fnindex COUNT 4508@cindex array, conditionally count elements 4509@cindex array, element counting 4510@cindex array, number of elements 4511 4512@table @asis 4513@item @emph{Description}: 4514 4515Counts the number of @code{.TRUE.} elements in a logical @var{MASK}, 4516or, if the @var{DIM} argument is supplied, counts the number of 4517elements along each row of the array in the @var{DIM} direction. 4518If the array has zero size, or all of the elements of @var{MASK} are 4519@code{.FALSE.}, then the result is @code{0}. 4520 4521@item @emph{Standard}: 4522Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 4523 4524@item @emph{Class}: 4525Transformational function 4526 4527@item @emph{Syntax}: 4528@code{RESULT = COUNT(MASK [, DIM, KIND])} 4529 4530@item @emph{Arguments}: 4531@multitable @columnfractions .15 .70 4532@item @var{MASK} @tab The type shall be @code{LOGICAL}. 4533@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}. 4534@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 4535expression indicating the kind parameter of the result. 4536@end multitable 4537 4538@item @emph{Return value}: 4539The return value is of type @code{INTEGER} and of kind @var{KIND}. If 4540@var{KIND} is absent, the return value is of default integer kind. 4541If @var{DIM} is present, the result is an array with a rank one less 4542than the rank of @var{ARRAY}, and a size corresponding to the shape 4543of @var{ARRAY} with the @var{DIM} dimension removed. 4544 4545@item @emph{Example}: 4546@smallexample 4547program test_count 4548 integer, dimension(2,3) :: a, b 4549 logical, dimension(2,3) :: mask 4550 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) 4551 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /)) 4552 print '(3i3)', a(1,:) 4553 print '(3i3)', a(2,:) 4554 print * 4555 print '(3i3)', b(1,:) 4556 print '(3i3)', b(2,:) 4557 print * 4558 mask = a.ne.b 4559 print '(3l3)', mask(1,:) 4560 print '(3l3)', mask(2,:) 4561 print * 4562 print '(3i3)', count(mask) 4563 print * 4564 print '(3i3)', count(mask, 1) 4565 print * 4566 print '(3i3)', count(mask, 2) 4567end program test_count 4568@end smallexample 4569@end table 4570 4571 4572 4573@node CPU_TIME 4574@section @code{CPU_TIME} --- CPU elapsed time in seconds 4575@fnindex CPU_TIME 4576@cindex time, elapsed 4577 4578@table @asis 4579@item @emph{Description}: 4580Returns a @code{REAL} value representing the elapsed CPU time in 4581seconds. This is useful for testing segments of code to determine 4582execution time. 4583 4584If a time source is available, time will be reported with microsecond 4585resolution. If no time source is available, @var{TIME} is set to 4586@code{-1.0}. 4587 4588Note that @var{TIME} may contain a, system dependent, arbitrary offset 4589and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute 4590value is meaningless, only differences between subsequent calls to 4591this subroutine, as shown in the example below, should be used. 4592 4593 4594@item @emph{Standard}: 4595Fortran 95 and later 4596 4597@item @emph{Class}: 4598Subroutine 4599 4600@item @emph{Syntax}: 4601@code{CALL CPU_TIME(TIME)} 4602 4603@item @emph{Arguments}: 4604@multitable @columnfractions .15 .70 4605@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}. 4606@end multitable 4607 4608@item @emph{Return value}: 4609None 4610 4611@item @emph{Example}: 4612@smallexample 4613program test_cpu_time 4614 real :: start, finish 4615 call cpu_time(start) 4616 ! put code to test here 4617 call cpu_time(finish) 4618 print '("Time = ",f6.3," seconds.")',finish-start 4619end program test_cpu_time 4620@end smallexample 4621 4622@item @emph{See also}: 4623@ref{SYSTEM_CLOCK}, @gol 4624@ref{DATE_AND_TIME} 4625@end table 4626 4627 4628 4629@node CSHIFT 4630@section @code{CSHIFT} --- Circular shift elements of an array 4631@fnindex CSHIFT 4632@cindex array, shift circularly 4633@cindex array, permutation 4634@cindex array, rotate 4635 4636@table @asis 4637@item @emph{Description}: 4638@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of 4639@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is 4640taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the 4641range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. 4642If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted 4643by @var{SHIFT} places. If rank is greater than one, then all complete rank one 4644sections of @var{ARRAY} along the given dimension are shifted. Elements 4645shifted out one end of each rank one section are shifted back in the other end. 4646 4647@item @emph{Standard}: 4648Fortran 90 and later 4649 4650@item @emph{Class}: 4651Transformational function 4652 4653@item @emph{Syntax}: 4654@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])} 4655 4656@item @emph{Arguments}: 4657@multitable @columnfractions .15 .70 4658@item @var{ARRAY} @tab Shall be an array of any type. 4659@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 4660@item @var{DIM} @tab The type shall be @code{INTEGER}. 4661@end multitable 4662 4663@item @emph{Return value}: 4664Returns an array of same type and rank as the @var{ARRAY} argument. 4665 4666@item @emph{Example}: 4667@smallexample 4668program test_cshift 4669 integer, dimension(3,3) :: a 4670 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 4671 print '(3i3)', a(1,:) 4672 print '(3i3)', a(2,:) 4673 print '(3i3)', a(3,:) 4674 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2) 4675 print * 4676 print '(3i3)', a(1,:) 4677 print '(3i3)', a(2,:) 4678 print '(3i3)', a(3,:) 4679end program test_cshift 4680@end smallexample 4681@end table 4682 4683 4684 4685@node CTIME 4686@section @code{CTIME} --- Convert a time into a string 4687@fnindex CTIME 4688@cindex time, conversion to string 4689@cindex conversion, to string 4690 4691@table @asis 4692@item @emph{Description}: 4693@code{CTIME} converts a system time value, such as returned by 4694@ref{TIME8}, to a string. The output will be of the form @samp{Sat 4695Aug 19 18:13:14 1995}. 4696 4697This intrinsic is provided in both subroutine and function forms; however, 4698only one form can be used in any given program unit. 4699 4700@item @emph{Standard}: 4701GNU extension 4702 4703@item @emph{Class}: 4704Subroutine, function 4705 4706@item @emph{Syntax}: 4707@multitable @columnfractions .80 4708@item @code{CALL CTIME(TIME, RESULT)}. 4709@item @code{RESULT = CTIME(TIME)}. 4710@end multitable 4711 4712@item @emph{Arguments}: 4713@multitable @columnfractions .15 .70 4714@item @var{TIME} @tab The type shall be of type @code{INTEGER}. 4715@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and 4716of default kind. It is an @code{INTENT(OUT)} argument. If the length 4717of this variable is too short for the time and date string to fit 4718completely, it will be blank on procedure return. 4719@end multitable 4720 4721@item @emph{Return value}: 4722The converted date and time as a string. 4723 4724@item @emph{Example}: 4725@smallexample 4726program test_ctime 4727 integer(8) :: i 4728 character(len=30) :: date 4729 i = time8() 4730 4731 ! Do something, main part of the program 4732 4733 call ctime(i,date) 4734 print *, 'Program was started on ', date 4735end program test_ctime 4736@end smallexample 4737 4738@item @emph{See Also}: 4739@ref{DATE_AND_TIME}, @gol 4740@ref{GMTIME}, @gol 4741@ref{LTIME}, @gol 4742@ref{TIME}, @gol 4743@ref{TIME8} 4744@end table 4745 4746 4747 4748@node DATE_AND_TIME 4749@section @code{DATE_AND_TIME} --- Date and time subroutine 4750@fnindex DATE_AND_TIME 4751@cindex date, current 4752@cindex current date 4753@cindex time, current 4754@cindex current time 4755 4756@table @asis 4757@item @emph{Description}: 4758@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and 4759time information from the real-time system clock. @var{DATE} is 4760@code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and 4761has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, 4762representing the difference with respect to Coordinated Universal Time (UTC). 4763Unavailable time and date parameters return blanks. 4764 4765@var{VALUES} is @code{INTENT(OUT)} and provides the following: 4766 4767@multitable @columnfractions .15 .70 4768@item @code{VALUE(1)}: @tab The year 4769@item @code{VALUE(2)}: @tab The month 4770@item @code{VALUE(3)}: @tab The day of the month 4771@item @code{VALUE(4)}: @tab Time difference with UTC in minutes 4772@item @code{VALUE(5)}: @tab The hour of the day 4773@item @code{VALUE(6)}: @tab The minutes of the hour 4774@item @code{VALUE(7)}: @tab The seconds of the minute 4775@item @code{VALUE(8)}: @tab The milliseconds of the second 4776@end multitable 4777 4778@item @emph{Standard}: 4779Fortran 90 and later 4780 4781@item @emph{Class}: 4782Subroutine 4783 4784@item @emph{Syntax}: 4785@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])} 4786 4787@item @emph{Arguments}: 4788@multitable @columnfractions .15 .70 4789@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)} 4790or larger, and of default kind. 4791@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)} 4792or larger, and of default kind. 4793@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)} 4794or larger, and of default kind. 4795@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}. 4796@end multitable 4797 4798@item @emph{Return value}: 4799None 4800 4801@item @emph{Example}: 4802@smallexample 4803program test_time_and_date 4804 character(8) :: date 4805 character(10) :: time 4806 character(5) :: zone 4807 integer,dimension(8) :: values 4808 ! using keyword arguments 4809 call date_and_time(date,time,zone,values) 4810 call date_and_time(DATE=date,ZONE=zone) 4811 call date_and_time(TIME=time) 4812 call date_and_time(VALUES=values) 4813 print '(a,2x,a,2x,a)', date, time, zone 4814 print '(8i5)', values 4815end program test_time_and_date 4816@end smallexample 4817 4818@item @emph{See also}: 4819@ref{CPU_TIME}, @gol 4820@ref{SYSTEM_CLOCK} 4821@end table 4822 4823 4824 4825@node DBLE 4826@section @code{DBLE} --- Double conversion function 4827@fnindex DBLE 4828@cindex conversion, to real 4829 4830@table @asis 4831@item @emph{Description}: 4832@code{DBLE(A)} Converts @var{A} to double precision real type. 4833 4834@item @emph{Standard}: 4835Fortran 77 and later 4836 4837@item @emph{Class}: 4838Elemental function 4839 4840@item @emph{Syntax}: 4841@code{RESULT = DBLE(A)} 4842 4843@item @emph{Arguments}: 4844@multitable @columnfractions .15 .70 4845@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL}, 4846or @code{COMPLEX}. 4847@end multitable 4848 4849@item @emph{Return value}: 4850The return value is of type double precision real. 4851 4852@item @emph{Example}: 4853@smallexample 4854program test_dble 4855 real :: x = 2.18 4856 integer :: i = 5 4857 complex :: z = (2.3,1.14) 4858 print *, dble(x), dble(i), dble(z) 4859end program test_dble 4860@end smallexample 4861 4862@item @emph{See also}: 4863@ref{REAL} 4864@end table 4865 4866 4867 4868@node DCMPLX 4869@section @code{DCMPLX} --- Double complex conversion function 4870@fnindex DCMPLX 4871@cindex complex numbers, conversion to 4872@cindex conversion, to complex 4873 4874@table @asis 4875@item @emph{Description}: 4876@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is 4877converted to the real component. If @var{Y} is present it is converted to the 4878imaginary component. If @var{Y} is not present then the imaginary component is 4879set to 0.0. If @var{X} is complex then @var{Y} must not be present. 4880 4881@item @emph{Standard}: 4882GNU extension 4883 4884@item @emph{Class}: 4885Elemental function 4886 4887@item @emph{Syntax}: 4888@code{RESULT = DCMPLX(X [, Y])} 4889 4890@item @emph{Arguments}: 4891@multitable @columnfractions .15 .70 4892@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 4893or @code{COMPLEX}. 4894@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be 4895@code{INTEGER} or @code{REAL}. 4896@end multitable 4897 4898@item @emph{Return value}: 4899The return value is of type @code{COMPLEX(8)} 4900 4901@item @emph{Example}: 4902@smallexample 4903program test_dcmplx 4904 integer :: i = 42 4905 real :: x = 3.14 4906 complex :: z 4907 z = cmplx(i, x) 4908 print *, dcmplx(i) 4909 print *, dcmplx(x) 4910 print *, dcmplx(z) 4911 print *, dcmplx(x,i) 4912end program test_dcmplx 4913@end smallexample 4914@end table 4915 4916 4917@node DIGITS 4918@section @code{DIGITS} --- Significant binary digits function 4919@fnindex DIGITS 4920@cindex model representation, significant digits 4921 4922@table @asis 4923@item @emph{Description}: 4924@code{DIGITS(X)} returns the number of significant binary digits of the internal 4925model representation of @var{X}. For example, on a system using a 32-bit 4926floating point representation, a default real number would likely return 24. 4927 4928@item @emph{Standard}: 4929Fortran 90 and later 4930 4931@item @emph{Class}: 4932Inquiry function 4933 4934@item @emph{Syntax}: 4935@code{RESULT = DIGITS(X)} 4936 4937@item @emph{Arguments}: 4938@multitable @columnfractions .15 .70 4939@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4940@end multitable 4941 4942@item @emph{Return value}: 4943The return value is of type @code{INTEGER}. 4944 4945@item @emph{Example}: 4946@smallexample 4947program test_digits 4948 integer :: i = 12345 4949 real :: x = 3.143 4950 real(8) :: y = 2.33 4951 print *, digits(i) 4952 print *, digits(x) 4953 print *, digits(y) 4954end program test_digits 4955@end smallexample 4956@end table 4957 4958 4959 4960@node DIM 4961@section @code{DIM} --- Positive difference 4962@fnindex DIM 4963@fnindex IDIM 4964@fnindex DDIM 4965@cindex positive difference 4966 4967@table @asis 4968@item @emph{Description}: 4969@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive; 4970otherwise returns zero. 4971 4972@item @emph{Standard}: 4973Fortran 77 and later 4974 4975@item @emph{Class}: 4976Elemental function 4977 4978@item @emph{Syntax}: 4979@code{RESULT = DIM(X, Y)} 4980 4981@item @emph{Arguments}: 4982@multitable @columnfractions .15 .70 4983@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL} 4984@item @var{Y} @tab The type shall be the same type and kind as @var{X}. (As 4985a GNU extension, arguments of different kinds are permitted.) 4986@end multitable 4987 4988@item @emph{Return value}: 4989The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU 4990extension, kind is the largest kind of the actual arguments.) 4991 4992@item @emph{Example}: 4993@smallexample 4994program test_dim 4995 integer :: i 4996 real(8) :: x 4997 i = dim(4, 15) 4998 x = dim(4.345_8, 2.111_8) 4999 print *, i 5000 print *, x 5001end program test_dim 5002@end smallexample 5003 5004@item @emph{Specific names}: 5005@multitable @columnfractions .20 .20 .20 .25 5006@item Name @tab Argument @tab Return type @tab Standard 5007@item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 5008@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later 5009@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 5010@end multitable 5011@end table 5012 5013 5014 5015@node DOT_PRODUCT 5016@section @code{DOT_PRODUCT} --- Dot product function 5017@fnindex DOT_PRODUCT 5018@cindex dot product 5019@cindex vector product 5020@cindex product, vector 5021 5022@table @asis 5023@item @emph{Description}: 5024@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication 5025of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be 5026either numeric or logical and must be arrays of rank one and of equal size. If 5027the vectors are @code{INTEGER} or @code{REAL}, the result is 5028@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result 5029is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL}, 5030the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}. 5031 5032@item @emph{Standard}: 5033Fortran 90 and later 5034 5035@item @emph{Class}: 5036Transformational function 5037 5038@item @emph{Syntax}: 5039@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)} 5040 5041@item @emph{Arguments}: 5042@multitable @columnfractions .15 .70 5043@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1. 5044@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. 5045@end multitable 5046 5047@item @emph{Return value}: 5048If the arguments are numeric, the return value is a scalar of numeric type, 5049@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are 5050@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}. 5051 5052@item @emph{Example}: 5053@smallexample 5054program test_dot_prod 5055 integer, dimension(3) :: a, b 5056 a = (/ 1, 2, 3 /) 5057 b = (/ 4, 5, 6 /) 5058 print '(3i3)', a 5059 print * 5060 print '(3i3)', b 5061 print * 5062 print *, dot_product(a,b) 5063end program test_dot_prod 5064@end smallexample 5065@end table 5066 5067 5068 5069@node DPROD 5070@section @code{DPROD} --- Double product function 5071@fnindex DPROD 5072@cindex product, double-precision 5073 5074@table @asis 5075@item @emph{Description}: 5076@code{DPROD(X,Y)} returns the product @code{X*Y}. 5077 5078@item @emph{Standard}: 5079Fortran 77 and later 5080 5081@item @emph{Class}: 5082Elemental function 5083 5084@item @emph{Syntax}: 5085@code{RESULT = DPROD(X, Y)} 5086 5087@item @emph{Arguments}: 5088@multitable @columnfractions .15 .70 5089@item @var{X} @tab The type shall be @code{REAL}. 5090@item @var{Y} @tab The type shall be @code{REAL}. 5091@end multitable 5092 5093@item @emph{Return value}: 5094The return value is of type @code{REAL(8)}. 5095 5096@item @emph{Example}: 5097@smallexample 5098program test_dprod 5099 real :: x = 5.2 5100 real :: y = 2.3 5101 real(8) :: d 5102 d = dprod(x,y) 5103 print *, d 5104end program test_dprod 5105@end smallexample 5106 5107@item @emph{Specific names}: 5108@multitable @columnfractions .20 .20 .20 .25 5109@item Name @tab Argument @tab Return type @tab Standard 5110@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 5111@end multitable 5112 5113@end table 5114 5115 5116@node DREAL 5117@section @code{DREAL} --- Double real part function 5118@fnindex DREAL 5119@cindex complex numbers, real part 5120 5121@table @asis 5122@item @emph{Description}: 5123@code{DREAL(Z)} returns the real part of complex variable @var{Z}. 5124 5125@item @emph{Standard}: 5126GNU extension 5127 5128@item @emph{Class}: 5129Elemental function 5130 5131@item @emph{Syntax}: 5132@code{RESULT = DREAL(A)} 5133 5134@item @emph{Arguments}: 5135@multitable @columnfractions .15 .70 5136@item @var{A} @tab The type shall be @code{COMPLEX(8)}. 5137@end multitable 5138 5139@item @emph{Return value}: 5140The return value is of type @code{REAL(8)}. 5141 5142@item @emph{Example}: 5143@smallexample 5144program test_dreal 5145 complex(8) :: z = (1.3_8,7.2_8) 5146 print *, dreal(z) 5147end program test_dreal 5148@end smallexample 5149 5150@item @emph{See also}: 5151@ref{AIMAG} 5152 5153@end table 5154 5155 5156 5157@node DSHIFTL 5158@section @code{DSHIFTL} --- Combined left shift 5159@fnindex DSHIFTL 5160@cindex left shift, combined 5161@cindex shift, left 5162 5163@table @asis 5164@item @emph{Description}: 5165@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5166rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT} 5167bits of @var{J}, and the remaining bits are the rightmost bits of 5168@var{I}. 5169 5170@item @emph{Standard}: 5171Fortran 2008 and later 5172 5173@item @emph{Class}: 5174Elemental function 5175 5176@item @emph{Syntax}: 5177@code{RESULT = DSHIFTL(I, J, SHIFT)} 5178 5179@item @emph{Arguments}: 5180@multitable @columnfractions .15 .70 5181@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5182@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5183If both @var{I} and @var{J} have integer type, then they shall have 5184the same kind type parameter. @var{I} and @var{J} shall not both be 5185BOZ constants. 5186@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5187be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5188shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5189@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5190@end multitable 5191 5192@item @emph{Return value}: 5193If either @var{I} or @var{J} is a BOZ constant, it is first converted 5194as if by the intrinsic function @code{INT} to an integer type with the 5195kind type parameter of the other. 5196 5197@item @emph{See also}: 5198@ref{DSHIFTR} 5199@end table 5200 5201 5202@node DSHIFTR 5203@section @code{DSHIFTR} --- Combined right shift 5204@fnindex DSHIFTR 5205@cindex right shift, combined 5206@cindex shift, right 5207 5208@table @asis 5209@item @emph{Description}: 5210@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5211leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT} 5212bits of @var{I}, and the remaining bits are the leftmost bits of 5213@var{J}. 5214 5215@item @emph{Standard}: 5216Fortran 2008 and later 5217 5218@item @emph{Class}: 5219Elemental function 5220 5221@item @emph{Syntax}: 5222@code{RESULT = DSHIFTR(I, J, SHIFT)} 5223 5224@item @emph{Arguments}: 5225@multitable @columnfractions .15 .70 5226@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5227@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5228If both @var{I} and @var{J} have integer type, then they shall have 5229the same kind type parameter. @var{I} and @var{J} shall not both be 5230BOZ constants. 5231@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5232be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5233shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5234@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5235@end multitable 5236 5237@item @emph{Return value}: 5238If either @var{I} or @var{J} is a BOZ constant, it is first converted 5239as if by the intrinsic function @code{INT} to an integer type with the 5240kind type parameter of the other. 5241 5242@item @emph{See also}: 5243@ref{DSHIFTL} 5244@end table 5245 5246 5247@node DTIME 5248@section @code{DTIME} --- Execution time subroutine (or function) 5249@fnindex DTIME 5250@cindex time, elapsed 5251@cindex elapsed time 5252 5253@table @asis 5254@item @emph{Description}: 5255@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime 5256since the start of the process's execution in @var{TIME}. @var{VALUES} 5257returns the user and system components of this time in @code{VALUES(1)} and 5258@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + 5259VALUES(2)}. 5260 5261Subsequent invocations of @code{DTIME} return values accumulated since the 5262previous invocation. 5263 5264On some systems, the underlying timings are represented using types with 5265sufficiently small limits that overflows (wrap around) are possible, such as 526632-bit types. Therefore, the values returned by this intrinsic might be, or 5267become, negative, or numerically less than previous values, during a single 5268run of the compiled program. 5269 5270Please note, that this implementation is thread safe if used within OpenMP 5271directives, i.e., its state will be consistent while called from multiple 5272threads. However, if @code{DTIME} is called from multiple threads, the result 5273is still the time since the last invocation. This may not give the intended 5274results. If possible, use @code{CPU_TIME} instead. 5275 5276This intrinsic is provided in both subroutine and function forms; however, 5277only one form can be used in any given program unit. 5278 5279@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5280 5281@multitable @columnfractions .15 .70 5282@item @code{VALUES(1)}: @tab User time in seconds. 5283@item @code{VALUES(2)}: @tab System time in seconds. 5284@item @code{TIME}: @tab Run time since start in seconds. 5285@end multitable 5286 5287@item @emph{Standard}: 5288GNU extension 5289 5290@item @emph{Class}: 5291Subroutine, function 5292 5293@item @emph{Syntax}: 5294@multitable @columnfractions .80 5295@item @code{CALL DTIME(VALUES, TIME)}. 5296@item @code{TIME = DTIME(VALUES)}, (not recommended). 5297@end multitable 5298 5299@item @emph{Arguments}: 5300@multitable @columnfractions .15 .70 5301@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5302@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5303@end multitable 5304 5305@item @emph{Return value}: 5306Elapsed time in seconds since the last invocation or since the start of program 5307execution if not called before. 5308 5309@item @emph{Example}: 5310@smallexample 5311program test_dtime 5312 integer(8) :: i, j 5313 real, dimension(2) :: tarray 5314 real :: result 5315 call dtime(tarray, result) 5316 print *, result 5317 print *, tarray(1) 5318 print *, tarray(2) 5319 do i=1,100000000 ! Just a delay 5320 j = i * i - i 5321 end do 5322 call dtime(tarray, result) 5323 print *, result 5324 print *, tarray(1) 5325 print *, tarray(2) 5326end program test_dtime 5327@end smallexample 5328 5329@item @emph{See also}: 5330@ref{CPU_TIME} 5331 5332@end table 5333 5334 5335 5336@node EOSHIFT 5337@section @code{EOSHIFT} --- End-off shift elements of an array 5338@fnindex EOSHIFT 5339@cindex array, shift 5340 5341@table @asis 5342@item @emph{Description}: 5343@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on 5344elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is 5345omitted it is taken to be @code{1}. @var{DIM} is a scalar of type 5346@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the 5347rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of 5348@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, 5349then all complete rank one sections of @var{ARRAY} along the given dimension are 5350shifted. Elements shifted out one end of each rank one section are dropped. If 5351@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY} 5352is copied back in the other end. If @var{BOUNDARY} is not present then the 5353following are copied in depending on the type of @var{ARRAY}. 5354 5355@multitable @columnfractions .15 .80 5356@item @emph{Array Type} @tab @emph{Boundary Value} 5357@item Numeric @tab 0 of the type and kind of @var{ARRAY}. 5358@item Logical @tab @code{.FALSE.}. 5359@item Character(@var{len}) @tab @var{len} blanks. 5360@end multitable 5361 5362@item @emph{Standard}: 5363Fortran 90 and later 5364 5365@item @emph{Class}: 5366Transformational function 5367 5368@item @emph{Syntax}: 5369@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])} 5370 5371@item @emph{Arguments}: 5372@multitable @columnfractions .15 .70 5373@item @var{ARRAY} @tab May be any type, not scalar. 5374@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 5375@item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 5376@item @var{DIM} @tab The type shall be @code{INTEGER}. 5377@end multitable 5378 5379@item @emph{Return value}: 5380Returns an array of same type and rank as the @var{ARRAY} argument. 5381 5382@item @emph{Example}: 5383@smallexample 5384program test_eoshift 5385 integer, dimension(3,3) :: a 5386 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 5387 print '(3i3)', a(1,:) 5388 print '(3i3)', a(2,:) 5389 print '(3i3)', a(3,:) 5390 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) 5391 print * 5392 print '(3i3)', a(1,:) 5393 print '(3i3)', a(2,:) 5394 print '(3i3)', a(3,:) 5395end program test_eoshift 5396@end smallexample 5397@end table 5398 5399 5400 5401@node EPSILON 5402@section @code{EPSILON} --- Epsilon function 5403@fnindex EPSILON 5404@cindex model representation, epsilon 5405 5406@table @asis 5407@item @emph{Description}: 5408@code{EPSILON(X)} returns the smallest number @var{E} of the same kind 5409as @var{X} such that @math{1 + E > 1}. 5410 5411@item @emph{Standard}: 5412Fortran 90 and later 5413 5414@item @emph{Class}: 5415Inquiry function 5416 5417@item @emph{Syntax}: 5418@code{RESULT = EPSILON(X)} 5419 5420@item @emph{Arguments}: 5421@multitable @columnfractions .15 .70 5422@item @var{X} @tab The type shall be @code{REAL}. 5423@end multitable 5424 5425@item @emph{Return value}: 5426The return value is of same type as the argument. 5427 5428@item @emph{Example}: 5429@smallexample 5430program test_epsilon 5431 real :: x = 3.143 5432 real(8) :: y = 2.33 5433 print *, EPSILON(x) 5434 print *, EPSILON(y) 5435end program test_epsilon 5436@end smallexample 5437@end table 5438 5439 5440 5441@node ERF 5442@section @code{ERF} --- Error function 5443@fnindex ERF 5444@cindex error function 5445 5446@table @asis 5447@item @emph{Description}: 5448@code{ERF(X)} computes the error function of @var{X}. 5449 5450@item @emph{Standard}: 5451Fortran 2008 and later 5452 5453@item @emph{Class}: 5454Elemental function 5455 5456@item @emph{Syntax}: 5457@code{RESULT = ERF(X)} 5458 5459@item @emph{Arguments}: 5460@multitable @columnfractions .15 .70 5461@item @var{X} @tab The type shall be @code{REAL}. 5462@end multitable 5463 5464@item @emph{Return value}: 5465The return value is of type @code{REAL}, of the same kind as 5466@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }. 5467 5468@item @emph{Example}: 5469@smallexample 5470program test_erf 5471 real(8) :: x = 0.17_8 5472 x = erf(x) 5473end program test_erf 5474@end smallexample 5475 5476@item @emph{Specific names}: 5477@multitable @columnfractions .20 .20 .20 .25 5478@item Name @tab Argument @tab Return type @tab Standard 5479@item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5480@end multitable 5481@end table 5482 5483 5484 5485@node ERFC 5486@section @code{ERFC} --- Error function 5487@fnindex ERFC 5488@cindex error function, complementary 5489 5490@table @asis 5491@item @emph{Description}: 5492@code{ERFC(X)} computes the complementary error function of @var{X}. 5493 5494@item @emph{Standard}: 5495Fortran 2008 and later 5496 5497@item @emph{Class}: 5498Elemental function 5499 5500@item @emph{Syntax}: 5501@code{RESULT = ERFC(X)} 5502 5503@item @emph{Arguments}: 5504@multitable @columnfractions .15 .70 5505@item @var{X} @tab The type shall be @code{REAL}. 5506@end multitable 5507 5508@item @emph{Return value}: 5509The return value is of type @code{REAL} and of the same kind as @var{X}. 5510It lies in the range @math{ 0 \leq erfc (x) \leq 2 }. 5511 5512@item @emph{Example}: 5513@smallexample 5514program test_erfc 5515 real(8) :: x = 0.17_8 5516 x = erfc(x) 5517end program test_erfc 5518@end smallexample 5519 5520@item @emph{Specific names}: 5521@multitable @columnfractions .20 .20 .20 .25 5522@item Name @tab Argument @tab Return type @tab Standard 5523@item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5524@end multitable 5525@end table 5526 5527 5528 5529@node ERFC_SCALED 5530@section @code{ERFC_SCALED} --- Error function 5531@fnindex ERFC_SCALED 5532@cindex error function, complementary, exponentially-scaled 5533 5534@table @asis 5535@item @emph{Description}: 5536@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary 5537error function of @var{X}. 5538 5539@item @emph{Standard}: 5540Fortran 2008 and later 5541 5542@item @emph{Class}: 5543Elemental function 5544 5545@item @emph{Syntax}: 5546@code{RESULT = ERFC_SCALED(X)} 5547 5548@item @emph{Arguments}: 5549@multitable @columnfractions .15 .70 5550@item @var{X} @tab The type shall be @code{REAL}. 5551@end multitable 5552 5553@item @emph{Return value}: 5554The return value is of type @code{REAL} and of the same kind as @var{X}. 5555 5556@item @emph{Example}: 5557@smallexample 5558program test_erfc_scaled 5559 real(8) :: x = 0.17_8 5560 x = erfc_scaled(x) 5561end program test_erfc_scaled 5562@end smallexample 5563@end table 5564 5565 5566 5567@node ETIME 5568@section @code{ETIME} --- Execution time subroutine (or function) 5569@fnindex ETIME 5570@cindex time, elapsed 5571 5572@table @asis 5573@item @emph{Description}: 5574@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime 5575since the start of the process's execution in @var{TIME}. @var{VALUES} 5576returns the user and system components of this time in @code{VALUES(1)} and 5577@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. 5578 5579On some systems, the underlying timings are represented using types with 5580sufficiently small limits that overflows (wrap around) are possible, such as 558132-bit types. Therefore, the values returned by this intrinsic might be, or 5582become, negative, or numerically less than previous values, during a single 5583run of the compiled program. 5584 5585This intrinsic is provided in both subroutine and function forms; however, 5586only one form can be used in any given program unit. 5587 5588@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5589 5590@multitable @columnfractions .15 .70 5591@item @code{VALUES(1)}: @tab User time in seconds. 5592@item @code{VALUES(2)}: @tab System time in seconds. 5593@item @code{TIME}: @tab Run time since start in seconds. 5594@end multitable 5595 5596@item @emph{Standard}: 5597GNU extension 5598 5599@item @emph{Class}: 5600Subroutine, function 5601 5602@item @emph{Syntax}: 5603@multitable @columnfractions .80 5604@item @code{CALL ETIME(VALUES, TIME)}. 5605@item @code{TIME = ETIME(VALUES)}, (not recommended). 5606@end multitable 5607 5608@item @emph{Arguments}: 5609@multitable @columnfractions .15 .70 5610@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5611@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5612@end multitable 5613 5614@item @emph{Return value}: 5615Elapsed time in seconds since the start of program execution. 5616 5617@item @emph{Example}: 5618@smallexample 5619program test_etime 5620 integer(8) :: i, j 5621 real, dimension(2) :: tarray 5622 real :: result 5623 call ETIME(tarray, result) 5624 print *, result 5625 print *, tarray(1) 5626 print *, tarray(2) 5627 do i=1,100000000 ! Just a delay 5628 j = i * i - i 5629 end do 5630 call ETIME(tarray, result) 5631 print *, result 5632 print *, tarray(1) 5633 print *, tarray(2) 5634end program test_etime 5635@end smallexample 5636 5637@item @emph{See also}: 5638@ref{CPU_TIME} 5639 5640@end table 5641 5642 5643 5644@node EVENT_QUERY 5645@section @code{EVENT_QUERY} --- Query whether a coarray event has occurred 5646@fnindex EVENT_QUERY 5647@cindex Events, EVENT_QUERY 5648 5649@table @asis 5650@item @emph{Description}: 5651@code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been 5652posted to the @var{EVENT} variable and not yet been removed by calling 5653@code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful, 5654it is assigned the value 0. If it is present and the invocation has failed, 5655it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}. 5656 5657@item @emph{Standard}: 5658TS 18508 or later 5659 5660@item @emph{Class}: 5661 subroutine 5662 5663@item @emph{Syntax}: 5664@code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])} 5665 5666@item @emph{Arguments}: 5667@multitable @columnfractions .15 .70 5668@item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE}, 5669defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed. 5670@item @var{COUNT} @tab (intent(out))Scalar integer with at least the 5671precision of default integer. 5672@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 5673@end multitable 5674 5675@item @emph{Example}: 5676@smallexample 5677program atomic 5678 use iso_fortran_env 5679 implicit none 5680 type(event_type) :: event_value_has_been_set[*] 5681 integer :: cnt 5682 if (this_image() == 1) then 5683 call event_query (event_value_has_been_set, cnt) 5684 if (cnt > 0) write(*,*) "Value has been set" 5685 elseif (this_image() == 2) then 5686 event post (event_value_has_been_set[1]) 5687 end if 5688end program atomic 5689@end smallexample 5690 5691@end table 5692 5693 5694 5695@node EXECUTE_COMMAND_LINE 5696@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command 5697@fnindex EXECUTE_COMMAND_LINE 5698@cindex system, system call 5699@cindex command line 5700 5701@table @asis 5702@item @emph{Description}: 5703@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or 5704asynchronously. 5705 5706The @code{COMMAND} argument is passed to the shell and executed (The 5707shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.). 5708If @code{WAIT} is present and has the value false, the execution of 5709the command is asynchronous if the system supports it; otherwise, the 5710command is executed synchronously using the C library's @code{system} 5711call. 5712 5713The three last arguments allow the user to get status information. After 5714synchronous execution, @code{EXITSTAT} contains the integer exit code of 5715the command, as returned by @code{system}. @code{CMDSTAT} is set to zero 5716if the command line was executed (whatever its exit status was). 5717@code{CMDMSG} is assigned an error message if an error has occurred. 5718 5719Note that the @code{system} function need not be thread-safe. It is 5720the responsibility of the user to ensure that @code{system} is not 5721called concurrently. 5722 5723For asynchronous execution on supported targets, the POSIX 5724@code{posix_spawn} or @code{fork} functions are used. Also, a signal 5725handler for the @code{SIGCHLD} signal is installed. 5726 5727@item @emph{Standard}: 5728Fortran 2008 and later 5729 5730@item @emph{Class}: 5731Subroutine 5732 5733@item @emph{Syntax}: 5734@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])} 5735 5736@item @emph{Arguments}: 5737@multitable @columnfractions .15 .70 5738@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar. 5739@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar. 5740@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5741default kind. 5742@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5743default kind. 5744@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the 5745default kind. 5746@end multitable 5747 5748@item @emph{Example}: 5749@smallexample 5750program test_exec 5751 integer :: i 5752 5753 call execute_command_line ("external_prog.exe", exitstat=i) 5754 print *, "Exit status of external_prog.exe was ", i 5755 5756 call execute_command_line ("reindex_files.exe", wait=.false.) 5757 print *, "Now reindexing files in the background" 5758 5759end program test_exec 5760@end smallexample 5761 5762 5763@item @emph{Note}: 5764 5765Because this intrinsic is implemented in terms of the @code{system} 5766function call, its behavior with respect to signaling is processor 5767dependent. In particular, on POSIX-compliant systems, the SIGINT and 5768SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As 5769such, if the parent process is terminated, the child process might not be 5770terminated alongside. 5771 5772 5773@item @emph{See also}: 5774@ref{SYSTEM} 5775@end table 5776 5777 5778 5779@node EXIT 5780@section @code{EXIT} --- Exit the program with status. 5781@fnindex EXIT 5782@cindex program termination 5783@cindex terminate program 5784 5785@table @asis 5786@item @emph{Description}: 5787@code{EXIT} causes immediate termination of the program with status. If status 5788is omitted it returns the canonical @emph{success} for the system. All Fortran 5789I/O units are closed. 5790 5791@item @emph{Standard}: 5792GNU extension 5793 5794@item @emph{Class}: 5795Subroutine 5796 5797@item @emph{Syntax}: 5798@code{CALL EXIT([STATUS])} 5799 5800@item @emph{Arguments}: 5801@multitable @columnfractions .15 .70 5802@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind. 5803@end multitable 5804 5805@item @emph{Return value}: 5806@code{STATUS} is passed to the parent process on exit. 5807 5808@item @emph{Example}: 5809@smallexample 5810program test_exit 5811 integer :: STATUS = 0 5812 print *, 'This program is going to exit.' 5813 call EXIT(STATUS) 5814end program test_exit 5815@end smallexample 5816 5817@item @emph{See also}: 5818@ref{ABORT}, @gol 5819@ref{KILL} 5820@end table 5821 5822 5823 5824@node EXP 5825@section @code{EXP} --- Exponential function 5826@fnindex EXP 5827@fnindex DEXP 5828@fnindex CEXP 5829@fnindex ZEXP 5830@fnindex CDEXP 5831@cindex exponential function 5832@cindex logarithm function, inverse 5833 5834@table @asis 5835@item @emph{Description}: 5836@code{EXP(X)} computes the base @math{e} exponential of @var{X}. 5837 5838@item @emph{Standard}: 5839Fortran 77 and later, has overloads that are GNU extensions 5840 5841@item @emph{Class}: 5842Elemental function 5843 5844@item @emph{Syntax}: 5845@code{RESULT = EXP(X)} 5846 5847@item @emph{Arguments}: 5848@multitable @columnfractions .15 .70 5849@item @var{X} @tab The type shall be @code{REAL} or 5850@code{COMPLEX}. 5851@end multitable 5852 5853@item @emph{Return value}: 5854The return value has same type and kind as @var{X}. 5855 5856@item @emph{Example}: 5857@smallexample 5858program test_exp 5859 real :: x = 1.0 5860 x = exp(x) 5861end program test_exp 5862@end smallexample 5863 5864@item @emph{Specific names}: 5865@multitable @columnfractions .20 .20 .20 .25 5866@item Name @tab Argument @tab Return type @tab Standard 5867@item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 5868@item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 5869@item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 5870@item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5871@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5872@end multitable 5873@end table 5874 5875 5876 5877@node EXPONENT 5878@section @code{EXPONENT} --- Exponent function 5879@fnindex EXPONENT 5880@cindex real number, exponent 5881@cindex floating point, exponent 5882 5883@table @asis 5884@item @emph{Description}: 5885@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X} 5886is zero the value returned is zero. 5887 5888@item @emph{Standard}: 5889Fortran 90 and later 5890 5891@item @emph{Class}: 5892Elemental function 5893 5894@item @emph{Syntax}: 5895@code{RESULT = EXPONENT(X)} 5896 5897@item @emph{Arguments}: 5898@multitable @columnfractions .15 .70 5899@item @var{X} @tab The type shall be @code{REAL}. 5900@end multitable 5901 5902@item @emph{Return value}: 5903The return value is of type default @code{INTEGER}. 5904 5905@item @emph{Example}: 5906@smallexample 5907program test_exponent 5908 real :: x = 1.0 5909 integer :: i 5910 i = exponent(x) 5911 print *, i 5912 print *, exponent(0.0) 5913end program test_exponent 5914@end smallexample 5915@end table 5916 5917 5918 5919@node EXTENDS_TYPE_OF 5920@section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension 5921@fnindex EXTENDS_TYPE_OF 5922 5923@table @asis 5924@item @emph{Description}: 5925Query dynamic type for extension. 5926 5927@item @emph{Standard}: 5928Fortran 2003 and later 5929 5930@item @emph{Class}: 5931Inquiry function 5932 5933@item @emph{Syntax}: 5934@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)} 5935 5936@item @emph{Arguments}: 5937@multitable @columnfractions .15 .70 5938@item @var{A} @tab Shall be an object of extensible declared type or 5939unlimited polymorphic. 5940@item @var{MOLD} @tab Shall be an object of extensible declared type or 5941unlimited polymorphic. 5942@end multitable 5943 5944@item @emph{Return value}: 5945The return value is a scalar of type default logical. It is true if and only if 5946the dynamic type of A is an extension type of the dynamic type of MOLD. 5947 5948 5949@item @emph{See also}: 5950@ref{SAME_TYPE_AS} 5951@end table 5952 5953 5954 5955@node FDATE 5956@section @code{FDATE} --- Get the current time as a string 5957@fnindex FDATE 5958@cindex time, current 5959@cindex current time 5960@cindex date, current 5961@cindex current date 5962 5963@table @asis 5964@item @emph{Description}: 5965@code{FDATE(DATE)} returns the current date (using the same format as 5966@ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE, 5967TIME())}. 5968 5969This intrinsic is provided in both subroutine and function forms; however, 5970only one form can be used in any given program unit. 5971 5972@item @emph{Standard}: 5973GNU extension 5974 5975@item @emph{Class}: 5976Subroutine, function 5977 5978@item @emph{Syntax}: 5979@multitable @columnfractions .80 5980@item @code{CALL FDATE(DATE)}. 5981@item @code{DATE = FDATE()}. 5982@end multitable 5983 5984@item @emph{Arguments}: 5985@multitable @columnfractions .15 .70 5986@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the 5987default kind. It is an @code{INTENT(OUT)} argument. If the length of 5988this variable is too short for the date and time string to fit 5989completely, it will be blank on procedure return. 5990@end multitable 5991 5992@item @emph{Return value}: 5993The current date and time as a string. 5994 5995@item @emph{Example}: 5996@smallexample 5997program test_fdate 5998 integer(8) :: i, j 5999 character(len=30) :: date 6000 call fdate(date) 6001 print *, 'Program started on ', date 6002 do i = 1, 100000000 ! Just a delay 6003 j = i * i - i 6004 end do 6005 call fdate(date) 6006 print *, 'Program ended on ', date 6007end program test_fdate 6008@end smallexample 6009 6010@item @emph{See also}: 6011@ref{DATE_AND_TIME}, @gol 6012@ref{CTIME} 6013@end table 6014 6015 6016@node FGET 6017@section @code{FGET} --- Read a single character in stream mode from stdin 6018@fnindex FGET 6019@cindex read character, stream mode 6020@cindex stream mode, read character 6021@cindex file operation, read character 6022 6023@table @asis 6024@item @emph{Description}: 6025Read a single character in stream mode from stdin by bypassing normal 6026formatted output. Stream I/O should not be mixed with normal record-oriented 6027(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6028 6029This intrinsic is provided in both subroutine and function forms; however, 6030only one form can be used in any given program unit. 6031 6032Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6033@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6034Programmers should consider the use of new stream IO feature in new code 6035for future portability. See also @ref{Fortran 2003 status}. 6036 6037@item @emph{Standard}: 6038GNU extension 6039 6040@item @emph{Class}: 6041Subroutine, function 6042 6043@item @emph{Syntax}: 6044@multitable @columnfractions .80 6045@item @code{CALL FGET(C [, STATUS])} 6046@item @code{STATUS = FGET(C)} 6047@end multitable 6048 6049@item @emph{Arguments}: 6050@multitable @columnfractions .15 .70 6051@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6052kind. 6053@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6054Returns 0 on success, -1 on end-of-file, and a system specific positive 6055error code otherwise. 6056@end multitable 6057 6058@item @emph{Example}: 6059@smallexample 6060PROGRAM test_fget 6061 INTEGER, PARAMETER :: strlen = 100 6062 INTEGER :: status, i = 1 6063 CHARACTER(len=strlen) :: str = "" 6064 6065 WRITE (*,*) 'Enter text:' 6066 DO 6067 CALL fget(str(i:i), status) 6068 if (status /= 0 .OR. i > strlen) exit 6069 i = i + 1 6070 END DO 6071 WRITE (*,*) TRIM(str) 6072END PROGRAM 6073@end smallexample 6074 6075@item @emph{See also}: 6076@ref{FGETC}, @gol 6077@ref{FPUT}, @gol 6078@ref{FPUTC} 6079@end table 6080 6081 6082 6083@node FGETC 6084@section @code{FGETC} --- Read a single character in stream mode 6085@fnindex FGETC 6086@cindex read character, stream mode 6087@cindex stream mode, read character 6088@cindex file operation, read character 6089 6090@table @asis 6091@item @emph{Description}: 6092Read a single character in stream mode by bypassing normal formatted output. 6093Stream I/O should not be mixed with normal record-oriented (formatted or 6094unformatted) I/O on the same unit; the results are unpredictable. 6095 6096This intrinsic is provided in both subroutine and function forms; however, 6097only one form can be used in any given program unit. 6098 6099Note that the @code{FGET} intrinsic is provided for backwards compatibility 6100with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6101Programmers should consider the use of new stream IO feature in new code 6102for future portability. See also @ref{Fortran 2003 status}. 6103 6104@item @emph{Standard}: 6105GNU extension 6106 6107@item @emph{Class}: 6108Subroutine, function 6109 6110@item @emph{Syntax}: 6111@multitable @columnfractions .80 6112@item @code{CALL FGETC(UNIT, C [, STATUS])} 6113@item @code{STATUS = FGETC(UNIT, C)} 6114@end multitable 6115 6116@item @emph{Arguments}: 6117@multitable @columnfractions .15 .70 6118@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6119@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6120kind. 6121@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6122Returns 0 on success, -1 on end-of-file and a system specific positive 6123error code otherwise. 6124@end multitable 6125 6126@item @emph{Example}: 6127@smallexample 6128PROGRAM test_fgetc 6129 INTEGER :: fd = 42, status 6130 CHARACTER :: c 6131 6132 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD") 6133 DO 6134 CALL fgetc(fd, c, status) 6135 IF (status /= 0) EXIT 6136 call fput(c) 6137 END DO 6138 CLOSE(UNIT=fd) 6139END PROGRAM 6140@end smallexample 6141 6142@item @emph{See also}: 6143@ref{FGET}, @gol 6144@ref{FPUT}, @gol 6145@ref{FPUTC} 6146@end table 6147 6148@node FINDLOC 6149@section @code{FINDLOC} --- Search an array for a value 6150@fnindex FINDLOC 6151@cindex findloc 6152 6153@table @asis 6154@item @emph{Description}: 6155Determines the location of the element in the array with the value 6156given in the @var{VALUE} argument, or, if the @var{DIM} argument is 6157supplied, determines the locations of the elements equal to the 6158@var{VALUE} argument element along each 6159row of the array in the @var{DIM} direction. If @var{MASK} is 6160present, only the elements for which @var{MASK} is @code{.TRUE.} are 6161considered. If more than one element in the array has the value 6162@var{VALUE}, the location returned is that of the first such element 6163in array element order if the @var{BACK} is not present or if it is 6164@code{.FALSE.}. If @var{BACK} is true, the location returned is that 6165of the last such element. If the array has zero size, or all of the 6166elements of @var{MASK} are @code{.FALSE.}, then the result is an array 6167of zeroes. Similarly, if @var{DIM} is supplied and all of the 6168elements of @var{MASK} along a given row are zero, the result value 6169for that row is zero. 6170 6171@item @emph{Standard}: 6172Fortran 2008 and later. 6173 6174@item @emph{Class}: 6175Transformational function 6176 6177@item @emph{Syntax}: 6178@multitable @columnfractions .80 6179@item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])} 6180@item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])} 6181@end multitable 6182 6183@item @emph{Arguments}: 6184@multitable @columnfractions .15 .70 6185@item @var{ARRAY} @tab Shall be an array of intrinsic type. 6186@item @var{VALUE} @tab A scalar of intrinsic type which is in type 6187conformance with @var{ARRAY}. 6188@item @var{DIM} @tab (Optional) Shall be a scalar of type 6189@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 6190inclusive. It may not be an optional dummy argument. 6191@item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL}, 6192and conformable with @var{ARRAY}. 6193@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6194expression indicating the kind parameter of the result. 6195@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 6196@end multitable 6197 6198@item @emph{Return value}: 6199If @var{DIM} is absent, the result is a rank-one array with a length 6200equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 6201is an array with a rank one less than the rank of @var{ARRAY}, and a 6202size corresponding to the size of @var{ARRAY} with the @var{DIM} 6203dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 6204of one, the result is a scalar. If the optional argument @var{KIND} 6205is present, the result is an integer of kind @var{KIND}, otherwise it 6206is of default kind. 6207 6208@item @emph{See also}: 6209@ref{MAXLOC}, @gol 6210@ref{MINLOC} 6211 6212@end table 6213 6214@node FLOOR 6215@section @code{FLOOR} --- Integer floor function 6216@fnindex FLOOR 6217@cindex floor 6218@cindex rounding, floor 6219 6220@table @asis 6221@item @emph{Description}: 6222@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}. 6223 6224@item @emph{Standard}: 6225Fortran 95 and later 6226 6227@item @emph{Class}: 6228Elemental function 6229 6230@item @emph{Syntax}: 6231@code{RESULT = FLOOR(A [, KIND])} 6232 6233@item @emph{Arguments}: 6234@multitable @columnfractions .15 .70 6235@item @var{A} @tab The type shall be @code{REAL}. 6236@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6237expression indicating the kind parameter of the result. 6238@end multitable 6239 6240@item @emph{Return value}: 6241The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 6242and of default-kind @code{INTEGER} otherwise. 6243 6244@item @emph{Example}: 6245@smallexample 6246program test_floor 6247 real :: x = 63.29 6248 real :: y = -63.59 6249 print *, floor(x) ! returns 63 6250 print *, floor(y) ! returns -64 6251end program test_floor 6252@end smallexample 6253 6254@item @emph{See also}: 6255@ref{CEILING}, @gol 6256@ref{NINT} 6257@end table 6258 6259 6260 6261@node FLUSH 6262@section @code{FLUSH} --- Flush I/O unit(s) 6263@fnindex FLUSH 6264@cindex file operation, flush 6265 6266@table @asis 6267@item @emph{Description}: 6268Flushes Fortran unit(s) currently open for output. Without the optional 6269argument, all units are flushed, otherwise just the unit specified. 6270 6271@item @emph{Standard}: 6272GNU extension 6273 6274@item @emph{Class}: 6275Subroutine 6276 6277@item @emph{Syntax}: 6278@code{CALL FLUSH(UNIT)} 6279 6280@item @emph{Arguments}: 6281@multitable @columnfractions .15 .70 6282@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}. 6283@end multitable 6284 6285@item @emph{Note}: 6286Beginning with the Fortran 2003 standard, there is a @code{FLUSH} 6287statement that should be preferred over the @code{FLUSH} intrinsic. 6288 6289The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement 6290have identical effect: they flush the runtime library's I/O buffer so 6291that the data becomes visible to other processes. This does not guarantee 6292that the data is committed to disk. 6293 6294On POSIX systems, you can request that all data is transferred to the 6295storage device by calling the @code{fsync} function, with the POSIX file 6296descriptor of the I/O unit as argument (retrieved with GNU intrinsic 6297@code{FNUM}). The following example shows how: 6298 6299@smallexample 6300 ! Declare the interface for POSIX fsync function 6301 interface 6302 function fsync (fd) bind(c,name="fsync") 6303 use iso_c_binding, only: c_int 6304 integer(c_int), value :: fd 6305 integer(c_int) :: fsync 6306 end function fsync 6307 end interface 6308 6309 ! Variable declaration 6310 integer :: ret 6311 6312 ! Opening unit 10 6313 open (10,file="foo") 6314 6315 ! ... 6316 ! Perform I/O on unit 10 6317 ! ... 6318 6319 ! Flush and sync 6320 flush(10) 6321 ret = fsync(fnum(10)) 6322 6323 ! Handle possible error 6324 if (ret /= 0) stop "Error calling FSYNC" 6325@end smallexample 6326 6327@end table 6328 6329 6330 6331@node FNUM 6332@section @code{FNUM} --- File number function 6333@fnindex FNUM 6334@cindex file operation, file number 6335 6336@table @asis 6337@item @emph{Description}: 6338@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the 6339open Fortran I/O unit @code{UNIT}. 6340 6341@item @emph{Standard}: 6342GNU extension 6343 6344@item @emph{Class}: 6345Function 6346 6347@item @emph{Syntax}: 6348@code{RESULT = FNUM(UNIT)} 6349 6350@item @emph{Arguments}: 6351@multitable @columnfractions .15 .70 6352@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6353@end multitable 6354 6355@item @emph{Return value}: 6356The return value is of type @code{INTEGER} 6357 6358@item @emph{Example}: 6359@smallexample 6360program test_fnum 6361 integer :: i 6362 open (unit=10, status = "scratch") 6363 i = fnum(10) 6364 print *, i 6365 close (10) 6366end program test_fnum 6367@end smallexample 6368@end table 6369 6370 6371 6372@node FPUT 6373@section @code{FPUT} --- Write a single character in stream mode to stdout 6374@fnindex FPUT 6375@cindex write character, stream mode 6376@cindex stream mode, write character 6377@cindex file operation, write character 6378 6379@table @asis 6380@item @emph{Description}: 6381Write a single character in stream mode to stdout by bypassing normal 6382formatted output. Stream I/O should not be mixed with normal record-oriented 6383(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6384 6385This intrinsic is provided in both subroutine and function forms; however, 6386only one form can be used in any given program unit. 6387 6388Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6389@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6390Programmers should consider the use of new stream IO feature in new code 6391for future portability. See also @ref{Fortran 2003 status}. 6392 6393@item @emph{Standard}: 6394GNU extension 6395 6396@item @emph{Class}: 6397Subroutine, function 6398 6399@item @emph{Syntax}: 6400@multitable @columnfractions .80 6401@item @code{CALL FPUT(C [, STATUS])} 6402@item @code{STATUS = FPUT(C)} 6403@end multitable 6404 6405@item @emph{Arguments}: 6406@multitable @columnfractions .15 .70 6407@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6408kind. 6409@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6410Returns 0 on success, -1 on end-of-file and a system specific positive 6411error code otherwise. 6412@end multitable 6413 6414@item @emph{Example}: 6415@smallexample 6416PROGRAM test_fput 6417 CHARACTER(len=10) :: str = "gfortran" 6418 INTEGER :: i 6419 DO i = 1, len_trim(str) 6420 CALL fput(str(i:i)) 6421 END DO 6422END PROGRAM 6423@end smallexample 6424 6425@item @emph{See also}: 6426@ref{FPUTC}, @gol 6427@ref{FGET}, @gol 6428@ref{FGETC} 6429@end table 6430 6431 6432 6433@node FPUTC 6434@section @code{FPUTC} --- Write a single character in stream mode 6435@fnindex FPUTC 6436@cindex write character, stream mode 6437@cindex stream mode, write character 6438@cindex file operation, write character 6439 6440@table @asis 6441@item @emph{Description}: 6442Write a single character in stream mode by bypassing normal formatted 6443output. Stream I/O should not be mixed with normal record-oriented 6444(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6445 6446This intrinsic is provided in both subroutine and function forms; however, 6447only one form can be used in any given program unit. 6448 6449Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6450@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6451Programmers should consider the use of new stream IO feature in new code 6452for future portability. See also @ref{Fortran 2003 status}. 6453 6454@item @emph{Standard}: 6455GNU extension 6456 6457@item @emph{Class}: 6458Subroutine, function 6459 6460@item @emph{Syntax}: 6461@multitable @columnfractions .80 6462@item @code{CALL FPUTC(UNIT, C [, STATUS])} 6463@item @code{STATUS = FPUTC(UNIT, C)} 6464@end multitable 6465 6466@item @emph{Arguments}: 6467@multitable @columnfractions .15 .70 6468@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6469@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6470kind. 6471@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6472Returns 0 on success, -1 on end-of-file and a system specific positive 6473error code otherwise. 6474@end multitable 6475 6476@item @emph{Example}: 6477@smallexample 6478PROGRAM test_fputc 6479 CHARACTER(len=10) :: str = "gfortran" 6480 INTEGER :: fd = 42, i 6481 6482 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW") 6483 DO i = 1, len_trim(str) 6484 CALL fputc(fd, str(i:i)) 6485 END DO 6486 CLOSE(fd) 6487END PROGRAM 6488@end smallexample 6489 6490@item @emph{See also}: 6491@ref{FPUT}, @gol 6492@ref{FGET}, @gol 6493@ref{FGETC} 6494@end table 6495 6496 6497 6498@node FRACTION 6499@section @code{FRACTION} --- Fractional part of the model representation 6500@fnindex FRACTION 6501@cindex real number, fraction 6502@cindex floating point, fraction 6503 6504@table @asis 6505@item @emph{Description}: 6506@code{FRACTION(X)} returns the fractional part of the model 6507representation of @code{X}. 6508 6509@item @emph{Standard}: 6510Fortran 90 and later 6511 6512@item @emph{Class}: 6513Elemental function 6514 6515@item @emph{Syntax}: 6516@code{Y = FRACTION(X)} 6517 6518@item @emph{Arguments}: 6519@multitable @columnfractions .15 .70 6520@item @var{X} @tab The type of the argument shall be a @code{REAL}. 6521@end multitable 6522 6523@item @emph{Return value}: 6524The return value is of the same type and kind as the argument. 6525The fractional part of the model representation of @code{X} is returned; 6526it is @code{X * RADIX(X)**(-EXPONENT(X))}. 6527 6528@item @emph{Example}: 6529@smallexample 6530program test_fraction 6531 real :: x 6532 x = 178.1387e-4 6533 print *, fraction(x), x * radix(x)**(-exponent(x)) 6534end program test_fraction 6535@end smallexample 6536 6537@end table 6538 6539 6540 6541@node FREE 6542@section @code{FREE} --- Frees memory 6543@fnindex FREE 6544@cindex pointer, cray 6545 6546@table @asis 6547@item @emph{Description}: 6548Frees memory previously allocated by @code{MALLOC}. The @code{FREE} 6549intrinsic is an extension intended to be used with Cray pointers, and is 6550provided in GNU Fortran to allow user to compile legacy code. For 6551new code using Fortran 95 pointers, the memory de-allocation intrinsic is 6552@code{DEALLOCATE}. 6553 6554@item @emph{Standard}: 6555GNU extension 6556 6557@item @emph{Class}: 6558Subroutine 6559 6560@item @emph{Syntax}: 6561@code{CALL FREE(PTR)} 6562 6563@item @emph{Arguments}: 6564@multitable @columnfractions .15 .70 6565@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the 6566location of the memory that should be de-allocated. 6567@end multitable 6568 6569@item @emph{Return value}: 6570None 6571 6572@item @emph{Example}: 6573See @code{MALLOC} for an example. 6574 6575@item @emph{See also}: 6576@ref{MALLOC} 6577@end table 6578 6579 6580 6581@node FSEEK 6582@section @code{FSEEK} --- Low level file positioning subroutine 6583@fnindex FSEEK 6584@cindex file operation, seek 6585@cindex file operation, position 6586 6587@table @asis 6588@item @emph{Description}: 6589Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} 6590is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET}, 6591if set to 1, @var{OFFSET} is taken to be relative to the current position 6592@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}. 6593On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek 6594fails silently. 6595 6596This intrinsic routine is not fully backwards compatible with @command{g77}. 6597In @command{g77}, the @code{FSEEK} takes a statement label instead of a 6598@var{STATUS} variable. If FSEEK is used in old code, change 6599@smallexample 6600 CALL FSEEK(UNIT, OFFSET, WHENCE, *label) 6601@end smallexample 6602to 6603@smallexample 6604 INTEGER :: status 6605 CALL FSEEK(UNIT, OFFSET, WHENCE, status) 6606 IF (status /= 0) GOTO label 6607@end smallexample 6608 6609Please note that GNU Fortran provides the Fortran 2003 Stream facility. 6610Programmers should consider the use of new stream IO feature in new code 6611for future portability. See also @ref{Fortran 2003 status}. 6612 6613@item @emph{Standard}: 6614GNU extension 6615 6616@item @emph{Class}: 6617Subroutine 6618 6619@item @emph{Syntax}: 6620@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])} 6621 6622@item @emph{Arguments}: 6623@multitable @columnfractions .15 .70 6624@item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}. 6625@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}. 6626@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}. 6627Its value shall be either 0, 1 or 2. 6628@item @var{STATUS} @tab (Optional) shall be a scalar of type 6629@code{INTEGER(4)}. 6630@end multitable 6631 6632@item @emph{Example}: 6633@smallexample 6634PROGRAM test_fseek 6635 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2 6636 INTEGER :: fd, offset, ierr 6637 6638 ierr = 0 6639 offset = 5 6640 fd = 10 6641 6642 OPEN(UNIT=fd, FILE="fseek.test") 6643 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET 6644 print *, FTELL(fd), ierr 6645 6646 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end 6647 print *, FTELL(fd), ierr 6648 6649 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning 6650 print *, FTELL(fd), ierr 6651 6652 CLOSE(UNIT=fd) 6653END PROGRAM 6654@end smallexample 6655 6656@item @emph{See also}: 6657@ref{FTELL} 6658@end table 6659 6660 6661 6662@node FSTAT 6663@section @code{FSTAT} --- Get file status 6664@fnindex FSTAT 6665@cindex file system, file status 6666 6667@table @asis 6668@item @emph{Description}: 6669@code{FSTAT} is identical to @ref{STAT}, except that information about an 6670already opened file is obtained. 6671 6672The elements in @code{VALUES} are the same as described by @ref{STAT}. 6673 6674This intrinsic is provided in both subroutine and function forms; however, 6675only one form can be used in any given program unit. 6676 6677@item @emph{Standard}: 6678GNU extension 6679 6680@item @emph{Class}: 6681Subroutine, function 6682 6683@item @emph{Syntax}: 6684@multitable @columnfractions .80 6685@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])} 6686@item @code{STATUS = FSTAT(UNIT, VALUES)} 6687@end multitable 6688 6689@item @emph{Arguments}: 6690@multitable @columnfractions .15 .70 6691@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. 6692@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 6693@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 6694on success and a system specific error code otherwise. 6695@end multitable 6696 6697@item @emph{Example}: 6698See @ref{STAT} for an example. 6699 6700@item @emph{See also}: 6701To stat a link: @gol 6702@ref{LSTAT} @gol 6703To stat a file: @gol 6704@ref{STAT} 6705@end table 6706 6707 6708 6709@node FTELL 6710@section @code{FTELL} --- Current stream position 6711@fnindex FTELL 6712@cindex file operation, position 6713 6714@table @asis 6715@item @emph{Description}: 6716Retrieves the current position within an open file. 6717 6718This intrinsic is provided in both subroutine and function forms; however, 6719only one form can be used in any given program unit. 6720 6721@item @emph{Standard}: 6722GNU extension 6723 6724@item @emph{Class}: 6725Subroutine, function 6726 6727@item @emph{Syntax}: 6728@multitable @columnfractions .80 6729@item @code{CALL FTELL(UNIT, OFFSET)} 6730@item @code{OFFSET = FTELL(UNIT)} 6731@end multitable 6732 6733@item @emph{Arguments}: 6734@multitable @columnfractions .15 .70 6735@item @var{OFFSET} @tab Shall of type @code{INTEGER}. 6736@item @var{UNIT} @tab Shall of type @code{INTEGER}. 6737@end multitable 6738 6739@item @emph{Return value}: 6740In either syntax, @var{OFFSET} is set to the current offset of unit 6741number @var{UNIT}, or to @math{-1} if the unit is not currently open. 6742 6743@item @emph{Example}: 6744@smallexample 6745PROGRAM test_ftell 6746 INTEGER :: i 6747 OPEN(10, FILE="temp.dat") 6748 CALL ftell(10,i) 6749 WRITE(*,*) i 6750END PROGRAM 6751@end smallexample 6752 6753@item @emph{See also}: 6754@ref{FSEEK} 6755@end table 6756 6757 6758 6759@node GAMMA 6760@section @code{GAMMA} --- Gamma function 6761@fnindex GAMMA 6762@fnindex DGAMMA 6763@cindex Gamma function 6764@cindex Factorial function 6765 6766@table @asis 6767@item @emph{Description}: 6768@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive, 6769integer values of @var{X} the Gamma function simplifies to the factorial 6770function @math{\Gamma(x)=(x-1)!}. 6771 6772@tex 6773$$ 6774\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t 6775$$ 6776@end tex 6777 6778@item @emph{Standard}: 6779Fortran 2008 and later 6780 6781@item @emph{Class}: 6782Elemental function 6783 6784@item @emph{Syntax}: 6785@code{X = GAMMA(X)} 6786 6787@item @emph{Arguments}: 6788@multitable @columnfractions .15 .70 6789@item @var{X} @tab Shall be of type @code{REAL} and neither zero 6790nor a negative integer. 6791@end multitable 6792 6793@item @emph{Return value}: 6794The return value is of type @code{REAL} of the same kind as @var{X}. 6795 6796@item @emph{Example}: 6797@smallexample 6798program test_gamma 6799 real :: x = 1.0 6800 x = gamma(x) ! returns 1.0 6801end program test_gamma 6802@end smallexample 6803 6804@item @emph{Specific names}: 6805@multitable @columnfractions .20 .20 .20 .25 6806@item Name @tab Argument @tab Return type @tab Standard 6807@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 6808@end multitable 6809 6810@item @emph{See also}: 6811Logarithm of the Gamma function: @gol 6812@ref{LOG_GAMMA} 6813@end table 6814 6815 6816 6817@node GERROR 6818@section @code{GERROR} --- Get last system error message 6819@fnindex GERROR 6820@cindex system, error handling 6821 6822@table @asis 6823@item @emph{Description}: 6824Returns the system error message corresponding to the last system error. 6825This resembles the functionality of @code{strerror(3)} in C. 6826 6827@item @emph{Standard}: 6828GNU extension 6829 6830@item @emph{Class}: 6831Subroutine 6832 6833@item @emph{Syntax}: 6834@code{CALL GERROR(RESULT)} 6835 6836@item @emph{Arguments}: 6837@multitable @columnfractions .15 .70 6838@item @var{RESULT} @tab Shall be of type @code{CHARACTER} and of default kind. 6839@end multitable 6840 6841@item @emph{Example}: 6842@smallexample 6843PROGRAM test_gerror 6844 CHARACTER(len=100) :: msg 6845 CALL gerror(msg) 6846 WRITE(*,*) msg 6847END PROGRAM 6848@end smallexample 6849 6850@item @emph{See also}: 6851@ref{IERRNO}, @gol 6852@ref{PERROR} 6853@end table 6854 6855 6856 6857@node GETARG 6858@section @code{GETARG} --- Get command line arguments 6859@fnindex GETARG 6860@cindex command-line arguments 6861@cindex arguments, to program 6862 6863@table @asis 6864@item @emph{Description}: 6865Retrieve the @var{POS}-th argument that was passed on the 6866command line when the containing program was invoked. 6867 6868This intrinsic routine is provided for backwards compatibility with 6869GNU Fortran 77. In new code, programmers should consider the use of 6870the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 6871standard. 6872 6873@item @emph{Standard}: 6874GNU extension 6875 6876@item @emph{Class}: 6877Subroutine 6878 6879@item @emph{Syntax}: 6880@code{CALL GETARG(POS, VALUE)} 6881 6882@item @emph{Arguments}: 6883@multitable @columnfractions .15 .70 6884@item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than 6885the default integer kind; @math{@var{POS} \geq 0} 6886@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default 6887kind. 6888@end multitable 6889 6890@item @emph{Return value}: 6891After @code{GETARG} returns, the @var{VALUE} argument holds the 6892@var{POS}th command line argument. If @var{VALUE} cannot hold the 6893argument, it is truncated to fit the length of @var{VALUE}. If there are 6894less than @var{POS} arguments specified at the command line, @var{VALUE} 6895will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set 6896to the name of the program (on systems that support this feature). 6897 6898@item @emph{Example}: 6899@smallexample 6900PROGRAM test_getarg 6901 INTEGER :: i 6902 CHARACTER(len=32) :: arg 6903 6904 DO i = 1, iargc() 6905 CALL getarg(i, arg) 6906 WRITE (*,*) arg 6907 END DO 6908END PROGRAM 6909@end smallexample 6910 6911@item @emph{See also}: 6912GNU Fortran 77 compatibility function: @gol 6913@ref{IARGC} @gol 6914Fortran 2003 functions and subroutines: @gol 6915@ref{GET_COMMAND}, @gol 6916@ref{GET_COMMAND_ARGUMENT}, @gol 6917@ref{COMMAND_ARGUMENT_COUNT} 6918@end table 6919 6920 6921 6922@node GET_COMMAND 6923@section @code{GET_COMMAND} --- Get the entire command line 6924@fnindex GET_COMMAND 6925@cindex command-line arguments 6926@cindex arguments, to program 6927 6928@table @asis 6929@item @emph{Description}: 6930Retrieve the entire command line that was used to invoke the program. 6931 6932@item @emph{Standard}: 6933Fortran 2003 and later 6934 6935@item @emph{Class}: 6936Subroutine 6937 6938@item @emph{Syntax}: 6939@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])} 6940 6941@item @emph{Arguments}: 6942@multitable @columnfractions .15 .70 6943@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and 6944of default kind. 6945@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of 6946default kind. 6947@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of 6948default kind. 6949@end multitable 6950 6951@item @emph{Return value}: 6952If @var{COMMAND} is present, stores the entire command line that was used 6953to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is 6954assigned the length of the command line. If @var{STATUS} is present, it 6955is assigned 0 upon success of the command, -1 if @var{COMMAND} is too 6956short to store the command line, or a positive value in case of an error. 6957 6958@item @emph{Example}: 6959@smallexample 6960PROGRAM test_get_command 6961 CHARACTER(len=255) :: cmd 6962 CALL get_command(cmd) 6963 WRITE (*,*) TRIM(cmd) 6964END PROGRAM 6965@end smallexample 6966 6967@item @emph{See also}: 6968@ref{GET_COMMAND_ARGUMENT}, @gol 6969@ref{COMMAND_ARGUMENT_COUNT} 6970@end table 6971 6972 6973 6974@node GET_COMMAND_ARGUMENT 6975@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments 6976@fnindex GET_COMMAND_ARGUMENT 6977@cindex command-line arguments 6978@cindex arguments, to program 6979 6980@table @asis 6981@item @emph{Description}: 6982Retrieve the @var{NUMBER}-th argument that was passed on the 6983command line when the containing program was invoked. 6984 6985@item @emph{Standard}: 6986Fortran 2003 and later 6987 6988@item @emph{Class}: 6989Subroutine 6990 6991@item @emph{Syntax}: 6992@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])} 6993 6994@item @emph{Arguments}: 6995@multitable @columnfractions .15 .70 6996@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of 6997default kind, @math{@var{NUMBER} \geq 0} 6998@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 6999and of default kind. 7000@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7001and of default kind. 7002@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7003and of default kind. 7004@end multitable 7005 7006@item @emph{Return value}: 7007After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the 7008@var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is 7009truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER} 7010arguments specified at the command line, @var{VALUE} will be filled with blanks. 7011If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on 7012systems that support this feature). The @var{LENGTH} argument contains the 7013length of the @var{NUMBER}-th command line argument. If the argument retrieval 7014fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated 7015command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is 7016zero. 7017 7018@item @emph{Example}: 7019@smallexample 7020PROGRAM test_get_command_argument 7021 INTEGER :: i 7022 CHARACTER(len=32) :: arg 7023 7024 i = 0 7025 DO 7026 CALL get_command_argument(i, arg) 7027 IF (LEN_TRIM(arg) == 0) EXIT 7028 7029 WRITE (*,*) TRIM(arg) 7030 i = i+1 7031 END DO 7032END PROGRAM 7033@end smallexample 7034 7035@item @emph{See also}: 7036@ref{GET_COMMAND}, @gol 7037@ref{COMMAND_ARGUMENT_COUNT} 7038@end table 7039 7040 7041 7042@node GETCWD 7043@section @code{GETCWD} --- Get current working directory 7044@fnindex GETCWD 7045@cindex system, working directory 7046 7047@table @asis 7048@item @emph{Description}: 7049Get current working directory. 7050 7051This intrinsic is provided in both subroutine and function forms; however, 7052only one form can be used in any given program unit. 7053 7054@item @emph{Standard}: 7055GNU extension 7056 7057@item @emph{Class}: 7058Subroutine, function 7059 7060@item @emph{Syntax}: 7061@multitable @columnfractions .80 7062@item @code{CALL GETCWD(C [, STATUS])} 7063@item @code{STATUS = GETCWD(C)} 7064@end multitable 7065 7066@item @emph{Arguments}: 7067@multitable @columnfractions .15 .70 7068@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. 7069@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, 7070a system specific and nonzero error code otherwise. 7071@end multitable 7072 7073@item @emph{Example}: 7074@smallexample 7075PROGRAM test_getcwd 7076 CHARACTER(len=255) :: cwd 7077 CALL getcwd(cwd) 7078 WRITE(*,*) TRIM(cwd) 7079END PROGRAM 7080@end smallexample 7081 7082@item @emph{See also}: 7083@ref{CHDIR} 7084@end table 7085 7086 7087 7088@node GETENV 7089@section @code{GETENV} --- Get an environmental variable 7090@fnindex GETENV 7091@cindex environment variable 7092 7093@table @asis 7094@item @emph{Description}: 7095Get the @var{VALUE} of the environmental variable @var{NAME}. 7096 7097This intrinsic routine is provided for backwards compatibility with 7098GNU Fortran 77. In new code, programmers should consider the use of 7099the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran 71002003 standard. 7101 7102Note that @code{GETENV} need not be thread-safe. It is the 7103responsibility of the user to ensure that the environment is not being 7104updated concurrently with a call to the @code{GETENV} intrinsic. 7105 7106@item @emph{Standard}: 7107GNU extension 7108 7109@item @emph{Class}: 7110Subroutine 7111 7112@item @emph{Syntax}: 7113@code{CALL GETENV(NAME, VALUE)} 7114 7115@item @emph{Arguments}: 7116@multitable @columnfractions .15 .70 7117@item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind. 7118@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. 7119@end multitable 7120 7121@item @emph{Return value}: 7122Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 7123not large enough to hold the data, it is truncated. If @var{NAME} 7124is not set, @var{VALUE} will be filled with blanks. 7125 7126@item @emph{Example}: 7127@smallexample 7128PROGRAM test_getenv 7129 CHARACTER(len=255) :: homedir 7130 CALL getenv("HOME", homedir) 7131 WRITE (*,*) TRIM(homedir) 7132END PROGRAM 7133@end smallexample 7134 7135@item @emph{See also}: 7136@ref{GET_ENVIRONMENT_VARIABLE} 7137@end table 7138 7139 7140 7141@node GET_ENVIRONMENT_VARIABLE 7142@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable 7143@fnindex GET_ENVIRONMENT_VARIABLE 7144@cindex environment variable 7145 7146@table @asis 7147@item @emph{Description}: 7148Get the @var{VALUE} of the environmental variable @var{NAME}. 7149 7150Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It 7151is the responsibility of the user to ensure that the environment is 7152not being updated concurrently with a call to the 7153@code{GET_ENVIRONMENT_VARIABLE} intrinsic. 7154 7155@item @emph{Standard}: 7156Fortran 2003 and later 7157 7158@item @emph{Class}: 7159Subroutine 7160 7161@item @emph{Syntax}: 7162@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)} 7163 7164@item @emph{Arguments}: 7165@multitable @columnfractions .15 .70 7166@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER} 7167and of default kind. 7168@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 7169and of default kind. 7170@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7171and of default kind. 7172@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7173and of default kind. 7174@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL} 7175and of default kind. 7176@end multitable 7177 7178@item @emph{Return value}: 7179Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 7180not large enough to hold the data, it is truncated. If @var{NAME} 7181is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH} 7182contains the length needed for storing the environment variable @var{NAME} 7183or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present 7184but too short for the environment variable; it is 1 if the environment 7185variable does not exist and 2 if the processor does not support environment 7186variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is 7187present with the value @code{.FALSE.}, the trailing blanks in @var{NAME} 7188are significant; otherwise they are not part of the environment variable 7189name. 7190 7191@item @emph{Example}: 7192@smallexample 7193PROGRAM test_getenv 7194 CHARACTER(len=255) :: homedir 7195 CALL get_environment_variable("HOME", homedir) 7196 WRITE (*,*) TRIM(homedir) 7197END PROGRAM 7198@end smallexample 7199@end table 7200 7201 7202 7203@node GETGID 7204@section @code{GETGID} --- Group ID function 7205@fnindex GETGID 7206@cindex system, group ID 7207 7208@table @asis 7209@item @emph{Description}: 7210Returns the numerical group ID of the current process. 7211 7212@item @emph{Standard}: 7213GNU extension 7214 7215@item @emph{Class}: 7216Function 7217 7218@item @emph{Syntax}: 7219@code{RESULT = GETGID()} 7220 7221@item @emph{Return value}: 7222The return value of @code{GETGID} is an @code{INTEGER} of the default 7223kind. 7224 7225 7226@item @emph{Example}: 7227See @code{GETPID} for an example. 7228 7229@item @emph{See also}: 7230@ref{GETPID}, @gol 7231@ref{GETUID} 7232@end table 7233 7234 7235 7236@node GETLOG 7237@section @code{GETLOG} --- Get login name 7238@fnindex GETLOG 7239@cindex system, login name 7240@cindex login name 7241 7242@table @asis 7243@item @emph{Description}: 7244Gets the username under which the program is running. 7245 7246@item @emph{Standard}: 7247GNU extension 7248 7249@item @emph{Class}: 7250Subroutine 7251 7252@item @emph{Syntax}: 7253@code{CALL GETLOG(C)} 7254 7255@item @emph{Arguments}: 7256@multitable @columnfractions .15 .70 7257@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind. 7258@end multitable 7259 7260@item @emph{Return value}: 7261Stores the current user name in @var{C}. (On systems where POSIX 7262functions @code{geteuid} and @code{getpwuid} are not available, and 7263the @code{getlogin} function is not implemented either, this will 7264return a blank string.) 7265 7266@item @emph{Example}: 7267@smallexample 7268PROGRAM TEST_GETLOG 7269 CHARACTER(32) :: login 7270 CALL GETLOG(login) 7271 WRITE(*,*) login 7272END PROGRAM 7273@end smallexample 7274 7275@item @emph{See also}: 7276@ref{GETUID} 7277@end table 7278 7279 7280 7281@node GETPID 7282@section @code{GETPID} --- Process ID function 7283@fnindex GETPID 7284@cindex system, process ID 7285@cindex process ID 7286 7287@table @asis 7288@item @emph{Description}: 7289Returns the numerical process identifier of the current process. 7290 7291@item @emph{Standard}: 7292GNU extension 7293 7294@item @emph{Class}: 7295Function 7296 7297@item @emph{Syntax}: 7298@code{RESULT = GETPID()} 7299 7300@item @emph{Return value}: 7301The return value of @code{GETPID} is an @code{INTEGER} of the default 7302kind. 7303 7304 7305@item @emph{Example}: 7306@smallexample 7307program info 7308 print *, "The current process ID is ", getpid() 7309 print *, "Your numerical user ID is ", getuid() 7310 print *, "Your numerical group ID is ", getgid() 7311end program info 7312@end smallexample 7313 7314@item @emph{See also}: 7315@ref{GETGID}, @gol 7316@ref{GETUID} 7317@end table 7318 7319 7320 7321@node GETUID 7322@section @code{GETUID} --- User ID function 7323@fnindex GETUID 7324@cindex system, user ID 7325@cindex user id 7326 7327@table @asis 7328@item @emph{Description}: 7329Returns the numerical user ID of the current process. 7330 7331@item @emph{Standard}: 7332GNU extension 7333 7334@item @emph{Class}: 7335Function 7336 7337@item @emph{Syntax}: 7338@code{RESULT = GETUID()} 7339 7340@item @emph{Return value}: 7341The return value of @code{GETUID} is an @code{INTEGER} of the default 7342kind. 7343 7344 7345@item @emph{Example}: 7346See @code{GETPID} for an example. 7347 7348@item @emph{See also}: 7349@ref{GETPID}, @gol 7350@ref{GETLOG} 7351@end table 7352 7353 7354 7355@node GMTIME 7356@section @code{GMTIME} --- Convert time to GMT info 7357@fnindex GMTIME 7358@cindex time, conversion to GMT info 7359 7360@table @asis 7361@item @emph{Description}: 7362Given a system time value @var{TIME} (as provided by the @ref{TIME} 7363intrinsic), fills @var{VALUES} with values extracted from it appropriate 7364to the UTC time zone (Universal Coordinated Time, also known in some 7365countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}. 7366 7367This intrinsic routine is provided for backwards compatibility with 7368GNU Fortran 77. In new code, programmers should consider the use of 7369the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 7370standard. 7371 7372@item @emph{Standard}: 7373GNU extension 7374 7375@item @emph{Class}: 7376Subroutine 7377 7378@item @emph{Syntax}: 7379@code{CALL GMTIME(TIME, VALUES)} 7380 7381@item @emph{Arguments}: 7382@multitable @columnfractions .15 .70 7383@item @var{TIME} @tab An @code{INTEGER} scalar expression 7384corresponding to a system time, with @code{INTENT(IN)}. 7385@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 7386with @code{INTENT(OUT)}. 7387@end multitable 7388 7389@item @emph{Return value}: 7390The elements of @var{VALUES} are assigned as follows: 7391@enumerate 7392@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 7393seconds 7394@item Minutes after the hour, range 0--59 7395@item Hours past midnight, range 0--23 7396@item Day of month, range 1--31 7397@item Number of months since January, range 0--11 7398@item Years since 1900 7399@item Number of days since Sunday, range 0--6 7400@item Days since January 1, range 0--365 7401@item Daylight savings indicator: positive if daylight savings is in 7402effect, zero if not, and negative if the information is not available. 7403@end enumerate 7404 7405@item @emph{See also}: 7406@ref{DATE_AND_TIME}, @gol 7407@ref{CTIME}, @gol 7408@ref{LTIME}, @gol 7409@ref{TIME}, @gol 7410@ref{TIME8} 7411@end table 7412 7413 7414 7415@node HOSTNM 7416@section @code{HOSTNM} --- Get system host name 7417@fnindex HOSTNM 7418@cindex system, host name 7419 7420@table @asis 7421@item @emph{Description}: 7422Retrieves the host name of the system on which the program is running. 7423 7424This intrinsic is provided in both subroutine and function forms; however, 7425only one form can be used in any given program unit. 7426 7427@item @emph{Standard}: 7428GNU extension 7429 7430@item @emph{Class}: 7431Subroutine, function 7432 7433@item @emph{Syntax}: 7434@multitable @columnfractions .80 7435@item @code{CALL HOSTNM(C [, STATUS])} 7436@item @code{STATUS = HOSTNM(NAME)} 7437@end multitable 7438 7439@item @emph{Arguments}: 7440@multitable @columnfractions .15 .70 7441@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind. 7442@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 7443Returns 0 on success, or a system specific error code otherwise. 7444@end multitable 7445 7446@item @emph{Return value}: 7447In either syntax, @var{NAME} is set to the current hostname if it can 7448be obtained, or to a blank string otherwise. 7449 7450@end table 7451 7452 7453 7454@node HUGE 7455@section @code{HUGE} --- Largest number of a kind 7456@fnindex HUGE 7457@cindex limits, largest number 7458@cindex model representation, largest number 7459 7460@table @asis 7461@item @emph{Description}: 7462@code{HUGE(X)} returns the largest number that is not an infinity in 7463the model of the type of @code{X}. 7464 7465@item @emph{Standard}: 7466Fortran 90 and later 7467 7468@item @emph{Class}: 7469Inquiry function 7470 7471@item @emph{Syntax}: 7472@code{RESULT = HUGE(X)} 7473 7474@item @emph{Arguments}: 7475@multitable @columnfractions .15 .70 7476@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}. 7477@end multitable 7478 7479@item @emph{Return value}: 7480The return value is of the same type and kind as @var{X} 7481 7482@item @emph{Example}: 7483@smallexample 7484program test_huge_tiny 7485 print *, huge(0), huge(0.0), huge(0.0d0) 7486 print *, tiny(0.0), tiny(0.0d0) 7487end program test_huge_tiny 7488@end smallexample 7489@end table 7490 7491 7492 7493@node HYPOT 7494@section @code{HYPOT} --- Euclidean distance function 7495@fnindex HYPOT 7496@cindex Euclidean distance 7497 7498@table @asis 7499@item @emph{Description}: 7500@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to 7501@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow. 7502 7503@item @emph{Standard}: 7504Fortran 2008 and later 7505 7506@item @emph{Class}: 7507Elemental function 7508 7509@item @emph{Syntax}: 7510@code{RESULT = HYPOT(X, Y)} 7511 7512@item @emph{Arguments}: 7513@multitable @columnfractions .15 .70 7514@item @var{X} @tab The type shall be @code{REAL}. 7515@item @var{Y} @tab The type and kind type parameter shall be the same as 7516@var{X}. 7517@end multitable 7518 7519@item @emph{Return value}: 7520The return value has the same type and kind type parameter as @var{X}. 7521 7522@item @emph{Example}: 7523@smallexample 7524program test_hypot 7525 real(4) :: x = 1.e0_4, y = 0.5e0_4 7526 x = hypot(x,y) 7527end program test_hypot 7528@end smallexample 7529@end table 7530 7531 7532 7533@node IACHAR 7534@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence 7535@fnindex IACHAR 7536@cindex @acronym{ASCII} collating sequence 7537@cindex collating sequence, @acronym{ASCII} 7538@cindex conversion, to integer 7539 7540@table @asis 7541@item @emph{Description}: 7542@code{IACHAR(C)} returns the code for the @acronym{ASCII} character 7543in the first character position of @code{C}. 7544 7545@item @emph{Standard}: 7546Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 7547 7548@item @emph{Class}: 7549Elemental function 7550 7551@item @emph{Syntax}: 7552@code{RESULT = IACHAR(C [, KIND])} 7553 7554@item @emph{Arguments}: 7555@multitable @columnfractions .15 .70 7556@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 7557@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7558expression indicating the kind parameter of the result. 7559@end multitable 7560 7561@item @emph{Return value}: 7562The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7563@var{KIND} is absent, the return value is of default integer kind. 7564 7565@item @emph{Example}: 7566@smallexample 7567program test_iachar 7568 integer i 7569 i = iachar(' ') 7570end program test_iachar 7571@end smallexample 7572 7573@item @emph{Note}: 7574See @ref{ICHAR} for a discussion of converting between numerical values 7575and formatted string representations. 7576 7577@item @emph{See also}: 7578@ref{ACHAR}, @gol 7579@ref{CHAR}, @gol 7580@ref{ICHAR} 7581@end table 7582 7583 7584 7585@node IALL 7586@section @code{IALL} --- Bitwise AND of array elements 7587@fnindex IALL 7588@cindex array, AND 7589@cindex bits, AND of array elements 7590 7591@table @asis 7592@item @emph{Description}: 7593Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM} 7594if the corresponding element in @var{MASK} is @code{TRUE}. 7595 7596@item @emph{Standard}: 7597Fortran 2008 and later 7598 7599@item @emph{Class}: 7600Transformational function 7601 7602@item @emph{Syntax}: 7603@multitable @columnfractions .80 7604@item @code{RESULT = IALL(ARRAY[, MASK])} 7605@item @code{RESULT = IALL(ARRAY, DIM[, MASK])} 7606@end multitable 7607 7608@item @emph{Arguments}: 7609@multitable @columnfractions .15 .70 7610@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7611@item @var{DIM} @tab (Optional) shall be a scalar of type 7612@code{INTEGER} with a value in the range from 1 to n, where n 7613equals the rank of @var{ARRAY}. 7614@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7615and either be a scalar or an array of the same shape as @var{ARRAY}. 7616@end multitable 7617 7618@item @emph{Return value}: 7619The result is of the same type as @var{ARRAY}. 7620 7621If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in 7622@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7623the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7624dimension @var{DIM} dropped is returned. 7625 7626@item @emph{Example}: 7627@smallexample 7628PROGRAM test_iall 7629 INTEGER(1) :: a(2) 7630 7631 a(1) = b'00100100' 7632 a(2) = b'01101010' 7633 7634 ! prints 00100000 7635 PRINT '(b8.8)', IALL(a) 7636END PROGRAM 7637@end smallexample 7638 7639@item @emph{See also}: 7640@ref{IANY}, @gol 7641@ref{IPARITY}, @gol 7642@ref{IAND} 7643@end table 7644 7645 7646 7647@node IAND 7648@section @code{IAND} --- Bitwise logical and 7649@fnindex IAND 7650@fnindex BIAND 7651@fnindex IIAND 7652@fnindex JIAND 7653@fnindex KIAND 7654@cindex bitwise logical and 7655@cindex logical and, bitwise 7656 7657@table @asis 7658@item @emph{Description}: 7659Bitwise logical @code{AND}. 7660 7661@item @emph{Standard}: 7662Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 7663 7664@item @emph{Class}: 7665Elemental function 7666 7667@item @emph{Syntax}: 7668@code{RESULT = IAND(I, J)} 7669 7670@item @emph{Arguments}: 7671@multitable @columnfractions .15 .70 7672@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 7673@item @var{J} @tab The type shall be @code{INTEGER} with the same 7674kind type parameter as @var{I} or a boz-literal-constant. 7675@var{I} and @var{J} shall not both be boz-literal-constants. 7676@end multitable 7677 7678@item @emph{Return value}: 7679The return type is @code{INTEGER} with the kind type parameter of the 7680arguments. 7681A boz-literal-constant is converted to an @code{INTEGER} with the kind 7682type parameter of the other argument as-if a call to @ref{INT} occurred. 7683 7684@item @emph{Example}: 7685@smallexample 7686PROGRAM test_iand 7687 INTEGER :: a, b 7688 DATA a / Z'F' /, b / Z'3' / 7689 WRITE (*,*) IAND(a, b) 7690END PROGRAM 7691@end smallexample 7692 7693@item @emph{Specific names}: 7694@multitable @columnfractions .20 .20 .20 .25 7695@item Name @tab Argument @tab Return type @tab Standard 7696@item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7697@item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7698@item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7699@item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7700@item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7701@end multitable 7702 7703@item @emph{See also}: 7704@ref{IOR}, @gol 7705@ref{IEOR}, @gol 7706@ref{IBITS}, @gol 7707@ref{IBSET}, @gol 7708@ref{IBCLR}, @gol 7709@ref{NOT} 7710@end table 7711 7712 7713 7714@node IANY 7715@section @code{IANY} --- Bitwise OR of array elements 7716@fnindex IANY 7717@cindex array, OR 7718@cindex bits, OR of array elements 7719 7720@table @asis 7721@item @emph{Description}: 7722Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along 7723dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 7724 7725@item @emph{Standard}: 7726Fortran 2008 and later 7727 7728@item @emph{Class}: 7729Transformational function 7730 7731@item @emph{Syntax}: 7732@multitable @columnfractions .80 7733@item @code{RESULT = IANY(ARRAY[, MASK])} 7734@item @code{RESULT = IANY(ARRAY, DIM[, MASK])} 7735@end multitable 7736 7737@item @emph{Arguments}: 7738@multitable @columnfractions .15 .70 7739@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7740@item @var{DIM} @tab (Optional) shall be a scalar of type 7741@code{INTEGER} with a value in the range from 1 to n, where n 7742equals the rank of @var{ARRAY}. 7743@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7744and either be a scalar or an array of the same shape as @var{ARRAY}. 7745@end multitable 7746 7747@item @emph{Return value}: 7748The result is of the same type as @var{ARRAY}. 7749 7750If @var{DIM} is absent, a scalar with the bitwise OR of all elements in 7751@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7752the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7753dimension @var{DIM} dropped is returned. 7754 7755@item @emph{Example}: 7756@smallexample 7757PROGRAM test_iany 7758 INTEGER(1) :: a(2) 7759 7760 a(1) = b'00100100' 7761 a(2) = b'01101010' 7762 7763 ! prints 01101110 7764 PRINT '(b8.8)', IANY(a) 7765END PROGRAM 7766@end smallexample 7767 7768@item @emph{See also}: 7769@ref{IPARITY}, @gol 7770@ref{IALL}, @gol 7771@ref{IOR} 7772@end table 7773 7774 7775 7776@node IARGC 7777@section @code{IARGC} --- Get the number of command line arguments 7778@fnindex IARGC 7779@cindex command-line arguments 7780@cindex command-line arguments, number of 7781@cindex arguments, to program 7782 7783@table @asis 7784@item @emph{Description}: 7785@code{IARGC} returns the number of arguments passed on the 7786command line when the containing program was invoked. 7787 7788This intrinsic routine is provided for backwards compatibility with 7789GNU Fortran 77. In new code, programmers should consider the use of 7790the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 7791standard. 7792 7793@item @emph{Standard}: 7794GNU extension 7795 7796@item @emph{Class}: 7797Function 7798 7799@item @emph{Syntax}: 7800@code{RESULT = IARGC()} 7801 7802@item @emph{Arguments}: 7803None 7804 7805@item @emph{Return value}: 7806The number of command line arguments, type @code{INTEGER(4)}. 7807 7808@item @emph{Example}: 7809See @ref{GETARG} 7810 7811@item @emph{See also}: 7812GNU Fortran 77 compatibility subroutine: @gol 7813@ref{GETARG} @gol 7814Fortran 2003 functions and subroutines: @gol 7815@ref{GET_COMMAND}, @gol 7816@ref{GET_COMMAND_ARGUMENT}, @gol 7817@ref{COMMAND_ARGUMENT_COUNT} 7818@end table 7819 7820 7821 7822@node IBCLR 7823@section @code{IBCLR} --- Clear bit 7824@fnindex IBCLR 7825@fnindex BBCLR 7826@fnindex IIBCLR 7827@fnindex JIBCLR 7828@fnindex KIBCLR 7829@cindex bits, unset 7830@cindex bits, clear 7831 7832@table @asis 7833@item @emph{Description}: 7834@code{IBCLR} returns the value of @var{I} with the bit at position 7835@var{POS} set to zero. 7836 7837@item @emph{Standard}: 7838Fortran 90 and later, has overloads that are GNU extensions 7839 7840@item @emph{Class}: 7841Elemental function 7842 7843@item @emph{Syntax}: 7844@code{RESULT = IBCLR(I, POS)} 7845 7846@item @emph{Arguments}: 7847@multitable @columnfractions .15 .70 7848@item @var{I} @tab The type shall be @code{INTEGER}. 7849@item @var{POS} @tab The type shall be @code{INTEGER}. 7850@end multitable 7851 7852@item @emph{Return value}: 7853The return value is of type @code{INTEGER} and of the same kind as 7854@var{I}. 7855 7856@item @emph{Specific names}: 7857@multitable @columnfractions .20 .20 .20 .25 7858@item Name @tab Argument @tab Return type @tab Standard 7859@item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7860@item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7861@item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7862@item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7863@item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7864@end multitable 7865 7866@item @emph{See also}: 7867@ref{IBITS}, @gol 7868@ref{IBSET}, @gol 7869@ref{IAND}, @gol 7870@ref{IOR}, @gol 7871@ref{IEOR}, @gol 7872@ref{MVBITS} 7873@end table 7874 7875 7876 7877@node IBITS 7878@section @code{IBITS} --- Bit extraction 7879@fnindex IBITS 7880@fnindex BBITS 7881@fnindex IIBITS 7882@fnindex JIBITS 7883@fnindex KIBITS 7884@cindex bits, get 7885@cindex bits, extract 7886 7887@table @asis 7888@item @emph{Description}: 7889@code{IBITS} extracts a field of length @var{LEN} from @var{I}, 7890starting from bit position @var{POS} and extending left for @var{LEN} 7891bits. The result is right-justified and the remaining bits are 7892zeroed. The value of @code{POS+LEN} must be less than or equal to the 7893value @code{BIT_SIZE(I)}. 7894 7895@item @emph{Standard}: 7896Fortran 90 and later, has overloads that are GNU extensions 7897 7898@item @emph{Class}: 7899Elemental function 7900 7901@item @emph{Syntax}: 7902@code{RESULT = IBITS(I, POS, LEN)} 7903 7904@item @emph{Arguments}: 7905@multitable @columnfractions .15 .70 7906@item @var{I} @tab The type shall be @code{INTEGER}. 7907@item @var{POS} @tab The type shall be @code{INTEGER}. 7908@item @var{LEN} @tab The type shall be @code{INTEGER}. 7909@end multitable 7910 7911@item @emph{Return value}: 7912The return value is of type @code{INTEGER} and of the same kind as 7913@var{I}. 7914 7915@item @emph{Specific names}: 7916@multitable @columnfractions .20 .20 .20 .25 7917@item Name @tab Argument @tab Return type @tab Standard 7918@item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7919@item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7920@item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7921@item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7922@item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7923@end multitable 7924 7925@item @emph{See also}: 7926@ref{BIT_SIZE}, @gol 7927@ref{IBCLR}, @gol 7928@ref{IBSET}, @gol 7929@ref{IAND}, @gol 7930@ref{IOR}, @gol 7931@ref{IEOR} 7932@end table 7933 7934 7935 7936@node IBSET 7937@section @code{IBSET} --- Set bit 7938@fnindex IBSET 7939@fnindex BBSET 7940@fnindex IIBSET 7941@fnindex JIBSET 7942@fnindex KIBSET 7943@cindex bits, set 7944 7945@table @asis 7946@item @emph{Description}: 7947@code{IBSET} returns the value of @var{I} with the bit at position 7948@var{POS} set to one. 7949 7950@item @emph{Standard}: 7951Fortran 90 and later, has overloads that are GNU extensions 7952 7953@item @emph{Class}: 7954Elemental function 7955 7956@item @emph{Syntax}: 7957@code{RESULT = IBSET(I, POS)} 7958 7959@item @emph{Arguments}: 7960@multitable @columnfractions .15 .70 7961@item @var{I} @tab The type shall be @code{INTEGER}. 7962@item @var{POS} @tab The type shall be @code{INTEGER}. 7963@end multitable 7964 7965@item @emph{Return value}: 7966The return value is of type @code{INTEGER} and of the same kind as 7967@var{I}. 7968 7969@item @emph{Specific names}: 7970@multitable @columnfractions .20 .20 .20 .25 7971@item Name @tab Argument @tab Return type @tab Standard 7972@item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7973@item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7974@item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7975@item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7976@item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7977@end multitable 7978 7979@item @emph{See also}: 7980@ref{IBCLR}, @gol 7981@ref{IBITS}, @gol 7982@ref{IAND}, @gol 7983@ref{IOR}, @gol 7984@ref{IEOR}, @gol 7985@ref{MVBITS} 7986@end table 7987 7988 7989 7990@node ICHAR 7991@section @code{ICHAR} --- Character-to-integer conversion function 7992@fnindex ICHAR 7993@cindex conversion, to integer 7994 7995@table @asis 7996@item @emph{Description}: 7997@code{ICHAR(C)} returns the code for the character in the first character 7998position of @code{C} in the system's native character set. 7999The correspondence between characters and their codes is not necessarily 8000the same across different GNU Fortran implementations. 8001 8002@item @emph{Standard}: 8003Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8004 8005@item @emph{Class}: 8006Elemental function 8007 8008@item @emph{Syntax}: 8009@code{RESULT = ICHAR(C [, KIND])} 8010 8011@item @emph{Arguments}: 8012@multitable @columnfractions .15 .70 8013@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 8014@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8015expression indicating the kind parameter of the result. 8016@end multitable 8017 8018@item @emph{Return value}: 8019The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8020@var{KIND} is absent, the return value is of default integer kind. 8021 8022@item @emph{Example}: 8023@smallexample 8024program test_ichar 8025 integer i 8026 i = ichar(' ') 8027end program test_ichar 8028@end smallexample 8029 8030@item @emph{Specific names}: 8031@multitable @columnfractions .20 .20 .20 .25 8032@item Name @tab Argument @tab Return type @tab Standard 8033@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later 8034@end multitable 8035 8036@item @emph{Note}: 8037No intrinsic exists to convert between a numeric value and a formatted 8038character string representation -- for instance, given the 8039@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or 8040@code{REAL} value with the value 154, or vice versa. Instead, this 8041functionality is provided by internal-file I/O, as in the following 8042example: 8043@smallexample 8044program read_val 8045 integer value 8046 character(len=10) string, string2 8047 string = '154' 8048 8049 ! Convert a string to a numeric value 8050 read (string,'(I10)') value 8051 print *, value 8052 8053 ! Convert a value to a formatted string 8054 write (string2,'(I10)') value 8055 print *, string2 8056end program read_val 8057@end smallexample 8058 8059@item @emph{See also}: 8060@ref{ACHAR}, @gol 8061@ref{CHAR}, @gol 8062@ref{IACHAR} 8063@end table 8064 8065 8066 8067@node IDATE 8068@section @code{IDATE} --- Get current local time subroutine (day/month/year) 8069@fnindex IDATE 8070@cindex date, current 8071@cindex current date 8072 8073@table @asis 8074@item @emph{Description}: 8075@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the 8076current local time. The day (in the range 1-31), month (in the range 1-12), 8077and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively. 8078The year has four significant digits. 8079 8080This intrinsic routine is provided for backwards compatibility with 8081GNU Fortran 77. In new code, programmers should consider the use of 8082the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 8083standard. 8084 8085@item @emph{Standard}: 8086GNU extension 8087 8088@item @emph{Class}: 8089Subroutine 8090 8091@item @emph{Syntax}: 8092@code{CALL IDATE(VALUES)} 8093 8094@item @emph{Arguments}: 8095@multitable @columnfractions .15 .70 8096@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and 8097the kind shall be the default integer kind. 8098@end multitable 8099 8100@item @emph{Return value}: 8101Does not return anything. 8102 8103@item @emph{Example}: 8104@smallexample 8105program test_idate 8106 integer, dimension(3) :: tarray 8107 call idate(tarray) 8108 print *, tarray(1) 8109 print *, tarray(2) 8110 print *, tarray(3) 8111end program test_idate 8112@end smallexample 8113 8114@item @emph{See also}: 8115@ref{DATE_AND_TIME} 8116@end table 8117 8118 8119@node IEOR 8120@section @code{IEOR} --- Bitwise logical exclusive or 8121@fnindex IEOR 8122@fnindex BIEOR 8123@fnindex IIEOR 8124@fnindex JIEOR 8125@fnindex KIEOR 8126@cindex bitwise logical exclusive or 8127@cindex logical exclusive or, bitwise 8128 8129@table @asis 8130@item @emph{Description}: 8131@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and 8132@var{J}. 8133 8134@item @emph{Standard}: 8135Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 8136 8137@item @emph{Class}: 8138Elemental function 8139 8140@item @emph{Syntax}: 8141@code{RESULT = IEOR(I, J)} 8142 8143@item @emph{Arguments}: 8144@multitable @columnfractions .15 .70 8145@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 8146@item @var{J} @tab The type shall be @code{INTEGER} with the same 8147kind type parameter as @var{I} or a boz-literal-constant. 8148@var{I} and @var{J} shall not both be boz-literal-constants. 8149@end multitable 8150 8151@item @emph{Return value}: 8152The return type is @code{INTEGER} with the kind type parameter of the 8153arguments. 8154A boz-literal-constant is converted to an @code{INTEGER} with the kind 8155type parameter of the other argument as-if a call to @ref{INT} occurred. 8156 8157@item @emph{Specific names}: 8158@multitable @columnfractions .20 .20 .20 .25 8159@item Name @tab Argument @tab Return type @tab Standard 8160@item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8161@item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8162@item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8163@item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8164@item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8165@end multitable 8166 8167@item @emph{See also}: 8168@ref{IOR}, @gol 8169@ref{IAND}, @gol 8170@ref{IBITS}, @gol 8171@ref{IBSET}, @gol 8172@ref{IBCLR}, @gol 8173@ref{NOT} 8174@end table 8175 8176 8177 8178@node IERRNO 8179@section @code{IERRNO} --- Get the last system error number 8180@fnindex IERRNO 8181@cindex system, error handling 8182 8183@table @asis 8184@item @emph{Description}: 8185Returns the last system error number, as given by the C @code{errno} 8186variable. 8187 8188@item @emph{Standard}: 8189GNU extension 8190 8191@item @emph{Class}: 8192Function 8193 8194@item @emph{Syntax}: 8195@code{RESULT = IERRNO()} 8196 8197@item @emph{Arguments}: 8198None 8199 8200@item @emph{Return value}: 8201The return value is of type @code{INTEGER} and of the default integer 8202kind. 8203 8204@item @emph{See also}: 8205@ref{PERROR} 8206@end table 8207 8208 8209 8210@node IMAGE_INDEX 8211@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index 8212@fnindex IMAGE_INDEX 8213@cindex coarray, @code{IMAGE_INDEX} 8214@cindex images, cosubscript to image index conversion 8215 8216@table @asis 8217@item @emph{Description}: 8218Returns the image index belonging to a cosubscript. 8219 8220@item @emph{Standard}: 8221Fortran 2008 and later 8222 8223@item @emph{Class}: 8224Inquiry function. 8225 8226@item @emph{Syntax}: 8227@code{RESULT = IMAGE_INDEX(COARRAY, SUB)} 8228 8229@item @emph{Arguments}: 8230@multitable @columnfractions .15 .70 8231@item @var{COARRAY} @tab Coarray of any type. 8232@item @var{SUB} @tab default integer rank-1 array of a size equal to 8233the corank of @var{COARRAY}. 8234@end multitable 8235 8236 8237@item @emph{Return value}: 8238Scalar default integer with the value of the image index which corresponds 8239to the cosubscripts. For invalid cosubscripts the result is zero. 8240 8241@item @emph{Example}: 8242@smallexample 8243INTEGER :: array[2,-1:4,8,*] 8244! Writes 28 (or 0 if there are fewer than 28 images) 8245WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1]) 8246@end smallexample 8247 8248@item @emph{See also}: 8249@ref{THIS_IMAGE}, @gol 8250@ref{NUM_IMAGES} 8251@end table 8252 8253 8254 8255@node INDEX intrinsic 8256@section @code{INDEX} --- Position of a substring within a string 8257@fnindex INDEX 8258@cindex substring position 8259@cindex string, find substring 8260 8261@table @asis 8262@item @emph{Description}: 8263Returns the position of the start of the first occurrence of string 8264@var{SUBSTRING} as a substring in @var{STRING}, counting from one. If 8265@var{SUBSTRING} is not present in @var{STRING}, zero is returned. If 8266the @var{BACK} argument is present and true, the return value is the 8267start of the last occurrence rather than the first. 8268 8269@item @emph{Standard}: 8270Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8271 8272@item @emph{Class}: 8273Elemental function 8274 8275@item @emph{Syntax}: 8276@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])} 8277 8278@item @emph{Arguments}: 8279@multitable @columnfractions .15 .70 8280@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with 8281@code{INTENT(IN)} 8282@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with 8283@code{INTENT(IN)} 8284@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with 8285@code{INTENT(IN)} 8286@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8287expression indicating the kind parameter of the result. 8288@end multitable 8289 8290@item @emph{Return value}: 8291The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8292@var{KIND} is absent, the return value is of default integer kind. 8293 8294@item @emph{Specific names}: 8295@multitable @columnfractions .20 .20 .20 .25 8296@item Name @tab Argument @tab Return type @tab Standard 8297@item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later 8298@end multitable 8299 8300@item @emph{See also}: 8301@ref{SCAN}, @gol 8302@ref{VERIFY} 8303@end table 8304 8305 8306 8307@node INT 8308@section @code{INT} --- Convert to integer type 8309@fnindex INT 8310@fnindex IFIX 8311@fnindex IDINT 8312@cindex conversion, to integer 8313 8314@table @asis 8315@item @emph{Description}: 8316Convert to integer type 8317 8318@item @emph{Standard}: 8319Fortran 77 and later, with boz-literal-constant Fortran 2008 and later. 8320 8321@item @emph{Class}: 8322Elemental function 8323 8324@item @emph{Syntax}: 8325@code{RESULT = INT(A [, KIND))} 8326 8327@item @emph{Arguments}: 8328@multitable @columnfractions .15 .70 8329@item @var{A} @tab Shall be of type @code{INTEGER}, 8330@code{REAL}, or @code{COMPLEX} or a boz-literal-constant. 8331@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8332expression indicating the kind parameter of the result. 8333@end multitable 8334 8335@item @emph{Return value}: 8336These functions return a @code{INTEGER} variable or array under 8337the following rules: 8338 8339@table @asis 8340@item (A) 8341If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 8342@item (B) 8343If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} 8344equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer 8345whose magnitude is the largest integer that does not exceed the magnitude 8346of @var{A} and whose sign is the same as the sign of @var{A}. 8347@item (C) 8348If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}. 8349@end table 8350 8351@item @emph{Example}: 8352@smallexample 8353program test_int 8354 integer :: i = 42 8355 complex :: z = (-3.7, 1.0) 8356 print *, int(i) 8357 print *, int(z), int(z,8) 8358end program 8359@end smallexample 8360 8361@item @emph{Specific names}: 8362@multitable @columnfractions .20 .20 .20 .25 8363@item Name @tab Argument @tab Return type @tab Standard 8364@item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8365@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8366@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 8367@end multitable 8368 8369@end table 8370 8371 8372@node INT2 8373@section @code{INT2} --- Convert to 16-bit integer type 8374@fnindex INT2 8375@fnindex SHORT 8376@cindex conversion, to integer 8377 8378@table @asis 8379@item @emph{Description}: 8380Convert to a @code{KIND=2} integer type. This is equivalent to the 8381standard @code{INT} intrinsic with an optional argument of 8382@code{KIND=2}, and is only included for backwards compatibility. 8383 8384The @code{SHORT} intrinsic is equivalent to @code{INT2}. 8385 8386@item @emph{Standard}: 8387GNU extension 8388 8389@item @emph{Class}: 8390Elemental function 8391 8392@item @emph{Syntax}: 8393@code{RESULT = INT2(A)} 8394 8395@item @emph{Arguments}: 8396@multitable @columnfractions .15 .70 8397@item @var{A} @tab Shall be of type @code{INTEGER}, 8398@code{REAL}, or @code{COMPLEX}. 8399@end multitable 8400 8401@item @emph{Return value}: 8402The return value is a @code{INTEGER(2)} variable. 8403 8404@item @emph{See also}: 8405@ref{INT}, @gol 8406@ref{INT8}, @gol 8407@ref{LONG} 8408@end table 8409 8410 8411 8412@node INT8 8413@section @code{INT8} --- Convert to 64-bit integer type 8414@fnindex INT8 8415@cindex conversion, to integer 8416 8417@table @asis 8418@item @emph{Description}: 8419Convert to a @code{KIND=8} integer type. This is equivalent to the 8420standard @code{INT} intrinsic with an optional argument of 8421@code{KIND=8}, and is only included for backwards compatibility. 8422 8423@item @emph{Standard}: 8424GNU extension 8425 8426@item @emph{Class}: 8427Elemental function 8428 8429@item @emph{Syntax}: 8430@code{RESULT = INT8(A)} 8431 8432@item @emph{Arguments}: 8433@multitable @columnfractions .15 .70 8434@item @var{A} @tab Shall be of type @code{INTEGER}, 8435@code{REAL}, or @code{COMPLEX}. 8436@end multitable 8437 8438@item @emph{Return value}: 8439The return value is a @code{INTEGER(8)} variable. 8440 8441@item @emph{See also}: 8442@ref{INT}, @gol 8443@ref{INT2}, @gol 8444@ref{LONG} 8445@end table 8446 8447 8448 8449@node IOR 8450@section @code{IOR} --- Bitwise logical or 8451@fnindex IOR 8452@fnindex BIOR 8453@fnindex IIOR 8454@fnindex JIOR 8455@fnindex KIOR 8456@cindex bitwise logical or 8457@cindex logical or, bitwise 8458 8459@table @asis 8460@item @emph{Description}: 8461@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and 8462@var{J}. 8463 8464@item @emph{Standard}: 8465Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 8466 8467@item @emph{Class}: 8468Elemental function 8469 8470@item @emph{Syntax}: 8471@code{RESULT = IOR(I, J)} 8472 8473@item @emph{Arguments}: 8474@multitable @columnfractions .15 .70 8475@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 8476@item @var{J} @tab The type shall be @code{INTEGER} with the same 8477kind type parameter as @var{I} or a boz-literal-constant. 8478@var{I} and @var{J} shall not both be boz-literal-constants. 8479@end multitable 8480 8481@item @emph{Return value}: 8482The return type is @code{INTEGER} with the kind type parameter of the 8483arguments. 8484A boz-literal-constant is converted to an @code{INTEGER} with the kind 8485type parameter of the other argument as-if a call to @ref{INT} occurred. 8486 8487@item @emph{Specific names}: 8488@multitable @columnfractions .20 .20 .20 .25 8489@item Name @tab Argument @tab Return type @tab Standard 8490@item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8491@item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8492@item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8493@item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8494@item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8495@end multitable 8496 8497@item @emph{See also}: 8498@ref{IEOR}, @gol 8499@ref{IAND}, @gol 8500@ref{IBITS}, @gol 8501@ref{IBSET}, @gol 8502@ref{IBCLR}, @gol 8503@ref{NOT} 8504@end table 8505 8506 8507 8508@node IPARITY 8509@section @code{IPARITY} --- Bitwise XOR of array elements 8510@fnindex IPARITY 8511@cindex array, parity 8512@cindex array, XOR 8513@cindex bits, XOR of array elements 8514 8515@table @asis 8516@item @emph{Description}: 8517Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along 8518dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 8519 8520@item @emph{Standard}: 8521Fortran 2008 and later 8522 8523@item @emph{Class}: 8524Transformational function 8525 8526@item @emph{Syntax}: 8527@multitable @columnfractions .80 8528@item @code{RESULT = IPARITY(ARRAY[, MASK])} 8529@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])} 8530@end multitable 8531 8532@item @emph{Arguments}: 8533@multitable @columnfractions .15 .70 8534@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 8535@item @var{DIM} @tab (Optional) shall be a scalar of type 8536@code{INTEGER} with a value in the range from 1 to n, where n 8537equals the rank of @var{ARRAY}. 8538@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 8539and either be a scalar or an array of the same shape as @var{ARRAY}. 8540@end multitable 8541 8542@item @emph{Return value}: 8543The result is of the same type as @var{ARRAY}. 8544 8545If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in 8546@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 8547the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 8548dimension @var{DIM} dropped is returned. 8549 8550@item @emph{Example}: 8551@smallexample 8552PROGRAM test_iparity 8553 INTEGER(1) :: a(2) 8554 8555 a(1) = int(b'00100100', 1) 8556 a(2) = int(b'01101010', 1) 8557 8558 ! prints 01001110 8559 PRINT '(b8.8)', IPARITY(a) 8560END PROGRAM 8561@end smallexample 8562 8563@item @emph{See also}: 8564@ref{IANY}, @gol 8565@ref{IALL}, @gol 8566@ref{IEOR}, @gol 8567@ref{PARITY} 8568@end table 8569 8570 8571 8572@node IRAND 8573@section @code{IRAND} --- Integer pseudo-random number 8574@fnindex IRAND 8575@cindex random number generation 8576 8577@table @asis 8578@item @emph{Description}: 8579@code{IRAND(FLAG)} returns a pseudo-random number from a uniform 8580distribution between 0 and a system-dependent limit (which is in most 8581cases 2147483647). If @var{FLAG} is 0, the next number 8582in the current sequence is returned; if @var{FLAG} is 1, the generator 8583is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 8584it is used as a new seed with @code{SRAND}. 8585 8586This intrinsic routine is provided for backwards compatibility with 8587GNU Fortran 77. It implements a simple modulo generator as provided 8588by @command{g77}. For new code, one should consider the use of 8589@ref{RANDOM_NUMBER} as it implements a superior algorithm. 8590 8591@item @emph{Standard}: 8592GNU extension 8593 8594@item @emph{Class}: 8595Function 8596 8597@item @emph{Syntax}: 8598@code{RESULT = IRAND(I)} 8599 8600@item @emph{Arguments}: 8601@multitable @columnfractions .15 .70 8602@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 8603@end multitable 8604 8605@item @emph{Return value}: 8606The return value is of @code{INTEGER(kind=4)} type. 8607 8608@item @emph{Example}: 8609@smallexample 8610program test_irand 8611 integer,parameter :: seed = 86456 8612 8613 call srand(seed) 8614 print *, irand(), irand(), irand(), irand() 8615 print *, irand(seed), irand(), irand(), irand() 8616end program test_irand 8617@end smallexample 8618 8619@end table 8620 8621 8622 8623@node IS_CONTIGUOUS 8624@section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous 8625@fnindex IS_IOSTAT_EOR 8626@cindex array, contiguity 8627 8628@table @asis 8629@item @emph{Description}: 8630@code{IS_CONTIGUOUS} tests whether an array is contiguous. 8631 8632@item @emph{Standard}: 8633Fortran 2008 and later 8634 8635@item @emph{Class}: 8636Inquiry function 8637 8638@item @emph{Syntax}: 8639@code{RESULT = IS_CONTIGUOUS(ARRAY)} 8640 8641@item @emph{Arguments}: 8642@multitable @columnfractions .15 .70 8643@item @var{ARRAY} @tab Shall be an array of any type. 8644@end multitable 8645 8646@item @emph{Return value}: 8647Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8648@var{ARRAY} is contiguous and false otherwise. 8649 8650@item @emph{Example}: 8651@smallexample 8652program test 8653 integer :: a(10) 8654 a = [1,2,3,4,5,6,7,8,9,10] 8655 call sub (a) ! every element, is contiguous 8656 call sub (a(::2)) ! every other element, is noncontiguous 8657contains 8658 subroutine sub (x) 8659 integer :: x(:) 8660 if (is_contiguous (x)) then 8661 write (*,*) 'X is contiguous' 8662 else 8663 write (*,*) 'X is not contiguous' 8664 end if 8665 end subroutine sub 8666end program test 8667@end smallexample 8668@end table 8669 8670 8671 8672@node IS_IOSTAT_END 8673@section @code{IS_IOSTAT_END} --- Test for end-of-file value 8674@fnindex IS_IOSTAT_END 8675@cindex @code{IOSTAT}, end of file 8676 8677@table @asis 8678@item @emph{Description}: 8679@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O 8680status ``end of file''. The function is equivalent to comparing the variable 8681with the @code{IOSTAT_END} parameter of the intrinsic module 8682@code{ISO_FORTRAN_ENV}. 8683 8684@item @emph{Standard}: 8685Fortran 2003 and later 8686 8687@item @emph{Class}: 8688Elemental function 8689 8690@item @emph{Syntax}: 8691@code{RESULT = IS_IOSTAT_END(I)} 8692 8693@item @emph{Arguments}: 8694@multitable @columnfractions .15 .70 8695@item @var{I} @tab Shall be of the type @code{INTEGER}. 8696@end multitable 8697 8698@item @emph{Return value}: 8699Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8700@var{I} has the value which indicates an end of file condition for 8701@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8702 8703@item @emph{Example}: 8704@smallexample 8705PROGRAM iostat 8706 IMPLICIT NONE 8707 INTEGER :: stat, i 8708 OPEN(88, FILE='test.dat') 8709 READ(88, *, IOSTAT=stat) i 8710 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE' 8711END PROGRAM 8712@end smallexample 8713@end table 8714 8715 8716 8717@node IS_IOSTAT_EOR 8718@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value 8719@fnindex IS_IOSTAT_EOR 8720@cindex @code{IOSTAT}, end of record 8721 8722@table @asis 8723@item @emph{Description}: 8724@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O 8725status ``end of record''. The function is equivalent to comparing the 8726variable with the @code{IOSTAT_EOR} parameter of the intrinsic module 8727@code{ISO_FORTRAN_ENV}. 8728 8729@item @emph{Standard}: 8730Fortran 2003 and later 8731 8732@item @emph{Class}: 8733Elemental function 8734 8735@item @emph{Syntax}: 8736@code{RESULT = IS_IOSTAT_EOR(I)} 8737 8738@item @emph{Arguments}: 8739@multitable @columnfractions .15 .70 8740@item @var{I} @tab Shall be of the type @code{INTEGER}. 8741@end multitable 8742 8743@item @emph{Return value}: 8744Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8745@var{I} has the value which indicates an end of file condition for 8746@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8747 8748@item @emph{Example}: 8749@smallexample 8750PROGRAM iostat 8751 IMPLICIT NONE 8752 INTEGER :: stat, i(50) 8753 OPEN(88, FILE='test.dat', FORM='UNFORMATTED') 8754 READ(88, IOSTAT=stat) i 8755 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD' 8756END PROGRAM 8757@end smallexample 8758@end table 8759 8760 8761@node ISATTY 8762@section @code{ISATTY} --- Whether a unit is a terminal device. 8763@fnindex ISATTY 8764@cindex system, terminal 8765 8766@table @asis 8767@item @emph{Description}: 8768Determine whether a unit is connected to a terminal device. 8769 8770@item @emph{Standard}: 8771GNU extension 8772 8773@item @emph{Class}: 8774Function 8775 8776@item @emph{Syntax}: 8777@code{RESULT = ISATTY(UNIT)} 8778 8779@item @emph{Arguments}: 8780@multitable @columnfractions .15 .70 8781@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 8782@end multitable 8783 8784@item @emph{Return value}: 8785Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal 8786device, @code{.FALSE.} otherwise. 8787 8788@item @emph{Example}: 8789@smallexample 8790PROGRAM test_isatty 8791 INTEGER(kind=1) :: unit 8792 DO unit = 1, 10 8793 write(*,*) isatty(unit=unit) 8794 END DO 8795END PROGRAM 8796@end smallexample 8797@item @emph{See also}: 8798@ref{TTYNAM} 8799@end table 8800 8801 8802 8803@node ISHFT 8804@section @code{ISHFT} --- Shift bits 8805@fnindex ISHFT 8806@fnindex BSHFT 8807@fnindex IISHFT 8808@fnindex JISHFT 8809@fnindex KISHFT 8810@cindex bits, shift 8811 8812@table @asis 8813@item @emph{Description}: 8814@code{ISHFT} returns a value corresponding to @var{I} with all of the 8815bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than 8816zero corresponds to a left shift, a value of zero corresponds to no 8817shift, and a value less than zero corresponds to a right shift. If the 8818absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the 8819value is undefined. Bits shifted out from the left end or right end are 8820lost; zeros are shifted in from the opposite end. 8821 8822@item @emph{Standard}: 8823Fortran 90 and later, has overloads that are GNU extensions 8824 8825@item @emph{Class}: 8826Elemental function 8827 8828@item @emph{Syntax}: 8829@code{RESULT = ISHFT(I, SHIFT)} 8830 8831@item @emph{Arguments}: 8832@multitable @columnfractions .15 .70 8833@item @var{I} @tab The type shall be @code{INTEGER}. 8834@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8835@end multitable 8836 8837@item @emph{Return value}: 8838The return value is of type @code{INTEGER} and of the same kind as 8839@var{I}. 8840 8841@item @emph{Specific names}: 8842@multitable @columnfractions .20 .20 .20 .25 8843@item Name @tab Argument @tab Return type @tab Standard 8844@item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8845@item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8846@item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8847@item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8848@item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8849@end multitable 8850 8851@item @emph{See also}: 8852@ref{ISHFTC} 8853@end table 8854 8855 8856 8857@node ISHFTC 8858@section @code{ISHFTC} --- Shift bits circularly 8859@fnindex ISHFTC 8860@fnindex BSHFTC 8861@fnindex IISHFTC 8862@fnindex JISHFTC 8863@fnindex KISHFTC 8864@cindex bits, shift circular 8865 8866@table @asis 8867@item @emph{Description}: 8868@code{ISHFTC} returns a value corresponding to @var{I} with the 8869rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that 8870is, bits shifted out one end are shifted into the opposite end. A value 8871of @var{SHIFT} greater than zero corresponds to a left shift, a value of 8872zero corresponds to no shift, and a value less than zero corresponds to 8873a right shift. The absolute value of @var{SHIFT} must be less than 8874@var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be 8875equivalent to @code{BIT_SIZE(I)}. 8876 8877@item @emph{Standard}: 8878Fortran 90 and later, has overloads that are GNU extensions 8879 8880@item @emph{Class}: 8881Elemental function 8882 8883@item @emph{Syntax}: 8884@code{RESULT = ISHFTC(I, SHIFT [, SIZE])} 8885 8886@item @emph{Arguments}: 8887@multitable @columnfractions .15 .70 8888@item @var{I} @tab The type shall be @code{INTEGER}. 8889@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8890@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER}; 8891the value must be greater than zero and less than or equal to 8892@code{BIT_SIZE(I)}. 8893@end multitable 8894 8895@item @emph{Return value}: 8896The return value is of type @code{INTEGER} and of the same kind as 8897@var{I}. 8898 8899@item @emph{Specific names}: 8900@multitable @columnfractions .20 .20 .20 .25 8901@item Name @tab Argument @tab Return type @tab Standard 8902@item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8903@item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8904@item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8905@item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8906@item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8907@end multitable 8908 8909@item @emph{See also}: 8910@ref{ISHFT} 8911@end table 8912 8913 8914 8915@node ISNAN 8916@section @code{ISNAN} --- Test for a NaN 8917@fnindex ISNAN 8918@cindex IEEE, ISNAN 8919 8920@table @asis 8921@item @emph{Description}: 8922@code{ISNAN} tests whether a floating-point value is an IEEE 8923Not-a-Number (NaN). 8924@item @emph{Standard}: 8925GNU extension 8926 8927@item @emph{Class}: 8928Elemental function 8929 8930@item @emph{Syntax}: 8931@code{ISNAN(X)} 8932 8933@item @emph{Arguments}: 8934@multitable @columnfractions .15 .70 8935@item @var{X} @tab Variable of the type @code{REAL}. 8936 8937@end multitable 8938 8939@item @emph{Return value}: 8940Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE} 8941if @var{X} is a NaN and @code{FALSE} otherwise. 8942 8943@item @emph{Example}: 8944@smallexample 8945program test_nan 8946 implicit none 8947 real :: x 8948 x = -1.0 8949 x = sqrt(x) 8950 if (isnan(x)) stop '"x" is a NaN' 8951end program test_nan 8952@end smallexample 8953@end table 8954 8955 8956 8957@node ITIME 8958@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) 8959@fnindex ITIME 8960@cindex time, current 8961@cindex current time 8962 8963@table @asis 8964@item @emph{Description}: 8965@code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the 8966current local time. The hour (in the range 1-24), minute (in the range 1-60), 8967and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES}, 8968respectively. 8969 8970This intrinsic routine is provided for backwards compatibility with 8971GNU Fortran 77. In new code, programmers should consider the use of 8972the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 8973standard. 8974 8975@item @emph{Standard}: 8976GNU extension 8977 8978@item @emph{Class}: 8979Subroutine 8980 8981@item @emph{Syntax}: 8982@code{CALL ITIME(VALUES)} 8983 8984@item @emph{Arguments}: 8985@multitable @columnfractions .15 .70 8986@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} 8987and the kind shall be the default integer kind. 8988@end multitable 8989 8990@item @emph{Return value}: 8991Does not return anything. 8992 8993 8994@item @emph{Example}: 8995@smallexample 8996program test_itime 8997 integer, dimension(3) :: tarray 8998 call itime(tarray) 8999 print *, tarray(1) 9000 print *, tarray(2) 9001 print *, tarray(3) 9002end program test_itime 9003@end smallexample 9004 9005@item @emph{See also}: 9006@ref{DATE_AND_TIME} 9007@end table 9008 9009 9010 9011@node KILL 9012@section @code{KILL} --- Send a signal to a process 9013@fnindex KILL 9014 9015@table @asis 9016@item @emph{Description}: 9017Sends the signal specified by @var{SIG} to the process @var{PID}. 9018See @code{kill(2)}. 9019 9020This intrinsic is provided in both subroutine and function forms; 9021however, only one form can be used in any given program unit. 9022@item @emph{Standard}: 9023GNU extension 9024 9025@item @emph{Standard}: 9026GNU extension 9027 9028@item @emph{Class}: 9029Subroutine, function 9030 9031@item @emph{Syntax}: 9032@multitable @columnfractions .80 9033@item @code{CALL KILL(PID, SIG [, STATUS])} 9034@item @code{STATUS = KILL(PID, SIG)} 9035@end multitable 9036 9037@item @emph{Arguments}: 9038@multitable @columnfractions .15 .70 9039@item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 9040@item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 9041@item @var{STATUS} @tab [Subroutine](Optional) 9042Shall be a scalar @code{INTEGER}. 9043Returns 0 on success; otherwise a system-specific error code is returned. 9044@item @var{STATUS} @tab [Function] The kind type parameter is that of 9045@code{pid}. 9046Returns 0 on success; otherwise a system-specific error code is returned. 9047@end multitable 9048 9049@item @emph{See also}: 9050@ref{ABORT}, @gol 9051@ref{EXIT} 9052@end table 9053 9054 9055@node KIND 9056@section @code{KIND} --- Kind of an entity 9057@fnindex KIND 9058@cindex kind 9059 9060@table @asis 9061@item @emph{Description}: 9062@code{KIND(X)} returns the kind value of the entity @var{X}. 9063 9064@item @emph{Standard}: 9065Fortran 95 and later 9066 9067@item @emph{Class}: 9068Inquiry function 9069 9070@item @emph{Syntax}: 9071@code{K = KIND(X)} 9072 9073@item @emph{Arguments}: 9074@multitable @columnfractions .15 .70 9075@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER}, 9076@code{REAL}, @code{COMPLEX} or @code{CHARACTER}. It may be scalar or 9077array valued. 9078@end multitable 9079 9080@item @emph{Return value}: 9081The return value is a scalar of type @code{INTEGER} and of the default 9082integer kind. 9083 9084@item @emph{Example}: 9085@smallexample 9086program test_kind 9087 integer,parameter :: kc = kind(' ') 9088 integer,parameter :: kl = kind(.true.) 9089 9090 print *, "The default character kind is ", kc 9091 print *, "The default logical kind is ", kl 9092end program test_kind 9093@end smallexample 9094 9095@end table 9096 9097 9098 9099@node LBOUND 9100@section @code{LBOUND} --- Lower dimension bounds of an array 9101@fnindex LBOUND 9102@cindex array, lower bound 9103 9104@table @asis 9105@item @emph{Description}: 9106Returns the lower bounds of an array, or a single lower bound 9107along the @var{DIM} dimension. 9108@item @emph{Standard}: 9109Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 9110 9111@item @emph{Class}: 9112Inquiry function 9113 9114@item @emph{Syntax}: 9115@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])} 9116 9117@item @emph{Arguments}: 9118@multitable @columnfractions .15 .70 9119@item @var{ARRAY} @tab Shall be an array, of any type. 9120@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 9121@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9122expression indicating the kind parameter of the result. 9123@end multitable 9124 9125@item @emph{Return value}: 9126The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9127@var{KIND} is absent, the return value is of default integer kind. 9128If @var{DIM} is absent, the result is an array of the lower bounds of 9129@var{ARRAY}. If @var{DIM} is present, the result is a scalar 9130corresponding to the lower bound of the array along that dimension. If 9131@var{ARRAY} is an expression rather than a whole array or array 9132structure component, or if it has a zero extent along the relevant 9133dimension, the lower bound is taken to be 1. 9134 9135@item @emph{See also}: 9136@ref{UBOUND}, @gol 9137@ref{LCOBOUND} 9138@end table 9139 9140 9141 9142@node LCOBOUND 9143@section @code{LCOBOUND} --- Lower codimension bounds of an array 9144@fnindex LCOBOUND 9145@cindex coarray, lower bound 9146 9147@table @asis 9148@item @emph{Description}: 9149Returns the lower bounds of a coarray, or a single lower cobound 9150along the @var{DIM} codimension. 9151@item @emph{Standard}: 9152Fortran 2008 and later 9153 9154@item @emph{Class}: 9155Inquiry function 9156 9157@item @emph{Syntax}: 9158@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])} 9159 9160@item @emph{Arguments}: 9161@multitable @columnfractions .15 .70 9162@item @var{ARRAY} @tab Shall be an coarray, of any type. 9163@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 9164@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9165expression indicating the kind parameter of the result. 9166@end multitable 9167 9168@item @emph{Return value}: 9169The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9170@var{KIND} is absent, the return value is of default integer kind. 9171If @var{DIM} is absent, the result is an array of the lower cobounds of 9172@var{COARRAY}. If @var{DIM} is present, the result is a scalar 9173corresponding to the lower cobound of the array along that codimension. 9174 9175@item @emph{See also}: 9176@ref{UCOBOUND}, @gol 9177@ref{LBOUND} 9178@end table 9179 9180 9181 9182@node LEADZ 9183@section @code{LEADZ} --- Number of leading zero bits of an integer 9184@fnindex LEADZ 9185@cindex zero bits 9186 9187@table @asis 9188@item @emph{Description}: 9189@code{LEADZ} returns the number of leading zero bits of an integer. 9190 9191@item @emph{Standard}: 9192Fortran 2008 and later 9193 9194@item @emph{Class}: 9195Elemental function 9196 9197@item @emph{Syntax}: 9198@code{RESULT = LEADZ(I)} 9199 9200@item @emph{Arguments}: 9201@multitable @columnfractions .15 .70 9202@item @var{I} @tab Shall be of type @code{INTEGER}. 9203@end multitable 9204 9205@item @emph{Return value}: 9206The type of the return value is the default @code{INTEGER}. 9207If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 9208 9209@item @emph{Example}: 9210@smallexample 9211PROGRAM test_leadz 9212 WRITE (*,*) BIT_SIZE(1) ! prints 32 9213 WRITE (*,*) LEADZ(1) ! prints 31 9214END PROGRAM 9215@end smallexample 9216 9217@item @emph{See also}: 9218@ref{BIT_SIZE}, @gol 9219@ref{TRAILZ}, @gol 9220@ref{POPCNT}, @gol 9221@ref{POPPAR} 9222@end table 9223 9224 9225 9226@node LEN 9227@section @code{LEN} --- Length of a character entity 9228@fnindex LEN 9229@cindex string, length 9230 9231@table @asis 9232@item @emph{Description}: 9233Returns the length of a character string. If @var{STRING} is an array, 9234the length of an element of @var{STRING} is returned. Note that 9235@var{STRING} need not be defined when this intrinsic is invoked, since 9236only the length, not the content, of @var{STRING} is needed. 9237 9238@item @emph{Standard}: 9239Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 9240 9241@item @emph{Class}: 9242Inquiry function 9243 9244@item @emph{Syntax}: 9245@code{L = LEN(STRING [, KIND])} 9246 9247@item @emph{Arguments}: 9248@multitable @columnfractions .15 .70 9249@item @var{STRING} @tab Shall be a scalar or array of type 9250@code{CHARACTER}, with @code{INTENT(IN)} 9251@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9252expression indicating the kind parameter of the result. 9253@end multitable 9254 9255@item @emph{Return value}: 9256The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9257@var{KIND} is absent, the return value is of default integer kind. 9258 9259 9260@item @emph{Specific names}: 9261@multitable @columnfractions .20 .20 .20 .25 9262@item Name @tab Argument @tab Return type @tab Standard 9263@item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later 9264@end multitable 9265 9266 9267@item @emph{See also}: 9268@ref{LEN_TRIM}, @gol 9269@ref{ADJUSTL}, @gol 9270@ref{ADJUSTR} 9271@end table 9272 9273 9274 9275@node LEN_TRIM 9276@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters 9277@fnindex LEN_TRIM 9278@cindex string, length, without trailing whitespace 9279 9280@table @asis 9281@item @emph{Description}: 9282Returns the length of a character string, ignoring any trailing blanks. 9283 9284@item @emph{Standard}: 9285Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 9286 9287@item @emph{Class}: 9288Elemental function 9289 9290@item @emph{Syntax}: 9291@code{RESULT = LEN_TRIM(STRING [, KIND])} 9292 9293@item @emph{Arguments}: 9294@multitable @columnfractions .15 .70 9295@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9296with @code{INTENT(IN)} 9297@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9298expression indicating the kind parameter of the result. 9299@end multitable 9300 9301@item @emph{Return value}: 9302The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9303@var{KIND} is absent, the return value is of default integer kind. 9304 9305@item @emph{See also}: 9306@ref{LEN}, @gol 9307@ref{ADJUSTL}, @gol 9308@ref{ADJUSTR} 9309@end table 9310 9311 9312 9313@node LGE 9314@section @code{LGE} --- Lexical greater than or equal 9315@fnindex LGE 9316@cindex lexical comparison of strings 9317@cindex string, comparison 9318 9319@table @asis 9320@item @emph{Description}: 9321Determines whether one string is lexically greater than or equal to 9322another string, where the two strings are interpreted as containing 9323ASCII character codes. If the String A and String B are not the same 9324length, the shorter is compared as if spaces were appended to it to form 9325a value that has the same length as the longer. 9326 9327In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9328@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9329operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9330that the latter use the processor's character ordering (which is not 9331ASCII on some targets), whereas the former always use the ASCII 9332ordering. 9333 9334@item @emph{Standard}: 9335Fortran 77 and later 9336 9337@item @emph{Class}: 9338Elemental function 9339 9340@item @emph{Syntax}: 9341@code{RESULT = LGE(STRING_A, STRING_B)} 9342 9343@item @emph{Arguments}: 9344@multitable @columnfractions .15 .70 9345@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9346@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9347@end multitable 9348 9349@item @emph{Return value}: 9350Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.} 9351otherwise, based on the ASCII ordering. 9352 9353@item @emph{Specific names}: 9354@multitable @columnfractions .20 .20 .20 .25 9355@item Name @tab Argument @tab Return type @tab Standard 9356@item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9357@end multitable 9358 9359@item @emph{See also}: 9360@ref{LGT}, @gol 9361@ref{LLE}, @gol 9362@ref{LLT} 9363@end table 9364 9365 9366 9367@node LGT 9368@section @code{LGT} --- Lexical greater than 9369@fnindex LGT 9370@cindex lexical comparison of strings 9371@cindex string, comparison 9372 9373@table @asis 9374@item @emph{Description}: 9375Determines whether one string is lexically greater than another string, 9376where the two strings are interpreted as containing ASCII character 9377codes. If the String A and String B are not the same length, the 9378shorter is compared as if spaces were appended to it to form a value 9379that has the same length as the longer. 9380 9381In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9382@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9383operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9384that the latter use the processor's character ordering (which is not 9385ASCII on some targets), whereas the former always use the ASCII 9386ordering. 9387 9388@item @emph{Standard}: 9389Fortran 77 and later 9390 9391@item @emph{Class}: 9392Elemental function 9393 9394@item @emph{Syntax}: 9395@code{RESULT = LGT(STRING_A, STRING_B)} 9396 9397@item @emph{Arguments}: 9398@multitable @columnfractions .15 .70 9399@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9400@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9401@end multitable 9402 9403@item @emph{Return value}: 9404Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.} 9405otherwise, based on the ASCII ordering. 9406 9407@item @emph{Specific names}: 9408@multitable @columnfractions .20 .20 .20 .25 9409@item Name @tab Argument @tab Return type @tab Standard 9410@item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9411@end multitable 9412 9413@item @emph{See also}: 9414@ref{LGE}, @gol 9415@ref{LLE}, @gol 9416@ref{LLT} 9417@end table 9418 9419 9420 9421@node LINK 9422@section @code{LINK} --- Create a hard link 9423@fnindex LINK 9424@cindex file system, create link 9425@cindex file system, hard link 9426 9427@table @asis 9428@item @emph{Description}: 9429Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null 9430character (@code{CHAR(0)}) can be used to mark the end of the names in 9431@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 9432names are ignored. If the @var{STATUS} argument is supplied, it 9433contains 0 on success or a nonzero error code upon return; see 9434@code{link(2)}. 9435 9436This intrinsic is provided in both subroutine and function forms; 9437however, only one form can be used in any given program unit. 9438 9439@item @emph{Standard}: 9440GNU extension 9441 9442@item @emph{Class}: 9443Subroutine, function 9444 9445@item @emph{Syntax}: 9446@multitable @columnfractions .80 9447@item @code{CALL LINK(PATH1, PATH2 [, STATUS])} 9448@item @code{STATUS = LINK(PATH1, PATH2)} 9449@end multitable 9450 9451@item @emph{Arguments}: 9452@multitable @columnfractions .15 .70 9453@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 9454@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 9455@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 9456@end multitable 9457 9458@item @emph{See also}: 9459@ref{SYMLNK}, @gol 9460@ref{UNLINK} 9461@end table 9462 9463 9464 9465@node LLE 9466@section @code{LLE} --- Lexical less than or equal 9467@fnindex LLE 9468@cindex lexical comparison of strings 9469@cindex string, comparison 9470 9471@table @asis 9472@item @emph{Description}: 9473Determines whether one string is lexically less than or equal to another 9474string, where the two strings are interpreted as containing ASCII 9475character codes. If the String A and String B are not the same length, 9476the shorter is compared as if spaces were appended to it to form a value 9477that has the same length as the longer. 9478 9479In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9480@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9481operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9482that the latter use the processor's character ordering (which is not 9483ASCII on some targets), whereas the former always use the ASCII 9484ordering. 9485 9486@item @emph{Standard}: 9487Fortran 77 and later 9488 9489@item @emph{Class}: 9490Elemental function 9491 9492@item @emph{Syntax}: 9493@code{RESULT = LLE(STRING_A, STRING_B)} 9494 9495@item @emph{Arguments}: 9496@multitable @columnfractions .15 .70 9497@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9498@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9499@end multitable 9500 9501@item @emph{Return value}: 9502Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.} 9503otherwise, based on the ASCII ordering. 9504 9505@item @emph{Specific names}: 9506@multitable @columnfractions .20 .20 .20 .25 9507@item Name @tab Argument @tab Return type @tab Standard 9508@item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9509@end multitable 9510 9511@item @emph{See also}: 9512@ref{LGE}, @gol 9513@ref{LGT}, @gol 9514@ref{LLT} 9515@end table 9516 9517 9518 9519@node LLT 9520@section @code{LLT} --- Lexical less than 9521@fnindex LLT 9522@cindex lexical comparison of strings 9523@cindex string, comparison 9524 9525@table @asis 9526@item @emph{Description}: 9527Determines whether one string is lexically less than another string, 9528where the two strings are interpreted as containing ASCII character 9529codes. If the String A and String B are not the same length, the 9530shorter is compared as if spaces were appended to it to form a value 9531that has the same length as the longer. 9532 9533In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9534@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9535operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9536that the latter use the processor's character ordering (which is not 9537ASCII on some targets), whereas the former always use the ASCII 9538ordering. 9539 9540@item @emph{Standard}: 9541Fortran 77 and later 9542 9543@item @emph{Class}: 9544Elemental function 9545 9546@item @emph{Syntax}: 9547@code{RESULT = LLT(STRING_A, STRING_B)} 9548 9549@item @emph{Arguments}: 9550@multitable @columnfractions .15 .70 9551@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9552@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9553@end multitable 9554 9555@item @emph{Return value}: 9556Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.} 9557otherwise, based on the ASCII ordering. 9558 9559@item @emph{Specific names}: 9560@multitable @columnfractions .20 .20 .20 .25 9561@item Name @tab Argument @tab Return type @tab Standard 9562@item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9563@end multitable 9564 9565@item @emph{See also}: 9566@ref{LGE}, @gol 9567@ref{LGT}, @gol 9568@ref{LLE} 9569@end table 9570 9571 9572 9573@node LNBLNK 9574@section @code{LNBLNK} --- Index of the last non-blank character in a string 9575@fnindex LNBLNK 9576@cindex string, find non-blank character 9577 9578@table @asis 9579@item @emph{Description}: 9580Returns the length of a character string, ignoring any trailing blanks. 9581This is identical to the standard @code{LEN_TRIM} intrinsic, and is only 9582included for backwards compatibility. 9583 9584@item @emph{Standard}: 9585GNU extension 9586 9587@item @emph{Class}: 9588Elemental function 9589 9590@item @emph{Syntax}: 9591@code{RESULT = LNBLNK(STRING)} 9592 9593@item @emph{Arguments}: 9594@multitable @columnfractions .15 .70 9595@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9596with @code{INTENT(IN)} 9597@end multitable 9598 9599@item @emph{Return value}: 9600The return value is of @code{INTEGER(kind=4)} type. 9601 9602@item @emph{See also}: 9603@ref{INDEX intrinsic}, @gol 9604@ref{LEN_TRIM} 9605@end table 9606 9607 9608 9609@node LOC 9610@section @code{LOC} --- Returns the address of a variable 9611@fnindex LOC 9612@cindex location of a variable in memory 9613 9614@table @asis 9615@item @emph{Description}: 9616@code{LOC(X)} returns the address of @var{X} as an integer. 9617 9618@item @emph{Standard}: 9619GNU extension 9620 9621@item @emph{Class}: 9622Inquiry function 9623 9624@item @emph{Syntax}: 9625@code{RESULT = LOC(X)} 9626 9627@item @emph{Arguments}: 9628@multitable @columnfractions .15 .70 9629@item @var{X} @tab Variable of any type. 9630@end multitable 9631 9632@item @emph{Return value}: 9633The return value is of type @code{INTEGER}, with a @code{KIND} 9634corresponding to the size (in bytes) of a memory address on the target 9635machine. 9636 9637@item @emph{Example}: 9638@smallexample 9639program test_loc 9640 integer :: i 9641 real :: r 9642 i = loc(r) 9643 print *, i 9644end program test_loc 9645@end smallexample 9646@end table 9647 9648 9649 9650@node LOG 9651@section @code{LOG} --- Natural logarithm function 9652@fnindex LOG 9653@fnindex ALOG 9654@fnindex DLOG 9655@fnindex CLOG 9656@fnindex ZLOG 9657@fnindex CDLOG 9658@cindex exponential function, inverse 9659@cindex logarithm function 9660@cindex natural logarithm function 9661 9662@table @asis 9663@item @emph{Description}: 9664@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the 9665logarithm to the base @math{e}. 9666 9667@item @emph{Standard}: 9668Fortran 77 and later, has GNU extensions 9669 9670@item @emph{Class}: 9671Elemental function 9672 9673@item @emph{Syntax}: 9674@code{RESULT = LOG(X)} 9675 9676@item @emph{Arguments}: 9677@multitable @columnfractions .15 .70 9678@item @var{X} @tab The type shall be @code{REAL} or 9679@code{COMPLEX}. 9680@end multitable 9681 9682@item @emph{Return value}: 9683The return value is of type @code{REAL} or @code{COMPLEX}. 9684The kind type parameter is the same as @var{X}. 9685If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range 9686@math{-\pi < \omega \leq \pi}. 9687 9688@item @emph{Example}: 9689@smallexample 9690program test_log 9691 real(8) :: x = 2.7182818284590451_8 9692 complex :: z = (1.0, 2.0) 9693 x = log(x) ! will yield (approximately) 1 9694 z = log(z) 9695end program test_log 9696@end smallexample 9697 9698@item @emph{Specific names}: 9699@multitable @columnfractions .20 .20 .20 .25 9700@item Name @tab Argument @tab Return type @tab Standard 9701@item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later 9702@item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later 9703@item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later 9704@item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 9705@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 9706@end multitable 9707@end table 9708 9709 9710 9711@node LOG10 9712@section @code{LOG10} --- Base 10 logarithm function 9713@fnindex LOG10 9714@fnindex ALOG10 9715@fnindex DLOG10 9716@cindex exponential function, inverse 9717@cindex logarithm function with base 10 9718@cindex base 10 logarithm function 9719 9720@table @asis 9721@item @emph{Description}: 9722@code{LOG10(X)} computes the base 10 logarithm of @var{X}. 9723 9724@item @emph{Standard}: 9725Fortran 77 and later 9726 9727@item @emph{Class}: 9728Elemental function 9729 9730@item @emph{Syntax}: 9731@code{RESULT = LOG10(X)} 9732 9733@item @emph{Arguments}: 9734@multitable @columnfractions .15 .70 9735@item @var{X} @tab The type shall be @code{REAL}. 9736@end multitable 9737 9738@item @emph{Return value}: 9739The return value is of type @code{REAL} or @code{COMPLEX}. 9740The kind type parameter is the same as @var{X}. 9741 9742@item @emph{Example}: 9743@smallexample 9744program test_log10 9745 real(8) :: x = 10.0_8 9746 x = log10(x) 9747end program test_log10 9748@end smallexample 9749 9750@item @emph{Specific names}: 9751@multitable @columnfractions .20 .20 .20 .25 9752@item Name @tab Argument @tab Return type @tab Standard 9753@item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 9754@item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 9755@end multitable 9756@end table 9757 9758 9759 9760@node LOG_GAMMA 9761@section @code{LOG_GAMMA} --- Logarithm of the Gamma function 9762@fnindex LOG_GAMMA 9763@fnindex LGAMMA 9764@fnindex ALGAMA 9765@fnindex DLGAMA 9766@cindex Gamma function, logarithm of 9767 9768@table @asis 9769@item @emph{Description}: 9770@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value 9771of the Gamma (@math{\Gamma}) function. 9772 9773@item @emph{Standard}: 9774Fortran 2008 and later 9775 9776@item @emph{Class}: 9777Elemental function 9778 9779@item @emph{Syntax}: 9780@code{X = LOG_GAMMA(X)} 9781 9782@item @emph{Arguments}: 9783@multitable @columnfractions .15 .70 9784@item @var{X} @tab Shall be of type @code{REAL} and neither zero 9785nor a negative integer. 9786@end multitable 9787 9788@item @emph{Return value}: 9789The return value is of type @code{REAL} of the same kind as @var{X}. 9790 9791@item @emph{Example}: 9792@smallexample 9793program test_log_gamma 9794 real :: x = 1.0 9795 x = lgamma(x) ! returns 0.0 9796end program test_log_gamma 9797@end smallexample 9798 9799@item @emph{Specific names}: 9800@multitable @columnfractions .20 .20 .20 .25 9801@item Name @tab Argument @tab Return type @tab Standard 9802@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 9803@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 9804@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 9805@end multitable 9806 9807@item @emph{See also}: 9808Gamma function: @gol 9809@ref{GAMMA} 9810@end table 9811 9812 9813 9814@node LOGICAL 9815@section @code{LOGICAL} --- Convert to logical type 9816@fnindex LOGICAL 9817@cindex conversion, to logical 9818 9819@table @asis 9820@item @emph{Description}: 9821Converts one kind of @code{LOGICAL} variable to another. 9822 9823@item @emph{Standard}: 9824Fortran 90 and later 9825 9826@item @emph{Class}: 9827Elemental function 9828 9829@item @emph{Syntax}: 9830@code{RESULT = LOGICAL(L [, KIND])} 9831 9832@item @emph{Arguments}: 9833@multitable @columnfractions .15 .70 9834@item @var{L} @tab The type shall be @code{LOGICAL}. 9835@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9836expression indicating the kind parameter of the result. 9837@end multitable 9838 9839@item @emph{Return value}: 9840The return value is a @code{LOGICAL} value equal to @var{L}, with a 9841kind corresponding to @var{KIND}, or of the default logical kind if 9842@var{KIND} is not given. 9843 9844@item @emph{See also}: 9845@ref{INT}, @gol 9846@ref{REAL}, @gol 9847@ref{CMPLX} 9848@end table 9849 9850 9851 9852@node LONG 9853@section @code{LONG} --- Convert to integer type 9854@fnindex LONG 9855@cindex conversion, to integer 9856 9857@table @asis 9858@item @emph{Description}: 9859Convert to a @code{KIND=4} integer type, which is the same size as a C 9860@code{long} integer. This is equivalent to the standard @code{INT} 9861intrinsic with an optional argument of @code{KIND=4}, and is only 9862included for backwards compatibility. 9863 9864@item @emph{Standard}: 9865GNU extension 9866 9867@item @emph{Class}: 9868Elemental function 9869 9870@item @emph{Syntax}: 9871@code{RESULT = LONG(A)} 9872 9873@item @emph{Arguments}: 9874@multitable @columnfractions .15 .70 9875@item @var{A} @tab Shall be of type @code{INTEGER}, 9876@code{REAL}, or @code{COMPLEX}. 9877@end multitable 9878 9879@item @emph{Return value}: 9880The return value is a @code{INTEGER(4)} variable. 9881 9882@item @emph{See also}: 9883@ref{INT}, @gol 9884@ref{INT2}, @gol 9885@ref{INT8} 9886@end table 9887 9888 9889 9890@node LSHIFT 9891@section @code{LSHIFT} --- Left shift bits 9892@fnindex LSHIFT 9893@cindex bits, shift left 9894 9895@table @asis 9896@item @emph{Description}: 9897@code{LSHIFT} returns a value corresponding to @var{I} with all of the 9898bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be 9899nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 9900the result value is undefined. Bits shifted out from the left end are 9901lost; zeros are shifted in from the opposite end. 9902 9903This function has been superseded by the @code{ISHFT} intrinsic, which 9904is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic, 9905which is standard in Fortran 2008 and later. 9906 9907@item @emph{Standard}: 9908GNU extension 9909 9910@item @emph{Class}: 9911Elemental function 9912 9913@item @emph{Syntax}: 9914@code{RESULT = LSHIFT(I, SHIFT)} 9915 9916@item @emph{Arguments}: 9917@multitable @columnfractions .15 .70 9918@item @var{I} @tab The type shall be @code{INTEGER}. 9919@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 9920@end multitable 9921 9922@item @emph{Return value}: 9923The return value is of type @code{INTEGER} and of the same kind as 9924@var{I}. 9925 9926@item @emph{See also}: 9927@ref{ISHFT}, @gol 9928@ref{ISHFTC}, @gol 9929@ref{RSHIFT}, @gol 9930@ref{SHIFTA}, @gol 9931@ref{SHIFTL}, @gol 9932@ref{SHIFTR} 9933@end table 9934 9935 9936 9937@node LSTAT 9938@section @code{LSTAT} --- Get file status 9939@fnindex LSTAT 9940@cindex file system, file status 9941 9942@table @asis 9943@item @emph{Description}: 9944@code{LSTAT} is identical to @ref{STAT}, except that if path is a 9945symbolic link, then the link itself is statted, not the file that it 9946refers to. 9947 9948The elements in @code{VALUES} are the same as described by @ref{STAT}. 9949 9950This intrinsic is provided in both subroutine and function forms; 9951however, only one form can be used in any given program unit. 9952 9953@item @emph{Standard}: 9954GNU extension 9955 9956@item @emph{Class}: 9957Subroutine, function 9958 9959@item @emph{Syntax}: 9960@multitable @columnfractions .80 9961@item @code{CALL LSTAT(NAME, VALUES [, STATUS])} 9962@item @code{STATUS = LSTAT(NAME, VALUES)} 9963@end multitable 9964 9965@item @emph{Arguments}: 9966@multitable @columnfractions .15 .70 9967@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default 9968kind, a valid path within the file system. 9969@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 9970@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. 9971Returns 0 on success and a system specific error code otherwise. 9972@end multitable 9973 9974@item @emph{Example}: 9975See @ref{STAT} for an example. 9976 9977@item @emph{See also}: 9978To stat an open file: @gol 9979@ref{FSTAT} @gol 9980To stat a file: @gol 9981@ref{STAT} 9982@end table 9983 9984 9985 9986@node LTIME 9987@section @code{LTIME} --- Convert time to local time info 9988@fnindex LTIME 9989@cindex time, conversion to local time info 9990 9991@table @asis 9992@item @emph{Description}: 9993Given a system time value @var{TIME} (as provided by the @ref{TIME} 9994intrinsic), fills @var{VALUES} with values extracted from it appropriate 9995to the local time zone using @code{localtime(3)}. 9996 9997This intrinsic routine is provided for backwards compatibility with 9998GNU Fortran 77. In new code, programmers should consider the use of 9999the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 10000standard. 10001 10002@item @emph{Standard}: 10003GNU extension 10004 10005@item @emph{Class}: 10006Subroutine 10007 10008@item @emph{Syntax}: 10009@code{CALL LTIME(TIME, VALUES)} 10010 10011@item @emph{Arguments}: 10012@multitable @columnfractions .15 .70 10013@item @var{TIME} @tab An @code{INTEGER} scalar expression 10014corresponding to a system time, with @code{INTENT(IN)}. 10015@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 10016with @code{INTENT(OUT)}. 10017@end multitable 10018 10019@item @emph{Return value}: 10020The elements of @var{VALUES} are assigned as follows: 10021@enumerate 10022@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 10023seconds 10024@item Minutes after the hour, range 0--59 10025@item Hours past midnight, range 0--23 10026@item Day of month, range 1--31 10027@item Number of months since January, range 0--11 10028@item Years since 1900 10029@item Number of days since Sunday, range 0--6 10030@item Days since January 1, range 0--365 10031@item Daylight savings indicator: positive if daylight savings is in 10032effect, zero if not, and negative if the information is not available. 10033@end enumerate 10034 10035@item @emph{See also}: 10036@ref{DATE_AND_TIME}, @gol 10037@ref{CTIME}, @gol 10038@ref{GMTIME}, @gol 10039@ref{TIME}, @gol 10040@ref{TIME8} 10041@end table 10042 10043 10044 10045@node MALLOC 10046@section @code{MALLOC} --- Allocate dynamic memory 10047@fnindex MALLOC 10048@cindex pointer, cray 10049 10050@table @asis 10051@item @emph{Description}: 10052@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and 10053returns the address of the allocated memory. The @code{MALLOC} intrinsic 10054is an extension intended to be used with Cray pointers, and is provided 10055in GNU Fortran to allow the user to compile legacy code. For new code 10056using Fortran 95 pointers, the memory allocation intrinsic is 10057@code{ALLOCATE}. 10058 10059@item @emph{Standard}: 10060GNU extension 10061 10062@item @emph{Class}: 10063Function 10064 10065@item @emph{Syntax}: 10066@code{PTR = MALLOC(SIZE)} 10067 10068@item @emph{Arguments}: 10069@multitable @columnfractions .15 .70 10070@item @var{SIZE} @tab The type shall be @code{INTEGER}. 10071@end multitable 10072 10073@item @emph{Return value}: 10074The return value is of type @code{INTEGER(K)}, with @var{K} such that 10075variables of type @code{INTEGER(K)} have the same size as 10076C pointers (@code{sizeof(void *)}). 10077 10078@item @emph{Example}: 10079The following example demonstrates the use of @code{MALLOC} and 10080@code{FREE} with Cray pointers. 10081 10082@smallexample 10083program test_malloc 10084 implicit none 10085 integer i 10086 real*8 x(*), z 10087 pointer(ptr_x,x) 10088 10089 ptr_x = malloc(20*8) 10090 do i = 1, 20 10091 x(i) = sqrt(1.0d0 / i) 10092 end do 10093 z = 0 10094 do i = 1, 20 10095 z = z + x(i) 10096 print *, z 10097 end do 10098 call free(ptr_x) 10099end program test_malloc 10100@end smallexample 10101 10102@item @emph{See also}: 10103@ref{FREE} 10104@end table 10105 10106 10107 10108@node MASKL 10109@section @code{MASKL} --- Left justified mask 10110@fnindex MASKL 10111@cindex mask, left justified 10112 10113@table @asis 10114@item @emph{Description}: 10115@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the 10116remaining bits set to 0. 10117 10118@item @emph{Standard}: 10119Fortran 2008 and later 10120 10121@item @emph{Class}: 10122Elemental function 10123 10124@item @emph{Syntax}: 10125@code{RESULT = MASKL(I[, KIND])} 10126 10127@item @emph{Arguments}: 10128@multitable @columnfractions .15 .70 10129@item @var{I} @tab Shall be of type @code{INTEGER}. 10130@item @var{KIND} @tab Shall be a scalar constant expression of type 10131@code{INTEGER}. 10132@end multitable 10133 10134@item @emph{Return value}: 10135The return value is of type @code{INTEGER}. If @var{KIND} is present, it 10136specifies the kind value of the return type; otherwise, it is of the 10137default integer kind. 10138 10139@item @emph{See also}: 10140@ref{MASKR} 10141@end table 10142 10143 10144 10145@node MASKR 10146@section @code{MASKR} --- Right justified mask 10147@fnindex MASKR 10148@cindex mask, right justified 10149 10150@table @asis 10151@item @emph{Description}: 10152@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the 10153remaining bits set to 0. 10154 10155@item @emph{Standard}: 10156Fortran 2008 and later 10157 10158@item @emph{Class}: 10159Elemental function 10160 10161@item @emph{Syntax}: 10162@code{RESULT = MASKR(I[, KIND])} 10163 10164@item @emph{Arguments}: 10165@multitable @columnfractions .15 .70 10166@item @var{I} @tab Shall be of type @code{INTEGER}. 10167@item @var{KIND} @tab Shall be a scalar constant expression of type 10168@code{INTEGER}. 10169@end multitable 10170 10171@item @emph{Return value}: 10172The return value is of type @code{INTEGER}. If @var{KIND} is present, it 10173specifies the kind value of the return type; otherwise, it is of the 10174default integer kind. 10175 10176@item @emph{See also}: 10177@ref{MASKL} 10178@end table 10179 10180 10181 10182@node MATMUL 10183@section @code{MATMUL} --- matrix multiplication 10184@fnindex MATMUL 10185@cindex matrix multiplication 10186@cindex product, matrix 10187 10188@table @asis 10189@item @emph{Description}: 10190Performs a matrix multiplication on numeric or logical arguments. 10191 10192@item @emph{Standard}: 10193Fortran 90 and later 10194 10195@item @emph{Class}: 10196Transformational function 10197 10198@item @emph{Syntax}: 10199@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)} 10200 10201@item @emph{Arguments}: 10202@multitable @columnfractions .15 .70 10203@item @var{MATRIX_A} @tab An array of @code{INTEGER}, 10204@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of 10205one or two. 10206@item @var{MATRIX_B} @tab An array of @code{INTEGER}, 10207@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric 10208type; otherwise, an array of @code{LOGICAL} type. The rank shall be one 10209or two, and the first (or only) dimension of @var{MATRIX_B} shall be 10210equal to the last (or only) dimension of @var{MATRIX_A}. 10211@var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays. 10212@end multitable 10213 10214@item @emph{Return value}: 10215The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and 10216kind of the result follow the usual type and kind promotion rules, as 10217for the @code{*} or @code{.AND.} operators. 10218@end table 10219 10220 10221 10222@node MAX 10223@section @code{MAX} --- Maximum value of an argument list 10224@fnindex MAX 10225@fnindex MAX0 10226@fnindex AMAX0 10227@fnindex MAX1 10228@fnindex AMAX1 10229@fnindex DMAX1 10230@cindex maximum value 10231 10232@table @asis 10233@item @emph{Description}: 10234Returns the argument with the largest (most positive) value. 10235 10236@item @emph{Standard}: 10237Fortran 77 and later 10238 10239@item @emph{Class}: 10240Elemental function 10241 10242@item @emph{Syntax}: 10243@code{RESULT = MAX(A1, A2 [, A3 [, ...]])} 10244 10245@item @emph{Arguments}: 10246@multitable @columnfractions .15 .70 10247@item @var{A1} @tab The type shall be @code{INTEGER} or 10248@code{REAL}. 10249@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10250as @var{A1}. (As a GNU extension, arguments of different kinds are 10251permitted.) 10252@end multitable 10253 10254@item @emph{Return value}: 10255The return value corresponds to the maximum value among the arguments, 10256and has the same type and kind as the first argument. 10257 10258@item @emph{Specific names}: 10259@multitable @columnfractions .20 .20 .20 .25 10260@item Name @tab Argument @tab Return type @tab Standard 10261@item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10262@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later 10263@item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later 10264@item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10265@item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10266@end multitable 10267 10268@item @emph{See also}: 10269@ref{MAXLOC} @gol 10270@ref{MAXVAL}, @gol 10271@ref{MIN} 10272@end table 10273 10274 10275 10276@node MAXEXPONENT 10277@section @code{MAXEXPONENT} --- Maximum exponent of a real kind 10278@fnindex MAXEXPONENT 10279@cindex model representation, maximum exponent 10280 10281@table @asis 10282@item @emph{Description}: 10283@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the 10284type of @code{X}. 10285 10286@item @emph{Standard}: 10287Fortran 90 and later 10288 10289@item @emph{Class}: 10290Inquiry function 10291 10292@item @emph{Syntax}: 10293@code{RESULT = MAXEXPONENT(X)} 10294 10295@item @emph{Arguments}: 10296@multitable @columnfractions .15 .70 10297@item @var{X} @tab Shall be of type @code{REAL}. 10298@end multitable 10299 10300@item @emph{Return value}: 10301The return value is of type @code{INTEGER} and of the default integer 10302kind. 10303 10304@item @emph{Example}: 10305@smallexample 10306program exponents 10307 real(kind=4) :: x 10308 real(kind=8) :: y 10309 10310 print *, minexponent(x), maxexponent(x) 10311 print *, minexponent(y), maxexponent(y) 10312end program exponents 10313@end smallexample 10314@end table 10315 10316 10317 10318@node MAXLOC 10319@section @code{MAXLOC} --- Location of the maximum value within an array 10320@fnindex MAXLOC 10321@cindex array, location of maximum element 10322 10323@table @asis 10324@item @emph{Description}: 10325Determines the location of the element in the array with the maximum 10326value, or, if the @var{DIM} argument is supplied, determines the 10327locations of the maximum element along each row of the array in the 10328@var{DIM} direction. If @var{MASK} is present, only the elements for 10329which @var{MASK} is @code{.TRUE.} are considered. If more than one 10330element in the array has the maximum value, the location returned is 10331that of the first such element in array element order if the 10332@var{BACK} is not present, or is false; if @var{BACK} is true, the location 10333returned is that of the last such element. If the array has zero 10334size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10335the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10336and all of the elements of @var{MASK} along a given row are zero, the 10337result value for that row is zero. 10338 10339@item @emph{Standard}: 10340Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the 10341@var{KIND} argument are available in Fortran 2003 and later. 10342The @var{BACK} argument is available in Fortran 2008 and later. 10343 10344@item @emph{Class}: 10345Transformational function 10346 10347@item @emph{Syntax}: 10348@multitable @columnfractions .80 10349@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} 10350@item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])} 10351@end multitable 10352 10353@item @emph{Arguments}: 10354@multitable @columnfractions .15 .70 10355@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10356@code{REAL}. 10357@item @var{DIM} @tab (Optional) Shall be a scalar of type 10358@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10359inclusive. It may not be an optional dummy argument. 10360@item @var{MASK} @tab Shall be of type @code{LOGICAL}, 10361and conformable with @var{ARRAY}. 10362@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10363expression indicating the kind parameter of the result. 10364@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 10365@end multitable 10366 10367@item @emph{Return value}: 10368If @var{DIM} is absent, the result is a rank-one array with a length 10369equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10370is an array with a rank one less than the rank of @var{ARRAY}, and a 10371size corresponding to the size of @var{ARRAY} with the @var{DIM} 10372dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10373of one, the result is a scalar. If the optional argument @var{KIND} 10374is present, the result is an integer of kind @var{KIND}, otherwise it 10375is of default kind. 10376 10377@item @emph{See also}: 10378@ref{FINDLOC}, @gol 10379@ref{MAX}, @gol 10380@ref{MAXVAL} 10381@end table 10382 10383 10384 10385@node MAXVAL 10386@section @code{MAXVAL} --- Maximum value of an array 10387@fnindex MAXVAL 10388@cindex array, maximum value 10389@cindex maximum value 10390 10391@table @asis 10392@item @emph{Description}: 10393Determines the maximum value of the elements in an array value, or, if 10394the @var{DIM} argument is supplied, determines the maximum value along 10395each row of the array in the @var{DIM} direction. If @var{MASK} is 10396present, only the elements for which @var{MASK} is @code{.TRUE.} are 10397considered. If the array has zero size, or all of the elements of 10398@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)} 10399if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character 10400type. 10401 10402@item @emph{Standard}: 10403Fortran 90 and later 10404 10405@item @emph{Class}: 10406Transformational function 10407 10408@item @emph{Syntax}: 10409@multitable @columnfractions .80 10410@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])} 10411@item @code{RESULT = MAXVAL(ARRAY [, MASK])} 10412@end multitable 10413 10414@item @emph{Arguments}: 10415@multitable @columnfractions .15 .70 10416@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10417@code{REAL}. 10418@item @var{DIM} @tab (Optional) Shall be a scalar of type 10419@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10420inclusive. It may not be an optional dummy argument. 10421@item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL}, 10422and conformable with @var{ARRAY}. 10423@end multitable 10424 10425@item @emph{Return value}: 10426If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10427is a scalar. If @var{DIM} is present, the result is an array with a 10428rank one less than the rank of @var{ARRAY}, and a size corresponding to 10429the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10430cases, the result is of the same type and kind as @var{ARRAY}. 10431 10432@item @emph{See also}: 10433@ref{MAX}, @gol 10434@ref{MAXLOC} 10435@end table 10436 10437 10438 10439@node MCLOCK 10440@section @code{MCLOCK} --- Time function 10441@fnindex MCLOCK 10442@cindex time, clock ticks 10443@cindex clock ticks 10444 10445@table @asis 10446@item @emph{Description}: 10447Returns the number of clock ticks since the start of the process, based 10448on the function @code{clock(3)} in the C standard library. 10449 10450This intrinsic is not fully portable, such as to systems with 32-bit 10451@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 10452the values returned by this intrinsic might be, or become, negative, or 10453numerically less than previous values, during a single run of the 10454compiled program. 10455 10456@item @emph{Standard}: 10457GNU extension 10458 10459@item @emph{Class}: 10460Function 10461 10462@item @emph{Syntax}: 10463@code{RESULT = MCLOCK()} 10464 10465@item @emph{Return value}: 10466The return value is a scalar of type @code{INTEGER(4)}, equal to the 10467number of clock ticks since the start of the process, or @code{-1} if 10468the system does not support @code{clock(3)}. 10469 10470@item @emph{See also}: 10471@ref{CTIME}, @gol 10472@ref{GMTIME}, @gol 10473@ref{LTIME}, @gol 10474@ref{MCLOCK}, @gol 10475@ref{TIME} 10476@end table 10477 10478 10479 10480@node MCLOCK8 10481@section @code{MCLOCK8} --- Time function (64-bit) 10482@fnindex MCLOCK8 10483@cindex time, clock ticks 10484@cindex clock ticks 10485 10486@table @asis 10487@item @emph{Description}: 10488Returns the number of clock ticks since the start of the process, based 10489on the function @code{clock(3)} in the C standard library. 10490 10491@emph{Warning:} this intrinsic does not increase the range of the timing 10492values over that returned by @code{clock(3)}. On a system with a 32-bit 10493@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though 10494it is converted to a 64-bit @code{INTEGER(8)} value. That means 10495overflows of the 32-bit value can still occur. Therefore, the values 10496returned by this intrinsic might be or become negative or numerically 10497less than previous values during a single run of the compiled program. 10498 10499@item @emph{Standard}: 10500GNU extension 10501 10502@item @emph{Class}: 10503Function 10504 10505@item @emph{Syntax}: 10506@code{RESULT = MCLOCK8()} 10507 10508@item @emph{Return value}: 10509The return value is a scalar of type @code{INTEGER(8)}, equal to the 10510number of clock ticks since the start of the process, or @code{-1} if 10511the system does not support @code{clock(3)}. 10512 10513@item @emph{See also}: 10514@ref{CTIME}, @gol 10515@ref{GMTIME}, @gol 10516@ref{LTIME}, @gol 10517@ref{MCLOCK}, @gol 10518@ref{TIME8} 10519@end table 10520 10521 10522 10523@node MERGE 10524@section @code{MERGE} --- Merge variables 10525@fnindex MERGE 10526@cindex array, merge arrays 10527@cindex array, combine arrays 10528 10529@table @asis 10530@item @emph{Description}: 10531Select values from two arrays according to a logical mask. The result 10532is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to 10533@var{FSOURCE} if it is @code{.FALSE.}. 10534 10535@item @emph{Standard}: 10536Fortran 90 and later 10537 10538@item @emph{Class}: 10539Elemental function 10540 10541@item @emph{Syntax}: 10542@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)} 10543 10544@item @emph{Arguments}: 10545@multitable @columnfractions .15 .70 10546@item @var{TSOURCE} @tab May be of any type. 10547@item @var{FSOURCE} @tab Shall be of the same type and type parameters 10548as @var{TSOURCE}. 10549@item @var{MASK} @tab Shall be of type @code{LOGICAL}. 10550@end multitable 10551 10552@item @emph{Return value}: 10553The result is of the same type and type parameters as @var{TSOURCE}. 10554 10555@end table 10556 10557 10558 10559@node MERGE_BITS 10560@section @code{MERGE_BITS} --- Merge of bits under mask 10561@fnindex MERGE_BITS 10562@cindex bits, merge 10563 10564@table @asis 10565@item @emph{Description}: 10566@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J} 10567as determined by the mask. The i-th bit of the result is equal to the 10568i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to 10569the i-th bit of @var{J} otherwise. 10570 10571@item @emph{Standard}: 10572Fortran 2008 and later 10573 10574@item @emph{Class}: 10575Elemental function 10576 10577@item @emph{Syntax}: 10578@code{RESULT = MERGE_BITS(I, J, MASK)} 10579 10580@item @emph{Arguments}: 10581@multitable @columnfractions .15 .70 10582@item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant. 10583@item @var{J} @tab Shall be of type @code{INTEGER} with the same 10584kind type parameter as @var{I} or a boz-literal-constant. 10585@var{I} and @var{J} shall not both be boz-literal-constants. 10586@item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant 10587and of the same kind as @var{I}. 10588@end multitable 10589 10590@item @emph{Return value}: 10591The result is of the same type and kind as @var{I}. 10592 10593@end table 10594 10595 10596 10597@node MIN 10598@section @code{MIN} --- Minimum value of an argument list 10599@fnindex MIN 10600@fnindex MIN0 10601@fnindex AMIN0 10602@fnindex MIN1 10603@fnindex AMIN1 10604@fnindex DMIN1 10605@cindex minimum value 10606 10607@table @asis 10608@item @emph{Description}: 10609Returns the argument with the smallest (most negative) value. 10610 10611@item @emph{Standard}: 10612Fortran 77 and later 10613 10614@item @emph{Class}: 10615Elemental function 10616 10617@item @emph{Syntax}: 10618@code{RESULT = MIN(A1, A2 [, A3, ...])} 10619 10620@item @emph{Arguments}: 10621@multitable @columnfractions .15 .70 10622@item @var{A1} @tab The type shall be @code{INTEGER} or 10623@code{REAL}. 10624@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10625as @var{A1}. (As a GNU extension, arguments of different kinds are 10626permitted.) 10627@end multitable 10628 10629@item @emph{Return value}: 10630The return value corresponds to the minimum value among the arguments, 10631and has the same type and kind as the first argument. 10632 10633@item @emph{Specific names}: 10634@multitable @columnfractions .20 .20 .20 .25 10635@item Name @tab Argument @tab Return type @tab Standard 10636@item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10637@item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10638@item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10639@item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10640@item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10641@end multitable 10642 10643@item @emph{See also}: 10644@ref{MAX}, @gol 10645@ref{MINLOC}, @gol 10646@ref{MINVAL} 10647@end table 10648 10649 10650 10651@node MINEXPONENT 10652@section @code{MINEXPONENT} --- Minimum exponent of a real kind 10653@fnindex MINEXPONENT 10654@cindex model representation, minimum exponent 10655 10656@table @asis 10657@item @emph{Description}: 10658@code{MINEXPONENT(X)} returns the minimum exponent in the model of the 10659type of @code{X}. 10660 10661@item @emph{Standard}: 10662Fortran 90 and later 10663 10664@item @emph{Class}: 10665Inquiry function 10666 10667@item @emph{Syntax}: 10668@code{RESULT = MINEXPONENT(X)} 10669 10670@item @emph{Arguments}: 10671@multitable @columnfractions .15 .70 10672@item @var{X} @tab Shall be of type @code{REAL}. 10673@end multitable 10674 10675@item @emph{Return value}: 10676The return value is of type @code{INTEGER} and of the default integer 10677kind. 10678 10679@item @emph{Example}: 10680See @code{MAXEXPONENT} for an example. 10681@end table 10682 10683 10684 10685@node MINLOC 10686@section @code{MINLOC} --- Location of the minimum value within an array 10687@fnindex MINLOC 10688@cindex array, location of minimum element 10689 10690@table @asis 10691@item @emph{Description}: 10692Determines the location of the element in the array with the minimum 10693value, or, if the @var{DIM} argument is supplied, determines the 10694locations of the minimum element along each row of the array in the 10695@var{DIM} direction. If @var{MASK} is present, only the elements for 10696which @var{MASK} is @code{.TRUE.} are considered. If more than one 10697element in the array has the minimum value, the location returned is 10698that of the first such element in array element order if the 10699@var{BACK} is not present, or is false; if @var{BACK} is true, the location 10700returned is that of the last such element. If the array has 10701zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10702the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10703and all of the elements of @var{MASK} along a given row are zero, the 10704result value for that row is zero. 10705 10706@item @emph{Standard}: 10707Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the 10708@var{KIND} argument are available in Fortran 2003 and later. 10709The @var{BACK} argument is available in Fortran 2008 and later. 10710 10711@item @emph{Class}: 10712Transformational function 10713 10714@item @emph{Syntax}: 10715@multitable @columnfractions .80 10716@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} 10717@item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])} 10718@end multitable 10719 10720@item @emph{Arguments}: 10721@multitable @columnfractions .15 .70 10722@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 10723@code{REAL} or @code{CHARACTER}. 10724@item @var{DIM} @tab (Optional) Shall be a scalar of type 10725@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10726inclusive. It may not be an optional dummy argument. 10727@item @var{MASK} @tab Shall be of type @code{LOGICAL}, 10728and conformable with @var{ARRAY}. 10729@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10730expression indicating the kind parameter of the result. 10731@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 10732@end multitable 10733 10734@item @emph{Return value}: 10735If @var{DIM} is absent, the result is a rank-one array with a length 10736equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10737is an array with a rank one less than the rank of @var{ARRAY}, and a 10738size corresponding to the size of @var{ARRAY} with the @var{DIM} 10739dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10740of one, the result is a scalar. If the optional argument @var{KIND} 10741is present, the result is an integer of kind @var{KIND}, otherwise it 10742is of default kind. 10743 10744@item @emph{See also}: 10745@ref{FINDLOC}, @gol 10746@ref{MIN}, @gol 10747@ref{MINVAL} 10748@end table 10749 10750 10751 10752@node MINVAL 10753@section @code{MINVAL} --- Minimum value of an array 10754@fnindex MINVAL 10755@cindex array, minimum value 10756@cindex minimum value 10757 10758@table @asis 10759@item @emph{Description}: 10760Determines the minimum value of the elements in an array value, or, if 10761the @var{DIM} argument is supplied, determines the minimum value along 10762each row of the array in the @var{DIM} direction. If @var{MASK} is 10763present, only the elements for which @var{MASK} is @code{.TRUE.} are 10764considered. If the array has zero size, or all of the elements of 10765@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if 10766@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if 10767@var{ARRAY} is of character type. 10768 10769@item @emph{Standard}: 10770Fortran 90 and later 10771 10772@item @emph{Class}: 10773Transformational function 10774 10775@item @emph{Syntax}: 10776@multitable @columnfractions .80 10777@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])} 10778@item @code{RESULT = MINVAL(ARRAY [, MASK])} 10779@end multitable 10780 10781@item @emph{Arguments}: 10782@multitable @columnfractions .15 .70 10783@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10784@code{REAL}. 10785@item @var{DIM} @tab (Optional) Shall be a scalar of type 10786@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10787inclusive. It may not be an optional dummy argument. 10788@item @var{MASK} @tab Shall be of type @code{LOGICAL}, 10789and conformable with @var{ARRAY}. 10790@end multitable 10791 10792@item @emph{Return value}: 10793If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10794is a scalar. If @var{DIM} is present, the result is an array with a 10795rank one less than the rank of @var{ARRAY}, and a size corresponding to 10796the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10797cases, the result is of the same type and kind as @var{ARRAY}. 10798 10799@item @emph{See also}: 10800@ref{MIN}, @gol 10801@ref{MINLOC} 10802@end table 10803 10804 10805 10806@node MOD 10807@section @code{MOD} --- Remainder function 10808@fnindex MOD 10809@fnindex AMOD 10810@fnindex DMOD 10811@fnindex BMOD 10812@fnindex IMOD 10813@fnindex JMOD 10814@fnindex KMOD 10815@cindex remainder 10816@cindex division, remainder 10817 10818@table @asis 10819@item @emph{Description}: 10820@code{MOD(A,P)} computes the remainder of the division of A by P@. 10821 10822@item @emph{Standard}: 10823Fortran 77 and later, has overloads that are GNU extensions 10824 10825@item @emph{Class}: 10826Elemental function 10827 10828@item @emph{Syntax}: 10829@code{RESULT = MOD(A, P)} 10830 10831@item @emph{Arguments}: 10832@multitable @columnfractions .15 .70 10833@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10834@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A} 10835and not equal to zero. (As a GNU extension, arguments of different kinds are 10836permitted.) 10837@end multitable 10838 10839@item @emph{Return value}: 10840The return value is the result of @code{A - (INT(A/P) * P)}. The type 10841and kind of the return value is the same as that of the arguments. The 10842returned value has the same sign as A and a magnitude less than the 10843magnitude of P. (As a GNU extension, kind is the largest kind of the actual 10844arguments.) 10845 10846@item @emph{Example}: 10847@smallexample 10848program test_mod 10849 print *, mod(17,3) 10850 print *, mod(17.5,5.5) 10851 print *, mod(17.5d0,5.5) 10852 print *, mod(17.5,5.5d0) 10853 10854 print *, mod(-17,3) 10855 print *, mod(-17.5,5.5) 10856 print *, mod(-17.5d0,5.5) 10857 print *, mod(-17.5,5.5d0) 10858 10859 print *, mod(17,-3) 10860 print *, mod(17.5,-5.5) 10861 print *, mod(17.5d0,-5.5) 10862 print *, mod(17.5,-5.5d0) 10863end program test_mod 10864@end smallexample 10865 10866@item @emph{Specific names}: 10867@multitable @columnfractions .20 .20 .20 .25 10868@item Name @tab Arguments @tab Return type @tab Standard 10869@item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later 10870@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later 10871@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later 10872@item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension 10873@item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension 10874@item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension 10875@item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension 10876@end multitable 10877 10878@item @emph{See also}: 10879@ref{MODULO} 10880 10881@end table 10882 10883 10884 10885@node MODULO 10886@section @code{MODULO} --- Modulo function 10887@fnindex MODULO 10888@cindex modulo 10889@cindex division, modulo 10890 10891@table @asis 10892@item @emph{Description}: 10893@code{MODULO(A,P)} computes the @var{A} modulo @var{P}. 10894 10895@item @emph{Standard}: 10896Fortran 95 and later 10897 10898@item @emph{Class}: 10899Elemental function 10900 10901@item @emph{Syntax}: 10902@code{RESULT = MODULO(A, P)} 10903 10904@item @emph{Arguments}: 10905@multitable @columnfractions .15 .70 10906@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10907@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}. 10908It shall not be zero. (As a GNU extension, arguments of different kinds are 10909permitted.) 10910@end multitable 10911 10912@item @emph{Return value}: 10913The type and kind of the result are those of the arguments. (As a GNU 10914extension, kind is the largest kind of the actual arguments.) 10915@table @asis 10916@item If @var{A} and @var{P} are of type @code{INTEGER}: 10917@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where 10918@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P} 10919(exclusive). 10920@item If @var{A} and @var{P} are of type @code{REAL}: 10921@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}. 10922@end table 10923The returned value has the same sign as P and a magnitude less than 10924the magnitude of P. 10925 10926@item @emph{Example}: 10927@smallexample 10928program test_modulo 10929 print *, modulo(17,3) 10930 print *, modulo(17.5,5.5) 10931 10932 print *, modulo(-17,3) 10933 print *, modulo(-17.5,5.5) 10934 10935 print *, modulo(17,-3) 10936 print *, modulo(17.5,-5.5) 10937end program 10938@end smallexample 10939 10940@item @emph{See also}: 10941@ref{MOD} 10942 10943@end table 10944 10945 10946 10947@node MOVE_ALLOC 10948@section @code{MOVE_ALLOC} --- Move allocation from one object to another 10949@fnindex MOVE_ALLOC 10950@cindex moving allocation 10951@cindex allocation, moving 10952 10953@table @asis 10954@item @emph{Description}: 10955@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to 10956@var{TO}. @var{FROM} will become deallocated in the process. 10957 10958@item @emph{Standard}: 10959Fortran 2003 and later 10960 10961@item @emph{Class}: 10962Pure subroutine 10963 10964@item @emph{Syntax}: 10965@code{CALL MOVE_ALLOC(FROM, TO)} 10966 10967@item @emph{Arguments}: 10968@multitable @columnfractions .15 .70 10969@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be 10970of any type and kind. 10971@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be 10972of the same type, kind and rank as @var{FROM}. 10973@end multitable 10974 10975@item @emph{Return value}: 10976None 10977 10978@item @emph{Example}: 10979@smallexample 10980program test_move_alloc 10981 integer, allocatable :: a(:), b(:) 10982 10983 allocate(a(3)) 10984 a = [ 1, 2, 3 ] 10985 call move_alloc(a, b) 10986 print *, allocated(a), allocated(b) 10987 print *, b 10988end program test_move_alloc 10989@end smallexample 10990@end table 10991 10992 10993 10994@node MVBITS 10995@section @code{MVBITS} --- Move bits from one integer to another 10996@fnindex MVBITS 10997@fnindex BMVBITS 10998@fnindex IMVBITS 10999@fnindex JMVBITS 11000@fnindex KMVBITS 11001@cindex bits, move 11002 11003@table @asis 11004@item @emph{Description}: 11005Moves @var{LEN} bits from positions @var{FROMPOS} through 11006@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through 11007@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not 11008affected by the movement of bits is unchanged. The values of 11009@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than 11010@code{BIT_SIZE(FROM)}. 11011 11012@item @emph{Standard}: 11013Fortran 90 and later, has overloads that are GNU extensions 11014 11015@item @emph{Class}: 11016Elemental subroutine 11017 11018@item @emph{Syntax}: 11019@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)} 11020 11021@item @emph{Arguments}: 11022@multitable @columnfractions .15 .70 11023@item @var{FROM} @tab The type shall be @code{INTEGER}. 11024@item @var{FROMPOS} @tab The type shall be @code{INTEGER}. 11025@item @var{LEN} @tab The type shall be @code{INTEGER}. 11026@item @var{TO} @tab The type shall be @code{INTEGER}, of the 11027same kind as @var{FROM}. 11028@item @var{TOPOS} @tab The type shall be @code{INTEGER}. 11029@end multitable 11030 11031@item @emph{Specific names}: 11032@multitable @columnfractions .20 .20 .20 .25 11033@item Name @tab Argument @tab Return type @tab Standard 11034@item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 11035@item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 11036@item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 11037@item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 11038@item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 11039@end multitable 11040 11041@item @emph{See also}: 11042@ref{IBCLR}, @gol 11043@ref{IBSET}, @gol 11044@ref{IBITS}, @gol 11045@ref{IAND}, @gol 11046@ref{IOR}, @gol 11047@ref{IEOR} 11048@end table 11049 11050 11051 11052@node NEAREST 11053@section @code{NEAREST} --- Nearest representable number 11054@fnindex NEAREST 11055@cindex real number, nearest different 11056@cindex floating point, nearest different 11057 11058@table @asis 11059@item @emph{Description}: 11060@code{NEAREST(X, S)} returns the processor-representable number nearest 11061to @code{X} in the direction indicated by the sign of @code{S}. 11062 11063@item @emph{Standard}: 11064Fortran 90 and later 11065 11066@item @emph{Class}: 11067Elemental function 11068 11069@item @emph{Syntax}: 11070@code{RESULT = NEAREST(X, S)} 11071 11072@item @emph{Arguments}: 11073@multitable @columnfractions .15 .70 11074@item @var{X} @tab Shall be of type @code{REAL}. 11075@item @var{S} @tab Shall be of type @code{REAL} and 11076not equal to zero. 11077@end multitable 11078 11079@item @emph{Return value}: 11080The return value is of the same type as @code{X}. If @code{S} is 11081positive, @code{NEAREST} returns the processor-representable number 11082greater than @code{X} and nearest to it. If @code{S} is negative, 11083@code{NEAREST} returns the processor-representable number smaller than 11084@code{X} and nearest to it. 11085 11086@item @emph{Example}: 11087@smallexample 11088program test_nearest 11089 real :: x, y 11090 x = nearest(42.0, 1.0) 11091 y = nearest(42.0, -1.0) 11092 write (*,"(3(G20.15))") x, y, x - y 11093end program test_nearest 11094@end smallexample 11095@end table 11096 11097 11098 11099@node NEW_LINE 11100@section @code{NEW_LINE} --- New line character 11101@fnindex NEW_LINE 11102@cindex newline 11103@cindex output, newline 11104 11105@table @asis 11106@item @emph{Description}: 11107@code{NEW_LINE(C)} returns the new-line character. 11108 11109@item @emph{Standard}: 11110Fortran 2003 and later 11111 11112@item @emph{Class}: 11113Inquiry function 11114 11115@item @emph{Syntax}: 11116@code{RESULT = NEW_LINE(C)} 11117 11118@item @emph{Arguments}: 11119@multitable @columnfractions .15 .70 11120@item @var{C} @tab The argument shall be a scalar or array of the 11121type @code{CHARACTER}. 11122@end multitable 11123 11124@item @emph{Return value}: 11125Returns a @var{CHARACTER} scalar of length one with the new-line character of 11126the same kind as parameter @var{C}. 11127 11128@item @emph{Example}: 11129@smallexample 11130program newline 11131 implicit none 11132 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' 11133end program newline 11134@end smallexample 11135@end table 11136 11137 11138 11139@node NINT 11140@section @code{NINT} --- Nearest whole number 11141@fnindex NINT 11142@fnindex IDNINT 11143@cindex rounding, nearest whole number 11144 11145@table @asis 11146@item @emph{Description}: 11147@code{NINT(A)} rounds its argument to the nearest whole number. 11148 11149@item @emph{Standard}: 11150Fortran 77 and later, with @var{KIND} argument Fortran 90 and later 11151 11152@item @emph{Class}: 11153Elemental function 11154 11155@item @emph{Syntax}: 11156@code{RESULT = NINT(A [, KIND])} 11157 11158@item @emph{Arguments}: 11159@multitable @columnfractions .15 .70 11160@item @var{A} @tab The type of the argument shall be @code{REAL}. 11161@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 11162expression indicating the kind parameter of the result. 11163@end multitable 11164 11165@item @emph{Return value}: 11166Returns @var{A} with the fractional portion of its magnitude eliminated by 11167rounding to the nearest whole number and with its sign preserved, 11168converted to an @code{INTEGER} of the default kind. 11169 11170@item @emph{Example}: 11171@smallexample 11172program test_nint 11173 real(4) x4 11174 real(8) x8 11175 x4 = 1.234E0_4 11176 x8 = 4.321_8 11177 print *, nint(x4), idnint(x8) 11178end program test_nint 11179@end smallexample 11180 11181@item @emph{Specific names}: 11182@multitable @columnfractions .20 .20 .20 .25 11183@item Name @tab Argument @tab Return Type @tab Standard 11184@item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 11185@item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 11186@end multitable 11187 11188@item @emph{See also}: 11189@ref{CEILING}, @gol 11190@ref{FLOOR} 11191@end table 11192 11193 11194 11195@node NORM2 11196@section @code{NORM2} --- Euclidean vector norms 11197@fnindex NORM2 11198@cindex Euclidean vector norm 11199@cindex L2 vector norm 11200@cindex norm, Euclidean 11201 11202@table @asis 11203@item @emph{Description}: 11204Calculates the Euclidean vector norm (@math{L_2} norm) 11205of @var{ARRAY} along dimension @var{DIM}. 11206 11207@item @emph{Standard}: 11208Fortran 2008 and later 11209 11210@item @emph{Class}: 11211Transformational function 11212 11213@item @emph{Syntax}: 11214@multitable @columnfractions .80 11215@item @code{RESULT = NORM2(ARRAY[, DIM])} 11216@end multitable 11217 11218@item @emph{Arguments}: 11219@multitable @columnfractions .15 .70 11220@item @var{ARRAY} @tab Shall be an array of type @code{REAL} 11221@item @var{DIM} @tab (Optional) shall be a scalar of type 11222@code{INTEGER} with a value in the range from 1 to n, where n 11223equals the rank of @var{ARRAY}. 11224@end multitable 11225 11226@item @emph{Return value}: 11227The result is of the same type as @var{ARRAY}. 11228 11229If @var{DIM} is absent, a scalar with the square root of the sum of all 11230elements in @var{ARRAY} squared is returned. Otherwise, an array of 11231rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a 11232shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped 11233is returned. 11234 11235@item @emph{Example}: 11236@smallexample 11237PROGRAM test_sum 11238 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] 11239 print *, NORM2(x) ! = sqrt(55.) ~ 7.416 11240END PROGRAM 11241@end smallexample 11242@end table 11243 11244 11245 11246@node NOT 11247@section @code{NOT} --- Logical negation 11248@fnindex NOT 11249@fnindex BNOT 11250@fnindex INOT 11251@fnindex JNOT 11252@fnindex KNOT 11253@cindex bits, negate 11254@cindex bitwise logical not 11255@cindex logical not, bitwise 11256 11257@table @asis 11258@item @emph{Description}: 11259@code{NOT} returns the bitwise Boolean inverse of @var{I}. 11260 11261@item @emph{Standard}: 11262Fortran 90 and later, has overloads that are GNU extensions 11263 11264@item @emph{Class}: 11265Elemental function 11266 11267@item @emph{Syntax}: 11268@code{RESULT = NOT(I)} 11269 11270@item @emph{Arguments}: 11271@multitable @columnfractions .15 .70 11272@item @var{I} @tab The type shall be @code{INTEGER}. 11273@end multitable 11274 11275@item @emph{Return value}: 11276The return type is @code{INTEGER}, of the same kind as the 11277argument. 11278 11279@item @emph{Specific names}: 11280@multitable @columnfractions .20 .20 .20 .25 11281@item Name @tab Argument @tab Return type @tab Standard 11282@item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 11283@item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 11284@item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 11285@item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 11286@item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 11287@end multitable 11288 11289@item @emph{See also}: 11290@ref{IAND}, @gol 11291@ref{IEOR}, @gol 11292@ref{IOR}, @gol 11293@ref{IBITS}, @gol 11294@ref{IBSET}, @gol 11295@ref{IBCLR} 11296@end table 11297 11298 11299 11300@node NULL 11301@section @code{NULL} --- Function that returns an disassociated pointer 11302@fnindex NULL 11303@cindex pointer, status 11304@cindex pointer, disassociated 11305 11306@table @asis 11307@item @emph{Description}: 11308Returns a disassociated pointer. 11309 11310If @var{MOLD} is present, a disassociated pointer of the same type is 11311returned, otherwise the type is determined by context. 11312 11313In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003 11314includes cases where it is required. 11315 11316@item @emph{Standard}: 11317Fortran 95 and later 11318 11319@item @emph{Class}: 11320Transformational function 11321 11322@item @emph{Syntax}: 11323@code{PTR => NULL([MOLD])} 11324 11325@item @emph{Arguments}: 11326@multitable @columnfractions .15 .70 11327@item @var{MOLD} @tab (Optional) shall be a pointer of any association 11328status and of any type. 11329@end multitable 11330 11331@item @emph{Return value}: 11332A disassociated pointer. 11333 11334@item @emph{Example}: 11335@smallexample 11336REAL, POINTER, DIMENSION(:) :: VEC => NULL () 11337@end smallexample 11338 11339@item @emph{See also}: 11340@ref{ASSOCIATED} 11341@end table 11342 11343 11344 11345@node NUM_IMAGES 11346@section @code{NUM_IMAGES} --- Function that returns the number of images 11347@fnindex NUM_IMAGES 11348@cindex coarray, @code{NUM_IMAGES} 11349@cindex images, number of 11350 11351@table @asis 11352@item @emph{Description}: 11353Returns the number of images. 11354 11355@item @emph{Standard}: 11356Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument, 11357Technical Specification (TS) 18508 or later 11358 11359 11360@item @emph{Class}: 11361Transformational function 11362 11363@item @emph{Syntax}: 11364@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} 11365 11366@item @emph{Arguments}: 11367@multitable @columnfractions .15 .70 11368@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 11369@item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression 11370@end multitable 11371 11372@item @emph{Return value}: 11373Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, 11374the number of images in the current team is returned. For values smaller or 11375equal distance to the initial team, it returns the number of images index 11376on the ancestor team which has a distance of @var{DISTANCE} from the invoking 11377team. If @var{DISTANCE} is larger than the distance to the initial team, the 11378number of images of the initial team is returned. If @var{FAILED} is not present 11379the total number of images is returned; if it has the value @code{.TRUE.}, 11380the number of failed images is returned, otherwise, the number of images which 11381do have not the failed status. 11382 11383@item @emph{Example}: 11384@smallexample 11385INTEGER :: value[*] 11386INTEGER :: i 11387value = THIS_IMAGE() 11388SYNC ALL 11389IF (THIS_IMAGE() == 1) THEN 11390 DO i = 1, NUM_IMAGES() 11391 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 11392 END DO 11393END IF 11394@end smallexample 11395 11396@item @emph{See also}: 11397@ref{THIS_IMAGE}, @gol 11398@ref{IMAGE_INDEX} 11399@end table 11400 11401 11402 11403@node OR 11404@section @code{OR} --- Bitwise logical OR 11405@fnindex OR 11406@cindex bitwise logical or 11407@cindex logical or, bitwise 11408 11409@table @asis 11410@item @emph{Description}: 11411Bitwise logical @code{OR}. 11412 11413This intrinsic routine is provided for backwards compatibility with 11414GNU Fortran 77. For integer arguments, programmers should consider 11415the use of the @ref{IOR} intrinsic defined by the Fortran standard. 11416 11417@item @emph{Standard}: 11418GNU extension 11419 11420@item @emph{Class}: 11421Function 11422 11423@item @emph{Syntax}: 11424@code{RESULT = OR(I, J)} 11425 11426@item @emph{Arguments}: 11427@multitable @columnfractions .15 .70 11428@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 11429type or a scalar @code{LOGICAL} type or a boz-literal-constant. 11430@item @var{J} @tab The type shall be the same as the type of @var{I} or 11431a boz-literal-constant. @var{I} and @var{J} shall not both be 11432boz-literal-constants. If either @var{I} and @var{J} is a 11433boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 11434@end multitable 11435 11436@item @emph{Return value}: 11437The return type is either a scalar @code{INTEGER} or a scalar 11438@code{LOGICAL}. If the kind type parameters differ, then the 11439smaller kind type is implicitly converted to larger kind, and the 11440return has the larger kind. A boz-literal-constant is 11441converted to an @code{INTEGER} with the kind type parameter of 11442the other argument as-if a call to @ref{INT} occurred. 11443 11444@item @emph{Example}: 11445@smallexample 11446PROGRAM test_or 11447 LOGICAL :: T = .TRUE., F = .FALSE. 11448 INTEGER :: a, b 11449 DATA a / Z'F' /, b / Z'3' / 11450 11451 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F) 11452 WRITE (*,*) OR(a, b) 11453END PROGRAM 11454@end smallexample 11455 11456@item @emph{See also}: 11457Fortran 95 elemental function: @gol 11458@ref{IOR} 11459@end table 11460 11461 11462 11463@node PACK 11464@section @code{PACK} --- Pack an array into an array of rank one 11465@fnindex PACK 11466@cindex array, packing 11467@cindex array, reduce dimension 11468@cindex array, gather elements 11469 11470@table @asis 11471@item @emph{Description}: 11472Stores the elements of @var{ARRAY} in an array of rank one. 11473 11474The beginning of the resulting array is made up of elements whose @var{MASK} 11475equals @code{TRUE}. Afterwards, positions are filled with elements taken from 11476@var{VECTOR}. 11477 11478@item @emph{Standard}: 11479Fortran 90 and later 11480 11481@item @emph{Class}: 11482Transformational function 11483 11484@item @emph{Syntax}: 11485@code{RESULT = PACK(ARRAY, MASK[,VECTOR])} 11486 11487@item @emph{Arguments}: 11488@multitable @columnfractions .15 .70 11489@item @var{ARRAY} @tab Shall be an array of any type. 11490@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and 11491of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} 11492scalar. 11493@item @var{VECTOR} @tab (Optional) shall be an array of the same type 11494as @var{ARRAY} and of rank one. If present, the number of elements in 11495@var{VECTOR} shall be equal to or greater than the number of true elements 11496in @var{MASK}. If @var{MASK} is scalar, the number of elements in 11497@var{VECTOR} shall be equal to or greater than the number of elements in 11498@var{ARRAY}. 11499@end multitable 11500 11501@item @emph{Return value}: 11502The result is an array of rank one and the same type as that of @var{ARRAY}. 11503If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the 11504number of @code{TRUE} values in @var{MASK} otherwise. 11505 11506@item @emph{Example}: 11507Gathering nonzero elements from an array: 11508@smallexample 11509PROGRAM test_pack_1 11510 INTEGER :: m(6) 11511 m = (/ 1, 0, 0, 0, 5, 0 /) 11512 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5" 11513END PROGRAM 11514@end smallexample 11515 11516Gathering nonzero elements from an array and appending elements from @var{VECTOR}: 11517@smallexample 11518PROGRAM test_pack_2 11519 INTEGER :: m(4) 11520 m = (/ 1, 0, 0, 2 /) 11521 ! The following results in "1 2 3 4" 11522 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) 11523END PROGRAM 11524@end smallexample 11525 11526@item @emph{See also}: 11527@ref{UNPACK} 11528@end table 11529 11530 11531 11532@node PARITY 11533@section @code{PARITY} --- Reduction with exclusive OR 11534@fnindex PARITY 11535@cindex Parity 11536@cindex Reduction, XOR 11537@cindex XOR reduction 11538 11539@table @asis 11540@item @emph{Description}: 11541Calculates the parity, i.e. the reduction using @code{.XOR.}, 11542of @var{MASK} along dimension @var{DIM}. 11543 11544@item @emph{Standard}: 11545Fortran 2008 and later 11546 11547@item @emph{Class}: 11548Transformational function 11549 11550@item @emph{Syntax}: 11551@multitable @columnfractions .80 11552@item @code{RESULT = PARITY(MASK[, DIM])} 11553@end multitable 11554 11555@item @emph{Arguments}: 11556@multitable @columnfractions .15 .70 11557@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} 11558@item @var{DIM} @tab (Optional) shall be a scalar of type 11559@code{INTEGER} with a value in the range from 1 to n, where n 11560equals the rank of @var{MASK}. 11561@end multitable 11562 11563@item @emph{Return value}: 11564The result is of the same type as @var{MASK}. 11565 11566If @var{DIM} is absent, a scalar with the parity of all elements in 11567@var{MASK} is returned, i.e. true if an odd number of elements is 11568@code{.true.} and false otherwise. If @var{DIM} is present, an array 11569of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, 11570and a shape similar to that of @var{MASK} with dimension @var{DIM} 11571dropped is returned. 11572 11573@item @emph{Example}: 11574@smallexample 11575PROGRAM test_sum 11576 LOGICAL :: x(2) = [ .true., .false. ] 11577 print *, PARITY(x) ! prints "T" (true). 11578END PROGRAM 11579@end smallexample 11580@end table 11581 11582 11583 11584@node PERROR 11585@section @code{PERROR} --- Print system error message 11586@fnindex PERROR 11587@cindex system, error handling 11588 11589@table @asis 11590@item @emph{Description}: 11591Prints (on the C @code{stderr} stream) a newline-terminated error 11592message corresponding to the last system error. This is prefixed by 11593@var{STRING}, a colon and a space. See @code{perror(3)}. 11594 11595@item @emph{Standard}: 11596GNU extension 11597 11598@item @emph{Class}: 11599Subroutine 11600 11601@item @emph{Syntax}: 11602@code{CALL PERROR(STRING)} 11603 11604@item @emph{Arguments}: 11605@multitable @columnfractions .15 .70 11606@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the 11607default kind. 11608@end multitable 11609 11610@item @emph{See also}: 11611@ref{IERRNO} 11612@end table 11613 11614 11615 11616@node POPCNT 11617@section @code{POPCNT} --- Number of bits set 11618@fnindex POPCNT 11619@cindex binary representation 11620@cindex bits set 11621 11622@table @asis 11623@item @emph{Description}: 11624@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary 11625representation of @code{I}. 11626 11627@item @emph{Standard}: 11628Fortran 2008 and later 11629 11630@item @emph{Class}: 11631Elemental function 11632 11633@item @emph{Syntax}: 11634@code{RESULT = POPCNT(I)} 11635 11636@item @emph{Arguments}: 11637@multitable @columnfractions .15 .70 11638@item @var{I} @tab Shall be of type @code{INTEGER}. 11639@end multitable 11640 11641@item @emph{Return value}: 11642The return value is of type @code{INTEGER} and of the default integer 11643kind. 11644 11645@item @emph{Example}: 11646@smallexample 11647program test_population 11648 print *, popcnt(127), poppar(127) 11649 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11650 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11651end program test_population 11652@end smallexample 11653@item @emph{See also}: 11654@ref{POPPAR}, @gol 11655@ref{LEADZ}, @gol 11656@ref{TRAILZ} 11657@end table 11658 11659 11660 11661@node POPPAR 11662@section @code{POPPAR} --- Parity of the number of bits set 11663@fnindex POPPAR 11664@cindex binary representation 11665@cindex parity 11666 11667@table @asis 11668@item @emph{Description}: 11669@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity 11670of the number of bits set ('1' bits) in the binary representation of 11671@code{I}. It is equal to 0 if @code{I} has an even number of bits set, 11672and 1 for an odd number of '1' bits. 11673 11674@item @emph{Standard}: 11675Fortran 2008 and later 11676 11677@item @emph{Class}: 11678Elemental function 11679 11680@item @emph{Syntax}: 11681@code{RESULT = POPPAR(I)} 11682 11683@item @emph{Arguments}: 11684@multitable @columnfractions .15 .70 11685@item @var{I} @tab Shall be of type @code{INTEGER}. 11686@end multitable 11687 11688@item @emph{Return value}: 11689The return value is of type @code{INTEGER} and of the default integer 11690kind. 11691 11692@item @emph{Example}: 11693@smallexample 11694program test_population 11695 print *, popcnt(127), poppar(127) 11696 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11697 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11698end program test_population 11699@end smallexample 11700@item @emph{See also}: 11701@ref{POPCNT}, @gol 11702@ref{LEADZ}, @gol 11703@ref{TRAILZ} 11704@end table 11705 11706 11707 11708@node PRECISION 11709@section @code{PRECISION} --- Decimal precision of a real kind 11710@fnindex PRECISION 11711@cindex model representation, precision 11712 11713@table @asis 11714@item @emph{Description}: 11715@code{PRECISION(X)} returns the decimal precision in the model of the 11716type of @code{X}. 11717 11718@item @emph{Standard}: 11719Fortran 90 and later 11720 11721@item @emph{Class}: 11722Inquiry function 11723 11724@item @emph{Syntax}: 11725@code{RESULT = PRECISION(X)} 11726 11727@item @emph{Arguments}: 11728@multitable @columnfractions .15 .70 11729@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may 11730be scalar or valued. 11731@end multitable 11732 11733@item @emph{Return value}: 11734The return value is of type @code{INTEGER} and of the default integer 11735kind. 11736 11737@item @emph{Example}: 11738@smallexample 11739program prec_and_range 11740 real(kind=4) :: x(2) 11741 complex(kind=8) :: y 11742 11743 print *, precision(x), range(x) 11744 print *, precision(y), range(y) 11745end program prec_and_range 11746@end smallexample 11747@item @emph{See also}: 11748@ref{SELECTED_REAL_KIND}, @gol 11749@ref{RANGE} 11750@end table 11751 11752 11753 11754@node PRESENT 11755@section @code{PRESENT} --- Determine whether an optional dummy argument is specified 11756@fnindex PRESENT 11757 11758@table @asis 11759@item @emph{Description}: 11760Determines whether an optional dummy argument is present. 11761 11762@item @emph{Standard}: 11763Fortran 90 and later 11764 11765@item @emph{Class}: 11766Inquiry function 11767 11768@item @emph{Syntax}: 11769@code{RESULT = PRESENT(A)} 11770 11771@item @emph{Arguments}: 11772@multitable @columnfractions .15 .70 11773@item @var{A} @tab May be of any type and may be a pointer, scalar or array 11774value, or a dummy procedure. It shall be the name of an optional dummy argument 11775accessible within the current subroutine or function. 11776@end multitable 11777 11778@item @emph{Return value}: 11779Returns either @code{TRUE} if the optional argument @var{A} is present, or 11780@code{FALSE} otherwise. 11781 11782@item @emph{Example}: 11783@smallexample 11784PROGRAM test_present 11785 WRITE(*,*) f(), f(42) ! "F T" 11786CONTAINS 11787 LOGICAL FUNCTION f(x) 11788 INTEGER, INTENT(IN), OPTIONAL :: x 11789 f = PRESENT(x) 11790 END FUNCTION 11791END PROGRAM 11792@end smallexample 11793@end table 11794 11795 11796 11797@node PRODUCT 11798@section @code{PRODUCT} --- Product of array elements 11799@fnindex PRODUCT 11800@cindex array, product 11801@cindex array, multiply elements 11802@cindex array, conditionally multiply elements 11803@cindex multiply array elements 11804 11805@table @asis 11806@item @emph{Description}: 11807Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if 11808the corresponding element in @var{MASK} is @code{TRUE}. 11809 11810@item @emph{Standard}: 11811Fortran 90 and later 11812 11813@item @emph{Class}: 11814Transformational function 11815 11816@item @emph{Syntax}: 11817@multitable @columnfractions .80 11818@item @code{RESULT = PRODUCT(ARRAY[, MASK])} 11819@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])} 11820@end multitable 11821 11822@item @emph{Arguments}: 11823@multitable @columnfractions .15 .70 11824@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 11825@code{REAL} or @code{COMPLEX}. 11826@item @var{DIM} @tab (Optional) shall be a scalar of type 11827@code{INTEGER} with a value in the range from 1 to n, where n 11828equals the rank of @var{ARRAY}. 11829@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 11830and either be a scalar or an array of the same shape as @var{ARRAY}. 11831@end multitable 11832 11833@item @emph{Return value}: 11834The result is of the same type as @var{ARRAY}. 11835 11836If @var{DIM} is absent, a scalar with the product of all elements in 11837@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 11838the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 11839dimension @var{DIM} dropped is returned. 11840 11841 11842@item @emph{Example}: 11843@smallexample 11844PROGRAM test_product 11845 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 11846 print *, PRODUCT(x) ! all elements, product = 120 11847 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15 11848END PROGRAM 11849@end smallexample 11850 11851@item @emph{See also}: 11852@ref{SUM} 11853@end table 11854 11855 11856 11857@node RADIX 11858@section @code{RADIX} --- Base of a model number 11859@fnindex RADIX 11860@cindex model representation, base 11861@cindex model representation, radix 11862 11863@table @asis 11864@item @emph{Description}: 11865@code{RADIX(X)} returns the base of the model representing the entity @var{X}. 11866 11867@item @emph{Standard}: 11868Fortran 90 and later 11869 11870@item @emph{Class}: 11871Inquiry function 11872 11873@item @emph{Syntax}: 11874@code{RESULT = RADIX(X)} 11875 11876@item @emph{Arguments}: 11877@multitable @columnfractions .15 .70 11878@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL} 11879@end multitable 11880 11881@item @emph{Return value}: 11882The return value is a scalar of type @code{INTEGER} and of the default 11883integer kind. 11884 11885@item @emph{Example}: 11886@smallexample 11887program test_radix 11888 print *, "The radix for the default integer kind is", radix(0) 11889 print *, "The radix for the default real kind is", radix(0.0) 11890end program test_radix 11891@end smallexample 11892@item @emph{See also}: 11893@ref{SELECTED_REAL_KIND} 11894@end table 11895 11896 11897 11898@node RAN 11899@section @code{RAN} --- Real pseudo-random number 11900@fnindex RAN 11901@cindex random number generation 11902 11903@table @asis 11904@item @emph{Description}: 11905For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is 11906provided as an alias for @code{RAND}. See @ref{RAND} for complete 11907documentation. 11908 11909@item @emph{Standard}: 11910GNU extension 11911 11912@item @emph{Class}: 11913Function 11914 11915@item @emph{See also}: 11916@ref{RAND}, @gol 11917@ref{RANDOM_NUMBER} 11918@end table 11919 11920 11921 11922@node RAND 11923@section @code{RAND} --- Real pseudo-random number 11924@fnindex RAND 11925@cindex random number generation 11926 11927@table @asis 11928@item @emph{Description}: 11929@code{RAND(FLAG)} returns a pseudo-random number from a uniform 11930distribution between 0 and 1. If @var{FLAG} is 0, the next number 11931in the current sequence is returned; if @var{FLAG} is 1, the generator 11932is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 11933it is used as a new seed with @code{SRAND}. 11934 11935This intrinsic routine is provided for backwards compatibility with 11936GNU Fortran 77. It implements a simple modulo generator as provided 11937by @command{g77}. For new code, one should consider the use of 11938@ref{RANDOM_NUMBER} as it implements a superior algorithm. 11939 11940@item @emph{Standard}: 11941GNU extension 11942 11943@item @emph{Class}: 11944Function 11945 11946@item @emph{Syntax}: 11947@code{RESULT = RAND(I)} 11948 11949@item @emph{Arguments}: 11950@multitable @columnfractions .15 .70 11951@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 11952@end multitable 11953 11954@item @emph{Return value}: 11955The return value is of @code{REAL} type and the default kind. 11956 11957@item @emph{Example}: 11958@smallexample 11959program test_rand 11960 integer,parameter :: seed = 86456 11961 11962 call srand(seed) 11963 print *, rand(), rand(), rand(), rand() 11964 print *, rand(seed), rand(), rand(), rand() 11965end program test_rand 11966@end smallexample 11967 11968@item @emph{See also}: 11969@ref{SRAND}, @gol 11970@ref{RANDOM_NUMBER} 11971 11972@end table 11973 11974 11975@node RANDOM_INIT 11976@section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator 11977@fnindex RANDOM_INIT 11978@cindex random number generation, initialization 11979 11980@table @asis 11981@item @emph{Description}: 11982Initializes the state of the pseudorandom number generator used by 11983@code{RANDOM_NUMBER}. 11984 11985@item @emph{Standard}: 11986Fortran 2018 11987 11988@item @emph{Class}: 11989Subroutine 11990 11991@item @emph{Syntax}: 11992@code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)} 11993 11994@item @emph{Arguments}: 11995@multitable @columnfractions .25 .70 11996@item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type, 11997and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to 11998a processor-dependent value that is the same each time @code{RANDOM_INIT} 11999is called from the same image. The term ``same image'' means a single 12000instance of program execution. The sequence of random numbers is different 12001for repeated execution of the program. If it is @code{.false.}, the seed 12002is set to a processor-dependent value. 12003@item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a 12004@code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.}, 12005the seed is set to a processor-dependent value that is distinct from th 12006seed set by a call to @code{RANDOM_INIT} in another image. If it is 12007@code{.false.}, the seed is set to a value that does depend which image called 12008@code{RANDOM_INIT}. 12009@end multitable 12010 12011@item @emph{Example}: 12012@smallexample 12013program test_random_seed 12014 implicit none 12015 real x(3), y(3) 12016 call random_init(.true., .true.) 12017 call random_number(x) 12018 call random_init(.true., .true.) 12019 call random_number(y) 12020 ! x and y are the same sequence 12021 if (any(x /= y)) call abort 12022end program test_random_seed 12023@end smallexample 12024 12025@item @emph{See also}: 12026@ref{RANDOM_NUMBER}, @gol 12027@ref{RANDOM_SEED} 12028@end table 12029 12030 12031@node RANDOM_NUMBER 12032@section @code{RANDOM_NUMBER} --- Pseudo-random number 12033@fnindex RANDOM_NUMBER 12034@cindex random number generation 12035 12036@table @asis 12037@item @emph{Description}: 12038Returns a single pseudorandom number or an array of pseudorandom numbers 12039from the uniform distribution over the range @math{ 0 \leq x < 1}. 12040 12041The runtime-library implements the xoshiro256** pseudorandom number 12042generator (PRNG). This generator has a period of @math{2^{256} - 1}, 12043and when using multiple threads up to @math{2^{128}} threads can each 12044generate @math{2^{128}} random numbers before any aliasing occurs. 12045 12046Note that in a multi-threaded program (e.g. using OpenMP directives), 12047each thread will have its own random number state. For details of the 12048seeding procedure, see the documentation for the @code{RANDOM_SEED} 12049intrinsic. 12050 12051 12052@item @emph{Standard}: 12053Fortran 90 and later 12054 12055@item @emph{Class}: 12056Subroutine 12057 12058@item @emph{Syntax}: 12059@code{CALL RANDOM_NUMBER(HARVEST)} 12060 12061@item @emph{Arguments}: 12062@multitable @columnfractions .15 .70 12063@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}. 12064@end multitable 12065 12066@item @emph{Example}: 12067@smallexample 12068program test_random_number 12069 REAL :: r(5,5) 12070 CALL RANDOM_NUMBER(r) 12071end program 12072@end smallexample 12073 12074@item @emph{See also}: 12075@ref{RANDOM_SEED}, @gol 12076@ref{RANDOM_INIT} 12077@end table 12078 12079 12080 12081@node RANDOM_SEED 12082@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence 12083@fnindex RANDOM_SEED 12084@cindex random number generation, seeding 12085@cindex seeding a random number generator 12086 12087@table @asis 12088@item @emph{Description}: 12089Restarts or queries the state of the pseudorandom number generator used by 12090@code{RANDOM_NUMBER}. 12091 12092If @code{RANDOM_SEED} is called without arguments, it is seeded with 12093random data retrieved from the operating system. 12094 12095As an extension to the Fortran standard, the GFortran 12096@code{RANDOM_NUMBER} supports multiple threads. Each thread in a 12097multi-threaded program has its own seed. When @code{RANDOM_SEED} is 12098called either without arguments or with the @var{PUT} argument, the 12099given seed is copied into a master seed as well as the seed of the 12100current thread. When a new thread uses @code{RANDOM_NUMBER} for the 12101first time, the seed is copied from the master seed, and forwarded 12102@math{N * 2^{128}} steps to guarantee that the random stream does not 12103alias any other stream in the system, where @var{N} is the number of 12104threads that have used @code{RANDOM_NUMBER} so far during the program 12105execution. 12106 12107@item @emph{Standard}: 12108Fortran 90 and later 12109 12110@item @emph{Class}: 12111Subroutine 12112 12113@item @emph{Syntax}: 12114@code{CALL RANDOM_SEED([SIZE, PUT, GET])} 12115 12116@item @emph{Arguments}: 12117@multitable @columnfractions .15 .70 12118@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default 12119@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size 12120of the arrays used with the @var{PUT} and @var{GET} arguments. 12121@item @var{PUT} @tab (Optional) Shall be an array of type default 12122@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of 12123the array must be larger than or equal to the number returned by the 12124@var{SIZE} argument. 12125@item @var{GET} @tab (Optional) Shall be an array of type default 12126@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size 12127of the array must be larger than or equal to the number returned by 12128the @var{SIZE} argument. 12129@end multitable 12130 12131@item @emph{Example}: 12132@smallexample 12133program test_random_seed 12134 implicit none 12135 integer, allocatable :: seed(:) 12136 integer :: n 12137 12138 call random_seed(size = n) 12139 allocate(seed(n)) 12140 call random_seed(get=seed) 12141 write (*, *) seed 12142end program test_random_seed 12143@end smallexample 12144 12145@item @emph{See also}: 12146@ref{RANDOM_NUMBER}, @gol 12147@ref{RANDOM_INIT} 12148@end table 12149 12150 12151 12152@node RANGE 12153@section @code{RANGE} --- Decimal exponent range 12154@fnindex RANGE 12155@cindex model representation, range 12156 12157@table @asis 12158@item @emph{Description}: 12159@code{RANGE(X)} returns the decimal exponent range in the model of the 12160type of @code{X}. 12161 12162@item @emph{Standard}: 12163Fortran 90 and later 12164 12165@item @emph{Class}: 12166Inquiry function 12167 12168@item @emph{Syntax}: 12169@code{RESULT = RANGE(X)} 12170 12171@item @emph{Arguments}: 12172@multitable @columnfractions .15 .70 12173@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL} 12174or @code{COMPLEX}. 12175@end multitable 12176 12177@item @emph{Return value}: 12178The return value is of type @code{INTEGER} and of the default integer 12179kind. 12180 12181@item @emph{Example}: 12182See @code{PRECISION} for an example. 12183@item @emph{See also}: 12184@ref{SELECTED_REAL_KIND}, @gol 12185@ref{PRECISION} 12186@end table 12187 12188 12189 12190@node RANK 12191@section @code{RANK} --- Rank of a data object 12192@fnindex RANK 12193@cindex rank 12194 12195@table @asis 12196@item @emph{Description}: 12197@code{RANK(A)} returns the rank of a scalar or array data object. 12198 12199@item @emph{Standard}: 12200Technical Specification (TS) 29113 12201 12202@item @emph{Class}: 12203Inquiry function 12204 12205@item @emph{Syntax}: 12206@code{RESULT = RANK(A)} 12207 12208@item @emph{Arguments}: 12209@multitable @columnfractions .15 .70 12210@item @var{A} @tab can be of any type 12211@end multitable 12212 12213@item @emph{Return value}: 12214The return value is of type @code{INTEGER} and of the default integer 12215kind. For arrays, their rank is returned; for scalars zero is returned. 12216 12217@item @emph{Example}: 12218@smallexample 12219program test_rank 12220 integer :: a 12221 real, allocatable :: b(:,:) 12222 12223 print *, rank(a), rank(b) ! Prints: 0 2 12224end program test_rank 12225@end smallexample 12226 12227@end table 12228 12229 12230 12231@node REAL 12232@section @code{REAL} --- Convert to real type 12233@fnindex REAL 12234@fnindex REALPART 12235@fnindex FLOAT 12236@fnindex DFLOAT 12237@fnindex FLOATI 12238@fnindex FLOATJ 12239@fnindex FLOATK 12240@fnindex SNGL 12241@cindex conversion, to real 12242@cindex complex numbers, real part 12243 12244@table @asis 12245@item @emph{Description}: 12246@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The 12247@code{REALPART} function is provided for compatibility with @command{g77}, 12248and its use is strongly discouraged. 12249 12250@item @emph{Standard}: 12251Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions 12252 12253@item @emph{Class}: 12254Elemental function 12255 12256@item @emph{Syntax}: 12257@multitable @columnfractions .80 12258@item @code{RESULT = REAL(A [, KIND])} 12259@item @code{RESULT = REALPART(Z)} 12260@end multitable 12261 12262@item @emph{Arguments}: 12263@multitable @columnfractions .15 .70 12264@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or 12265@code{COMPLEX}. 12266@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12267expression indicating the kind parameter of the result. 12268@end multitable 12269 12270@item @emph{Return value}: 12271These functions return a @code{REAL} variable or array under 12272the following rules: 12273 12274@table @asis 12275@item (A) 12276@code{REAL(A)} is converted to a default real type if @var{A} is an 12277integer or real variable. 12278@item (B) 12279@code{REAL(A)} is converted to a real type with the kind type parameter 12280of @var{A} if @var{A} is a complex variable. 12281@item (C) 12282@code{REAL(A, KIND)} is converted to a real type with kind type 12283parameter @var{KIND} if @var{A} is a complex, integer, or real 12284variable. 12285@end table 12286 12287@item @emph{Example}: 12288@smallexample 12289program test_real 12290 complex :: x = (1.0, 2.0) 12291 print *, real(x), real(x,8), realpart(x) 12292end program test_real 12293@end smallexample 12294 12295@item @emph{Specific names}: 12296@multitable @columnfractions .20 .20 .20 .25 12297@item Name @tab Argument @tab Return type @tab Standard 12298@item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension 12299@item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension 12300@item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension 12301@item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension 12302@item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension 12303@item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension 12304@end multitable 12305 12306 12307@item @emph{See also}: 12308@ref{DBLE} 12309 12310@end table 12311 12312 12313 12314@node RENAME 12315@section @code{RENAME} --- Rename a file 12316@fnindex RENAME 12317@cindex file system, rename file 12318 12319@table @asis 12320@item @emph{Description}: 12321Renames a file from file @var{PATH1} to @var{PATH2}. A null 12322character (@code{CHAR(0)}) can be used to mark the end of the names in 12323@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 12324names are ignored. If the @var{STATUS} argument is supplied, it 12325contains 0 on success or a nonzero error code upon return; see 12326@code{rename(2)}. 12327 12328This intrinsic is provided in both subroutine and function forms; 12329however, only one form can be used in any given program unit. 12330 12331@item @emph{Standard}: 12332GNU extension 12333 12334@item @emph{Class}: 12335Subroutine, function 12336 12337@item @emph{Syntax}: 12338@multitable @columnfractions .80 12339@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])} 12340@item @code{STATUS = RENAME(PATH1, PATH2)} 12341@end multitable 12342 12343@item @emph{Arguments}: 12344@multitable @columnfractions .15 .70 12345@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 12346@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 12347@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 12348@end multitable 12349 12350@item @emph{See also}: 12351@ref{LINK} 12352 12353@end table 12354 12355 12356 12357@node REPEAT 12358@section @code{REPEAT} --- Repeated string concatenation 12359@fnindex REPEAT 12360@cindex string, repeat 12361@cindex string, concatenate 12362 12363@table @asis 12364@item @emph{Description}: 12365Concatenates @var{NCOPIES} copies of a string. 12366 12367@item @emph{Standard}: 12368Fortran 90 and later 12369 12370@item @emph{Class}: 12371Transformational function 12372 12373@item @emph{Syntax}: 12374@code{RESULT = REPEAT(STRING, NCOPIES)} 12375 12376@item @emph{Arguments}: 12377@multitable @columnfractions .15 .70 12378@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}. 12379@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}. 12380@end multitable 12381 12382@item @emph{Return value}: 12383A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies 12384of @var{STRING}. 12385 12386@item @emph{Example}: 12387@smallexample 12388program test_repeat 12389 write(*,*) repeat("x", 5) ! "xxxxx" 12390end program 12391@end smallexample 12392@end table 12393 12394 12395 12396@node RESHAPE 12397@section @code{RESHAPE} --- Function to reshape an array 12398@fnindex RESHAPE 12399@cindex array, change dimensions 12400@cindex array, transmogrify 12401 12402@table @asis 12403@item @emph{Description}: 12404Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary, 12405the new array may be padded with elements from @var{PAD} or permuted 12406as defined by @var{ORDER}. 12407 12408@item @emph{Standard}: 12409Fortran 90 and later 12410 12411@item @emph{Class}: 12412Transformational function 12413 12414@item @emph{Syntax}: 12415@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])} 12416 12417@item @emph{Arguments}: 12418@multitable @columnfractions .15 .70 12419@item @var{SOURCE} @tab Shall be an array of any type. 12420@item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an 12421array of rank one. Its values must be positive or zero. 12422@item @var{PAD} @tab (Optional) shall be an array of the same 12423type as @var{SOURCE}. 12424@item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER} 12425and an array of the same shape as @var{SHAPE}. Its values shall 12426be a permutation of the numbers from 1 to n, where n is the size of 12427@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall 12428be assumed. 12429@end multitable 12430 12431@item @emph{Return value}: 12432The result is an array of shape @var{SHAPE} with the same type as 12433@var{SOURCE}. 12434 12435@item @emph{Example}: 12436@smallexample 12437PROGRAM test_reshape 12438 INTEGER, DIMENSION(4) :: x 12439 WRITE(*,*) SHAPE(x) ! prints "4" 12440 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" 12441END PROGRAM 12442@end smallexample 12443 12444@item @emph{See also}: 12445@ref{SHAPE} 12446@end table 12447 12448 12449 12450@node RRSPACING 12451@section @code{RRSPACING} --- Reciprocal of the relative spacing 12452@fnindex RRSPACING 12453@cindex real number, relative spacing 12454@cindex floating point, relative spacing 12455 12456 12457@table @asis 12458@item @emph{Description}: 12459@code{RRSPACING(X)} returns the reciprocal of the relative spacing of 12460model numbers near @var{X}. 12461 12462@item @emph{Standard}: 12463Fortran 90 and later 12464 12465@item @emph{Class}: 12466Elemental function 12467 12468@item @emph{Syntax}: 12469@code{RESULT = RRSPACING(X)} 12470 12471@item @emph{Arguments}: 12472@multitable @columnfractions .15 .70 12473@item @var{X} @tab Shall be of type @code{REAL}. 12474@end multitable 12475 12476@item @emph{Return value}: 12477The return value is of the same type and kind as @var{X}. 12478The value returned is equal to 12479@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}. 12480 12481@item @emph{See also}: 12482@ref{SPACING} 12483@end table 12484 12485 12486 12487@node RSHIFT 12488@section @code{RSHIFT} --- Right shift bits 12489@fnindex RSHIFT 12490@cindex bits, shift right 12491 12492@table @asis 12493@item @emph{Description}: 12494@code{RSHIFT} returns a value corresponding to @var{I} with all of the 12495bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be 12496nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 12497the result value is undefined. Bits shifted out from the right end 12498are lost. The fill is arithmetic: the bits shifted in from the left 12499end are equal to the leftmost bit, which in two's complement 12500representation is the sign bit. 12501 12502This function has been superseded by the @code{SHIFTA} intrinsic, which 12503is standard in Fortran 2008 and later. 12504 12505@item @emph{Standard}: 12506GNU extension 12507 12508@item @emph{Class}: 12509Elemental function 12510 12511@item @emph{Syntax}: 12512@code{RESULT = RSHIFT(I, SHIFT)} 12513 12514@item @emph{Arguments}: 12515@multitable @columnfractions .15 .70 12516@item @var{I} @tab The type shall be @code{INTEGER}. 12517@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12518@end multitable 12519 12520@item @emph{Return value}: 12521The return value is of type @code{INTEGER} and of the same kind as 12522@var{I}. 12523 12524@item @emph{See also}: 12525@ref{ISHFT}, @gol 12526@ref{ISHFTC}, @gol 12527@ref{LSHIFT}, @gol 12528@ref{SHIFTA}, @gol 12529@ref{SHIFTR}, @gol 12530@ref{SHIFTL} 12531 12532@end table 12533 12534 12535 12536@node SAME_TYPE_AS 12537@section @code{SAME_TYPE_AS} --- Query dynamic types for equality 12538@fnindex SAME_TYPE_AS 12539 12540@table @asis 12541@item @emph{Description}: 12542Query dynamic types for equality. 12543 12544@item @emph{Standard}: 12545Fortran 2003 and later 12546 12547@item @emph{Class}: 12548Inquiry function 12549 12550@item @emph{Syntax}: 12551@code{RESULT = SAME_TYPE_AS(A, B)} 12552 12553@item @emph{Arguments}: 12554@multitable @columnfractions .15 .70 12555@item @var{A} @tab Shall be an object of extensible declared type or 12556unlimited polymorphic. 12557@item @var{B} @tab Shall be an object of extensible declared type or 12558unlimited polymorphic. 12559@end multitable 12560 12561@item @emph{Return value}: 12562The return value is a scalar of type default logical. It is true if and 12563only if the dynamic type of A is the same as the dynamic type of B. 12564 12565@item @emph{See also}: 12566@ref{EXTENDS_TYPE_OF} 12567 12568@end table 12569 12570 12571 12572@node SCALE 12573@section @code{SCALE} --- Scale a real value 12574@fnindex SCALE 12575@cindex real number, scale 12576@cindex floating point, scale 12577 12578@table @asis 12579@item @emph{Description}: 12580@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}. 12581 12582@item @emph{Standard}: 12583Fortran 90 and later 12584 12585@item @emph{Class}: 12586Elemental function 12587 12588@item @emph{Syntax}: 12589@code{RESULT = SCALE(X, I)} 12590 12591@item @emph{Arguments}: 12592@multitable @columnfractions .15 .70 12593@item @var{X} @tab The type of the argument shall be a @code{REAL}. 12594@item @var{I} @tab The type of the argument shall be a @code{INTEGER}. 12595@end multitable 12596 12597@item @emph{Return value}: 12598The return value is of the same type and kind as @var{X}. 12599Its value is @code{X * RADIX(X)**I}. 12600 12601@item @emph{Example}: 12602@smallexample 12603program test_scale 12604 real :: x = 178.1387e-4 12605 integer :: i = 5 12606 print *, scale(x,i), x*radix(x)**i 12607end program test_scale 12608@end smallexample 12609 12610@end table 12611 12612 12613 12614@node SCAN 12615@section @code{SCAN} --- Scan a string for the presence of a set of characters 12616@fnindex SCAN 12617@cindex string, find subset 12618 12619@table @asis 12620@item @emph{Description}: 12621Scans a @var{STRING} for any of the characters in a @var{SET} 12622of characters. 12623 12624If @var{BACK} is either absent or equals @code{FALSE}, this function 12625returns the position of the leftmost character of @var{STRING} that is 12626in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position 12627is returned. If no character of @var{SET} is found in @var{STRING}, the 12628result is zero. 12629 12630@item @emph{Standard}: 12631Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 12632 12633@item @emph{Class}: 12634Elemental function 12635 12636@item @emph{Syntax}: 12637@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])} 12638 12639@item @emph{Arguments}: 12640@multitable @columnfractions .15 .70 12641@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 12642@item @var{SET} @tab Shall be of type @code{CHARACTER}. 12643@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 12644@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12645expression indicating the kind parameter of the result. 12646@end multitable 12647 12648@item @emph{Return value}: 12649The return value is of type @code{INTEGER} and of kind @var{KIND}. If 12650@var{KIND} is absent, the return value is of default integer kind. 12651 12652@item @emph{Example}: 12653@smallexample 12654PROGRAM test_scan 12655 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O' 12656 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A' 12657 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none 12658END PROGRAM 12659@end smallexample 12660 12661@item @emph{See also}: 12662@ref{INDEX intrinsic}, @gol 12663@ref{VERIFY} 12664@end table 12665 12666 12667 12668@node SECNDS 12669@section @code{SECNDS} --- Time function 12670@fnindex SECNDS 12671@cindex time, elapsed 12672@cindex elapsed time 12673 12674@table @asis 12675@item @emph{Description}: 12676@code{SECNDS(X)} gets the time in seconds from the real-time system clock. 12677@var{X} is a reference time, also in seconds. If this is zero, the time in 12678seconds from midnight is returned. This function is non-standard and its 12679use is discouraged. 12680 12681@item @emph{Standard}: 12682GNU extension 12683 12684@item @emph{Class}: 12685Function 12686 12687@item @emph{Syntax}: 12688@code{RESULT = SECNDS (X)} 12689 12690@item @emph{Arguments}: 12691@multitable @columnfractions .15 .70 12692@item @var{T} @tab Shall be of type @code{REAL(4)}. 12693@item @var{X} @tab Shall be of type @code{REAL(4)}. 12694@end multitable 12695 12696@item @emph{Return value}: 12697None 12698 12699@item @emph{Example}: 12700@smallexample 12701program test_secnds 12702 integer :: i 12703 real(4) :: t1, t2 12704 print *, secnds (0.0) ! seconds since midnight 12705 t1 = secnds (0.0) ! reference time 12706 do i = 1, 10000000 ! do something 12707 end do 12708 t2 = secnds (t1) ! elapsed time 12709 print *, "Something took ", t2, " seconds." 12710end program test_secnds 12711@end smallexample 12712@end table 12713 12714 12715 12716@node SECOND 12717@section @code{SECOND} --- CPU time function 12718@fnindex SECOND 12719@cindex time, elapsed 12720@cindex elapsed time 12721 12722@table @asis 12723@item @emph{Description}: 12724Returns a @code{REAL(4)} value representing the elapsed CPU time in 12725seconds. This provides the same functionality as the standard 12726@code{CPU_TIME} intrinsic, and is only included for backwards 12727compatibility. 12728 12729This intrinsic is provided in both subroutine and function forms; 12730however, only one form can be used in any given program unit. 12731 12732@item @emph{Standard}: 12733GNU extension 12734 12735@item @emph{Class}: 12736Subroutine, function 12737 12738@item @emph{Syntax}: 12739@multitable @columnfractions .80 12740@item @code{CALL SECOND(TIME)} 12741@item @code{TIME = SECOND()} 12742@end multitable 12743 12744@item @emph{Arguments}: 12745@multitable @columnfractions .15 .70 12746@item @var{TIME} @tab Shall be of type @code{REAL(4)}. 12747@end multitable 12748 12749@item @emph{Return value}: 12750In either syntax, @var{TIME} is set to the process's current runtime in 12751seconds. 12752 12753@item @emph{See also}: 12754@ref{CPU_TIME} 12755 12756@end table 12757 12758 12759 12760@node SELECTED_CHAR_KIND 12761@section @code{SELECTED_CHAR_KIND} --- Choose character kind 12762@fnindex SELECTED_CHAR_KIND 12763@cindex character kind 12764@cindex kind, character 12765 12766@table @asis 12767@item @emph{Description}: 12768 12769@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character 12770set named @var{NAME}, if a character set with such a name is supported, 12771or @math{-1} otherwise. Currently, supported character sets include 12772``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646'' 12773(Universal Character Set, UCS-4) which is commonly known as Unicode. 12774 12775@item @emph{Standard}: 12776Fortran 2003 and later 12777 12778@item @emph{Class}: 12779Transformational function 12780 12781@item @emph{Syntax}: 12782@code{RESULT = SELECTED_CHAR_KIND(NAME)} 12783 12784@item @emph{Arguments}: 12785@multitable @columnfractions .15 .70 12786@item @var{NAME} @tab Shall be a scalar and of the default character type. 12787@end multitable 12788 12789@item @emph{Example}: 12790@smallexample 12791program character_kind 12792 use iso_fortran_env 12793 implicit none 12794 integer, parameter :: ascii = selected_char_kind ("ascii") 12795 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646') 12796 12797 character(kind=ascii, len=26) :: alphabet 12798 character(kind=ucs4, len=30) :: hello_world 12799 12800 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz" 12801 hello_world = ucs4_'Hello World and Ni Hao -- ' & 12802 // char (int (z'4F60'), ucs4) & 12803 // char (int (z'597D'), ucs4) 12804 12805 write (*,*) alphabet 12806 12807 open (output_unit, encoding='UTF-8') 12808 write (*,*) trim (hello_world) 12809end program character_kind 12810@end smallexample 12811@end table 12812 12813 12814 12815@node SELECTED_INT_KIND 12816@section @code{SELECTED_INT_KIND} --- Choose integer kind 12817@fnindex SELECTED_INT_KIND 12818@cindex integer kind 12819@cindex kind, integer 12820 12821@table @asis 12822@item @emph{Description}: 12823@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer 12824type that can represent all values ranging from @math{-10^R} (exclusive) 12825to @math{10^R} (exclusive). If there is no integer kind that accommodates 12826this range, @code{SELECTED_INT_KIND} returns @math{-1}. 12827 12828@item @emph{Standard}: 12829Fortran 90 and later 12830 12831@item @emph{Class}: 12832Transformational function 12833 12834@item @emph{Syntax}: 12835@code{RESULT = SELECTED_INT_KIND(R)} 12836 12837@item @emph{Arguments}: 12838@multitable @columnfractions .15 .70 12839@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}. 12840@end multitable 12841 12842@item @emph{Example}: 12843@smallexample 12844program large_integers 12845 integer,parameter :: k5 = selected_int_kind(5) 12846 integer,parameter :: k15 = selected_int_kind(15) 12847 integer(kind=k5) :: i5 12848 integer(kind=k15) :: i15 12849 12850 print *, huge(i5), huge(i15) 12851 12852 ! The following inequalities are always true 12853 print *, huge(i5) >= 10_k5**5-1 12854 print *, huge(i15) >= 10_k15**15-1 12855end program large_integers 12856@end smallexample 12857@end table 12858 12859 12860 12861@node SELECTED_REAL_KIND 12862@section @code{SELECTED_REAL_KIND} --- Choose real kind 12863@fnindex SELECTED_REAL_KIND 12864@cindex real kind 12865@cindex kind, real 12866@cindex radix, real 12867 12868@table @asis 12869@item @emph{Description}: 12870@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type 12871with decimal precision of at least @code{P} digits, exponent range of 12872at least @code{R}, and with a radix of @code{RADIX}. 12873 12874@item @emph{Standard}: 12875Fortran 90 and later, with @code{RADIX} Fortran 2008 or later 12876 12877@item @emph{Class}: 12878Transformational function 12879 12880@item @emph{Syntax}: 12881@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])} 12882 12883@item @emph{Arguments}: 12884@multitable @columnfractions .15 .70 12885@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12886@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12887@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12888@end multitable 12889Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall 12890be present; since Fortran 2008, they are assumed to be zero if absent. 12891 12892@item @emph{Return value}: 12893 12894@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of 12895a real data type with decimal precision of at least @code{P} digits, a 12896decimal exponent range of at least @code{R}, and with the requested 12897@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with 12898any radix can be returned. If more than one real data type meet the 12899criteria, the kind of the data type with the smallest decimal precision 12900is returned. If no real data type matches the criteria, the result is 12901@table @asis 12902@item -1 if the processor does not support a real data type with a 12903precision greater than or equal to @code{P}, but the @code{R} and 12904@code{RADIX} requirements can be fulfilled 12905@item -2 if the processor does not support a real type with an exponent 12906range greater than or equal to @code{R}, but @code{P} and @code{RADIX} 12907are fulfillable 12908@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements 12909are fulfillable 12910@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements 12911are fulfillable 12912@item -5 if there is no real type with the given @code{RADIX} 12913@end table 12914 12915@item @emph{Example}: 12916@smallexample 12917program real_kinds 12918 integer,parameter :: p6 = selected_real_kind(6) 12919 integer,parameter :: p10r100 = selected_real_kind(10,100) 12920 integer,parameter :: r400 = selected_real_kind(r=400) 12921 real(kind=p6) :: x 12922 real(kind=p10r100) :: y 12923 real(kind=r400) :: z 12924 12925 print *, precision(x), range(x) 12926 print *, precision(y), range(y) 12927 print *, precision(z), range(z) 12928end program real_kinds 12929@end smallexample 12930@item @emph{See also}: 12931@ref{PRECISION}, @gol 12932@ref{RANGE}, @gol 12933@ref{RADIX} 12934@end table 12935 12936 12937 12938@node SET_EXPONENT 12939@section @code{SET_EXPONENT} --- Set the exponent of the model 12940@fnindex SET_EXPONENT 12941@cindex real number, set exponent 12942@cindex floating point, set exponent 12943 12944@table @asis 12945@item @emph{Description}: 12946@code{SET_EXPONENT(X, I)} returns the real number whose fractional part 12947is that that of @var{X} and whose exponent part is @var{I}. 12948 12949@item @emph{Standard}: 12950Fortran 90 and later 12951 12952@item @emph{Class}: 12953Elemental function 12954 12955@item @emph{Syntax}: 12956@code{RESULT = SET_EXPONENT(X, I)} 12957 12958@item @emph{Arguments}: 12959@multitable @columnfractions .15 .70 12960@item @var{X} @tab Shall be of type @code{REAL}. 12961@item @var{I} @tab Shall be of type @code{INTEGER}. 12962@end multitable 12963 12964@item @emph{Return value}: 12965The return value is of the same type and kind as @var{X}. 12966The real number whose fractional part 12967is that that of @var{X} and whose exponent part if @var{I} is returned; 12968it is @code{FRACTION(X) * RADIX(X)**I}. 12969 12970@item @emph{Example}: 12971@smallexample 12972PROGRAM test_setexp 12973 REAL :: x = 178.1387e-4 12974 INTEGER :: i = 17 12975 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i 12976END PROGRAM 12977@end smallexample 12978 12979@end table 12980 12981 12982 12983@node SHAPE 12984@section @code{SHAPE} --- Determine the shape of an array 12985@fnindex SHAPE 12986@cindex array, shape 12987 12988@table @asis 12989@item @emph{Description}: 12990Determines the shape of an array. 12991 12992@item @emph{Standard}: 12993Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 12994 12995@item @emph{Class}: 12996Inquiry function 12997 12998@item @emph{Syntax}: 12999@code{RESULT = SHAPE(SOURCE [, KIND])} 13000 13001@item @emph{Arguments}: 13002@multitable @columnfractions .15 .70 13003@item @var{SOURCE} @tab Shall be an array or scalar of any type. 13004If @var{SOURCE} is a pointer it must be associated and allocatable 13005arrays must be allocated. 13006@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13007expression indicating the kind parameter of the result. 13008@end multitable 13009 13010@item @emph{Return value}: 13011An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 13012has dimensions. The elements of the resulting array correspond to the extend 13013of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar, 13014the result is the rank one array of size zero. If @var{KIND} is absent, the 13015return value has the default integer kind otherwise the specified kind. 13016 13017@item @emph{Example}: 13018@smallexample 13019PROGRAM test_shape 13020 INTEGER, DIMENSION(-1:1, -1:2) :: A 13021 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) 13022 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) 13023END PROGRAM 13024@end smallexample 13025 13026@item @emph{See also}: 13027@ref{RESHAPE}, @gol 13028@ref{SIZE} 13029@end table 13030 13031 13032 13033@node SHIFTA 13034@section @code{SHIFTA} --- Right shift with fill 13035@fnindex SHIFTA 13036@cindex bits, shift right 13037@cindex shift, right with fill 13038 13039@table @asis 13040@item @emph{Description}: 13041@code{SHIFTA} returns a value corresponding to @var{I} with all of the 13042bits shifted right by @var{SHIFT} places. @var{SHIFT} that be 13043nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 13044the result value is undefined. Bits shifted out from the right end 13045are lost. The fill is arithmetic: the bits shifted in from the left 13046end are equal to the leftmost bit, which in two's complement 13047representation is the sign bit. 13048 13049@item @emph{Standard}: 13050Fortran 2008 and later 13051 13052@item @emph{Class}: 13053Elemental function 13054 13055@item @emph{Syntax}: 13056@code{RESULT = SHIFTA(I, SHIFT)} 13057 13058@item @emph{Arguments}: 13059@multitable @columnfractions .15 .70 13060@item @var{I} @tab The type shall be @code{INTEGER}. 13061@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13062@end multitable 13063 13064@item @emph{Return value}: 13065The return value is of type @code{INTEGER} and of the same kind as 13066@var{I}. 13067 13068@item @emph{See also}: 13069@ref{SHIFTL}, @gol 13070@ref{SHIFTR} 13071@end table 13072 13073 13074 13075@node SHIFTL 13076@section @code{SHIFTL} --- Left shift 13077@fnindex SHIFTL 13078@cindex bits, shift left 13079@cindex shift, left 13080 13081@table @asis 13082@item @emph{Description}: 13083@code{SHIFTL} returns a value corresponding to @var{I} with all of the 13084bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be 13085nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 13086the result value is undefined. Bits shifted out from the left end are 13087lost, and bits shifted in from the right end are set to 0. 13088 13089@item @emph{Standard}: 13090Fortran 2008 and later 13091 13092@item @emph{Class}: 13093Elemental function 13094 13095@item @emph{Syntax}: 13096@code{RESULT = SHIFTL(I, SHIFT)} 13097 13098@item @emph{Arguments}: 13099@multitable @columnfractions .15 .70 13100@item @var{I} @tab The type shall be @code{INTEGER}. 13101@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13102@end multitable 13103 13104@item @emph{Return value}: 13105The return value is of type @code{INTEGER} and of the same kind as 13106@var{I}. 13107 13108@item @emph{See also}: 13109@ref{SHIFTA}, @gol 13110@ref{SHIFTR} 13111@end table 13112 13113 13114 13115@node SHIFTR 13116@section @code{SHIFTR} --- Right shift 13117@fnindex SHIFTR 13118@cindex bits, shift right 13119@cindex shift, right 13120 13121@table @asis 13122@item @emph{Description}: 13123@code{SHIFTR} returns a value corresponding to @var{I} with all of the 13124bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be 13125nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 13126the result value is undefined. Bits shifted out from the right end 13127are lost, and bits shifted in from the left end are set to 0. 13128 13129@item @emph{Standard}: 13130Fortran 2008 and later 13131 13132@item @emph{Class}: 13133Elemental function 13134 13135@item @emph{Syntax}: 13136@code{RESULT = SHIFTR(I, SHIFT)} 13137 13138@item @emph{Arguments}: 13139@multitable @columnfractions .15 .70 13140@item @var{I} @tab The type shall be @code{INTEGER}. 13141@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13142@end multitable 13143 13144@item @emph{Return value}: 13145The return value is of type @code{INTEGER} and of the same kind as 13146@var{I}. 13147 13148@item @emph{See also}: 13149@ref{SHIFTA}, @gol 13150@ref{SHIFTL} 13151@end table 13152 13153 13154 13155@node SIGN 13156@section @code{SIGN} --- Sign copying function 13157@fnindex SIGN 13158@fnindex ISIGN 13159@fnindex DSIGN 13160@cindex sign copying 13161 13162@table @asis 13163@item @emph{Description}: 13164@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}. 13165 13166@item @emph{Standard}: 13167Fortran 77 and later 13168 13169@item @emph{Class}: 13170Elemental function 13171 13172@item @emph{Syntax}: 13173@code{RESULT = SIGN(A, B)} 13174 13175@item @emph{Arguments}: 13176@multitable @columnfractions .15 .70 13177@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL} 13178@item @var{B} @tab Shall be of the same type and kind as @var{A}. 13179@end multitable 13180 13181@item @emph{Return value}: 13182The kind of the return value is that of @var{A} and @var{B}. 13183If @math{B\ge 0} then the result is @code{ABS(A)}, else 13184it is @code{-ABS(A)}. 13185 13186@item @emph{Example}: 13187@smallexample 13188program test_sign 13189 print *, sign(-12,1) 13190 print *, sign(-12,0) 13191 print *, sign(-12,-1) 13192 13193 print *, sign(-12.,1.) 13194 print *, sign(-12.,0.) 13195 print *, sign(-12.,-1.) 13196end program test_sign 13197@end smallexample 13198 13199@item @emph{Specific names}: 13200@multitable @columnfractions .20 .20 .20 .25 13201@item Name @tab Arguments @tab Return type @tab Standard 13202@item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later 13203@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later 13204@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later 13205@end multitable 13206@end table 13207 13208 13209 13210@node SIGNAL 13211@section @code{SIGNAL} --- Signal handling subroutine (or function) 13212@fnindex SIGNAL 13213@cindex system, signal handling 13214 13215@table @asis 13216@item @emph{Description}: 13217@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine 13218@var{HANDLER} to be executed with a single integer argument when signal 13219@var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to 13220turn off handling of signal @var{NUMBER} or revert to its default 13221action. See @code{signal(2)}. 13222 13223If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument 13224is supplied, it is set to the value returned by @code{signal(2)}. 13225 13226@item @emph{Standard}: 13227GNU extension 13228 13229@item @emph{Class}: 13230Subroutine, function 13231 13232@item @emph{Syntax}: 13233@multitable @columnfractions .80 13234@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])} 13235@item @code{STATUS = SIGNAL(NUMBER, HANDLER)} 13236@end multitable 13237 13238@item @emph{Arguments}: 13239@multitable @columnfractions .15 .70 13240@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)} 13241@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or 13242@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. 13243@code{INTEGER}. It is @code{INTENT(IN)}. 13244@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 13245integer. It has @code{INTENT(OUT)}. 13246@end multitable 13247@c TODO: What should the interface of the handler be? Does it take arguments? 13248 13249@item @emph{Return value}: 13250The @code{SIGNAL} function returns the value returned by @code{signal(2)}. 13251 13252@item @emph{Example}: 13253@smallexample 13254program test_signal 13255 intrinsic signal 13256 external handler_print 13257 13258 call signal (12, handler_print) 13259 call signal (10, 1) 13260 13261 call sleep (30) 13262end program test_signal 13263@end smallexample 13264@end table 13265 13266 13267 13268@node SIN 13269@section @code{SIN} --- Sine function 13270@fnindex SIN 13271@fnindex DSIN 13272@fnindex CSIN 13273@fnindex ZSIN 13274@fnindex CDSIN 13275@cindex trigonometric function, sine 13276@cindex sine 13277 13278@table @asis 13279@item @emph{Description}: 13280@code{SIN(X)} computes the sine of @var{X}. 13281 13282@item @emph{Standard}: 13283Fortran 77 and later 13284 13285@item @emph{Class}: 13286Elemental function 13287 13288@item @emph{Syntax}: 13289@code{RESULT = SIN(X)} 13290 13291@item @emph{Arguments}: 13292@multitable @columnfractions .15 .70 13293@item @var{X} @tab The type shall be @code{REAL} or 13294@code{COMPLEX}. 13295@end multitable 13296 13297@item @emph{Return value}: 13298The return value has same type and kind as @var{X}. 13299 13300@item @emph{Example}: 13301@smallexample 13302program test_sin 13303 real :: x = 0.0 13304 x = sin(x) 13305end program test_sin 13306@end smallexample 13307 13308@item @emph{Specific names}: 13309@multitable @columnfractions .20 .20 .20 .25 13310@item Name @tab Argument @tab Return type @tab Standard 13311@item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 13312@item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 13313@item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 13314@item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13315@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13316@end multitable 13317 13318@item @emph{See also}: 13319Inverse function: @gol 13320@ref{ASIN} @gol 13321Degrees function: @gol 13322@ref{SIND} 13323@end table 13324 13325 13326 13327@node SIND 13328@section @code{SIND} --- Sine function, degrees 13329@fnindex SIND 13330@fnindex DSIND 13331@fnindex CSIND 13332@fnindex ZSIND 13333@fnindex CDSIND 13334@cindex trigonometric function, sine, degrees 13335@cindex sine, degrees 13336 13337@table @asis 13338@item @emph{Description}: 13339@code{SIND(X)} computes the sine of @var{X} in degrees. 13340 13341This function is for compatibility only and should be avoided in favor of 13342standard constructs wherever possible. 13343 13344@item @emph{Standard}: 13345GNU extension, enabled with @option{-fdec-math}. 13346 13347@item @emph{Class}: 13348Elemental function 13349 13350@item @emph{Syntax}: 13351@code{RESULT = SIND(X)} 13352 13353@item @emph{Arguments}: 13354@multitable @columnfractions .15 .70 13355@item @var{X} @tab The type shall be @code{REAL} or 13356@code{COMPLEX}. 13357@end multitable 13358 13359@item @emph{Return value}: 13360The return value has same type and kind as @var{X}, and its value is in degrees. 13361 13362@item @emph{Example}: 13363@smallexample 13364program test_sind 13365 real :: x = 0.0 13366 x = sind(x) 13367end program test_sind 13368@end smallexample 13369 13370@item @emph{Specific names}: 13371@multitable @columnfractions .20 .20 .20 .25 13372@item Name @tab Argument @tab Return type @tab Standard 13373@item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 13374@item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 13375@item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension 13376@item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13377@item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13378@end multitable 13379 13380@item @emph{See also}: 13381Inverse function: @gol 13382@ref{ASIND} @gol 13383Radians function: @gol 13384@ref{SIN} @gol 13385@end table 13386 13387 13388 13389@node SINH 13390@section @code{SINH} --- Hyperbolic sine function 13391@fnindex SINH 13392@fnindex DSINH 13393@cindex hyperbolic sine 13394@cindex hyperbolic function, sine 13395@cindex sine, hyperbolic 13396 13397@table @asis 13398@item @emph{Description}: 13399@code{SINH(X)} computes the hyperbolic sine of @var{X}. 13400 13401@item @emph{Standard}: 13402Fortran 90 and later, for a complex argument Fortran 2008 or later, has 13403a GNU extension 13404 13405@item @emph{Class}: 13406Elemental function 13407 13408@item @emph{Syntax}: 13409@code{RESULT = SINH(X)} 13410 13411@item @emph{Arguments}: 13412@multitable @columnfractions .15 .70 13413@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13414@end multitable 13415 13416@item @emph{Return value}: 13417The return value has same type and kind as @var{X}. 13418 13419@item @emph{Example}: 13420@smallexample 13421program test_sinh 13422 real(8) :: x = - 1.0_8 13423 x = sinh(x) 13424end program test_sinh 13425@end smallexample 13426 13427@item @emph{Specific names}: 13428@multitable @columnfractions .20 .20 .20 .25 13429@item Name @tab Argument @tab Return type @tab Standard 13430@item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 and later 13431@end multitable 13432 13433@item @emph{See also}: 13434@ref{ASINH} 13435@end table 13436 13437 13438 13439@node SIZE 13440@section @code{SIZE} --- Determine the size of an array 13441@fnindex SIZE 13442@cindex array, size 13443@cindex array, number of elements 13444@cindex array, count elements 13445 13446@table @asis 13447@item @emph{Description}: 13448Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}, 13449or the total number of elements in @var{ARRAY} if @var{DIM} is absent. 13450 13451@item @emph{Standard}: 13452Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 13453 13454@item @emph{Class}: 13455Inquiry function 13456 13457@item @emph{Syntax}: 13458@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])} 13459 13460@item @emph{Arguments}: 13461@multitable @columnfractions .15 .70 13462@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is 13463a pointer it must be associated and allocatable arrays must be allocated. 13464@item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} 13465and its value shall be in the range from 1 to n, where n equals the rank 13466of @var{ARRAY}. 13467@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13468expression indicating the kind parameter of the result. 13469@end multitable 13470 13471@item @emph{Return value}: 13472The return value is of type @code{INTEGER} and of kind @var{KIND}. If 13473@var{KIND} is absent, the return value is of default integer kind. 13474 13475@item @emph{Example}: 13476@smallexample 13477PROGRAM test_size 13478 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 13479END PROGRAM 13480@end smallexample 13481 13482@item @emph{See also}: 13483@ref{SHAPE}, @gol 13484@ref{RESHAPE} 13485@end table 13486 13487 13488@node SIZEOF 13489@section @code{SIZEOF} --- Size in bytes of an expression 13490@fnindex SIZEOF 13491@cindex expression size 13492@cindex size of an expression 13493 13494@table @asis 13495@item @emph{Description}: 13496@code{SIZEOF(X)} calculates the number of bytes of storage the 13497expression @code{X} occupies. 13498 13499@item @emph{Standard}: 13500GNU extension 13501 13502@item @emph{Class}: 13503Inquiry function 13504 13505@item @emph{Syntax}: 13506@code{N = SIZEOF(X)} 13507 13508@item @emph{Arguments}: 13509@multitable @columnfractions .15 .70 13510@item @var{X} @tab The argument shall be of any type, rank or shape. 13511@end multitable 13512 13513@item @emph{Return value}: 13514The return value is of type integer and of the system-dependent kind 13515@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the 13516number of bytes occupied by the argument. If the argument has the 13517@code{POINTER} attribute, the number of bytes of the storage area pointed 13518to is returned. If the argument is of a derived type with @code{POINTER} 13519or @code{ALLOCATABLE} components, the return value does not account for 13520the sizes of the data pointed to by these components. If the argument is 13521polymorphic, the size according to the dynamic type is returned. The argument 13522may not be a procedure or procedure pointer. Note that the code assumes for 13523arrays that those are contiguous; for contiguous arrays, it returns the 13524storage or an array element multiplied by the size of the array. 13525 13526@item @emph{Example}: 13527@smallexample 13528 integer :: i 13529 real :: r, s(5) 13530 print *, (sizeof(s)/sizeof(r) == 5) 13531 end 13532@end smallexample 13533The example will print @code{.TRUE.} unless you are using a platform 13534where default @code{REAL} variables are unusually padded. 13535 13536@item @emph{See also}: 13537@ref{C_SIZEOF}, @gol 13538@ref{STORAGE_SIZE} 13539@end table 13540 13541 13542@node SLEEP 13543@section @code{SLEEP} --- Sleep for the specified number of seconds 13544@fnindex SLEEP 13545@cindex delayed execution 13546 13547@table @asis 13548@item @emph{Description}: 13549Calling this subroutine causes the process to pause for @var{SECONDS} seconds. 13550 13551@item @emph{Standard}: 13552GNU extension 13553 13554@item @emph{Class}: 13555Subroutine 13556 13557@item @emph{Syntax}: 13558@code{CALL SLEEP(SECONDS)} 13559 13560@item @emph{Arguments}: 13561@multitable @columnfractions .15 .70 13562@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}. 13563@end multitable 13564 13565@item @emph{Example}: 13566@smallexample 13567program test_sleep 13568 call sleep(5) 13569end 13570@end smallexample 13571@end table 13572 13573 13574 13575@node SPACING 13576@section @code{SPACING} --- Smallest distance between two numbers of a given type 13577@fnindex SPACING 13578@cindex real number, relative spacing 13579@cindex floating point, relative spacing 13580 13581@table @asis 13582@item @emph{Description}: 13583Determines the distance between the argument @var{X} and the nearest 13584adjacent number of the same type. 13585 13586@item @emph{Standard}: 13587Fortran 90 and later 13588 13589@item @emph{Class}: 13590Elemental function 13591 13592@item @emph{Syntax}: 13593@code{RESULT = SPACING(X)} 13594 13595@item @emph{Arguments}: 13596@multitable @columnfractions .15 .70 13597@item @var{X} @tab Shall be of type @code{REAL}. 13598@end multitable 13599 13600@item @emph{Return value}: 13601The result is of the same type as the input argument @var{X}. 13602 13603@item @emph{Example}: 13604@smallexample 13605PROGRAM test_spacing 13606 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37) 13607 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200) 13608 13609 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686 13610 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686 13611END PROGRAM 13612@end smallexample 13613 13614@item @emph{See also}: 13615@ref{RRSPACING} 13616@end table 13617 13618 13619 13620@node SPREAD 13621@section @code{SPREAD} --- Add a dimension to an array 13622@fnindex SPREAD 13623@cindex array, increase dimension 13624@cindex array, duplicate elements 13625@cindex array, duplicate dimensions 13626 13627@table @asis 13628@item @emph{Description}: 13629Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified 13630dimension @var{DIM}. 13631 13632@item @emph{Standard}: 13633Fortran 90 and later 13634 13635@item @emph{Class}: 13636Transformational function 13637 13638@item @emph{Syntax}: 13639@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)} 13640 13641@item @emph{Arguments}: 13642@multitable @columnfractions .15 .70 13643@item @var{SOURCE} @tab Shall be a scalar or an array of any type and 13644a rank less than seven. 13645@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a 13646value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}. 13647@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}. 13648@end multitable 13649 13650@item @emph{Return value}: 13651The result is an array of the same type as @var{SOURCE} and has rank n+1 13652where n equals the rank of @var{SOURCE}. 13653 13654@item @emph{Example}: 13655@smallexample 13656PROGRAM test_spread 13657 INTEGER :: a = 1, b(2) = (/ 1, 2 /) 13658 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1" 13659 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2" 13660END PROGRAM 13661@end smallexample 13662 13663@item @emph{See also}: 13664@ref{UNPACK} 13665@end table 13666 13667 13668 13669@node SQRT 13670@section @code{SQRT} --- Square-root function 13671@fnindex SQRT 13672@fnindex DSQRT 13673@fnindex CSQRT 13674@fnindex ZSQRT 13675@fnindex CDSQRT 13676@cindex root 13677@cindex square-root 13678 13679@table @asis 13680@item @emph{Description}: 13681@code{SQRT(X)} computes the square root of @var{X}. 13682 13683@item @emph{Standard}: 13684Fortran 77 and later 13685 13686@item @emph{Class}: 13687Elemental function 13688 13689@item @emph{Syntax}: 13690@code{RESULT = SQRT(X)} 13691 13692@item @emph{Arguments}: 13693@multitable @columnfractions .15 .70 13694@item @var{X} @tab The type shall be @code{REAL} or 13695@code{COMPLEX}. 13696@end multitable 13697 13698@item @emph{Return value}: 13699The return value is of type @code{REAL} or @code{COMPLEX}. 13700The kind type parameter is the same as @var{X}. 13701 13702@item @emph{Example}: 13703@smallexample 13704program test_sqrt 13705 real(8) :: x = 2.0_8 13706 complex :: z = (1.0, 2.0) 13707 x = sqrt(x) 13708 z = sqrt(z) 13709end program test_sqrt 13710@end smallexample 13711 13712@item @emph{Specific names}: 13713@multitable @columnfractions .20 .20 .20 .25 13714@item Name @tab Argument @tab Return type @tab Standard 13715@item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 13716@item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 13717@item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 13718@item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13719@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13720@end multitable 13721@end table 13722 13723 13724 13725@node SRAND 13726@section @code{SRAND} --- Reinitialize the random number generator 13727@fnindex SRAND 13728@cindex random number generation, seeding 13729@cindex seeding a random number generator 13730 13731@table @asis 13732@item @emph{Description}: 13733@code{SRAND} reinitializes the pseudo-random number generator 13734called by @code{RAND} and @code{IRAND}. The new seed used by the 13735generator is specified by the required argument @var{SEED}. 13736 13737@item @emph{Standard}: 13738GNU extension 13739 13740@item @emph{Class}: 13741Subroutine 13742 13743@item @emph{Syntax}: 13744@code{CALL SRAND(SEED)} 13745 13746@item @emph{Arguments}: 13747@multitable @columnfractions .15 .70 13748@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}. 13749@end multitable 13750 13751@item @emph{Return value}: 13752Does not return anything. 13753 13754@item @emph{Example}: 13755See @code{RAND} and @code{IRAND} for examples. 13756 13757@item @emph{Notes}: 13758The Fortran standard specifies the intrinsic subroutines 13759@code{RANDOM_SEED} to initialize the pseudo-random number 13760generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers. 13761These subroutines should be used in new codes. 13762 13763Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND}, 13764@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and 13765@code{RANDOM_SEED} on the other hand) access two independent 13766pseudo-random number generators. 13767 13768@item @emph{See also}: 13769@ref{RAND}, @gol 13770@ref{RANDOM_SEED}, @gol 13771@ref{RANDOM_NUMBER} 13772@end table 13773 13774 13775 13776@node STAT 13777@section @code{STAT} --- Get file status 13778@fnindex STAT 13779@cindex file system, file status 13780 13781@table @asis 13782@item @emph{Description}: 13783This function returns information about a file. No permissions are required on 13784the file itself, but execute (search) permission is required on all of the 13785directories in path that lead to the file. 13786 13787The elements that are obtained and stored in the array @code{VALUES}: 13788@multitable @columnfractions .15 .70 13789@item @code{VALUES(1)} @tab Device ID 13790@item @code{VALUES(2)} @tab Inode number 13791@item @code{VALUES(3)} @tab File mode 13792@item @code{VALUES(4)} @tab Number of links 13793@item @code{VALUES(5)} @tab Owner's uid 13794@item @code{VALUES(6)} @tab Owner's gid 13795@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available) 13796@item @code{VALUES(8)} @tab File size (bytes) 13797@item @code{VALUES(9)} @tab Last access time 13798@item @code{VALUES(10)} @tab Last modification time 13799@item @code{VALUES(11)} @tab Last file status change time 13800@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available) 13801@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available) 13802@end multitable 13803 13804Not all these elements are relevant on all systems. 13805If an element is not relevant, it is returned as 0. 13806 13807This intrinsic is provided in both subroutine and function forms; however, 13808only one form can be used in any given program unit. 13809 13810@item @emph{Standard}: 13811GNU extension 13812 13813@item @emph{Class}: 13814Subroutine, function 13815 13816@item @emph{Syntax}: 13817@multitable @columnfractions .80 13818@item @code{CALL STAT(NAME, VALUES [, STATUS])} 13819@item @code{STATUS = STAT(NAME, VALUES)} 13820@end multitable 13821 13822@item @emph{Arguments}: 13823@multitable @columnfractions .15 .70 13824@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the 13825default kind and a valid path within the file system. 13826@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 13827@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 13828on success and a system specific error code otherwise. 13829@end multitable 13830 13831@item @emph{Example}: 13832@smallexample 13833PROGRAM test_stat 13834 INTEGER, DIMENSION(13) :: buff 13835 INTEGER :: status 13836 13837 CALL STAT("/etc/passwd", buff, status) 13838 13839 IF (status == 0) THEN 13840 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1) 13841 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2) 13842 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3) 13843 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4) 13844 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5) 13845 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6) 13846 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7) 13847 WRITE (*, FMT="('File size:', T30, I19)") buff(8) 13848 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9)) 13849 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10)) 13850 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11)) 13851 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12) 13852 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13) 13853 END IF 13854END PROGRAM 13855@end smallexample 13856 13857@item @emph{See also}: 13858To stat an open file: @gol 13859@ref{FSTAT} @gol 13860To stat a link: @gol 13861@ref{LSTAT} 13862@end table 13863 13864 13865 13866@node STORAGE_SIZE 13867@section @code{STORAGE_SIZE} --- Storage size in bits 13868@fnindex STORAGE_SIZE 13869@cindex storage size 13870 13871@table @asis 13872@item @emph{Description}: 13873Returns the storage size of argument @var{A} in bits. 13874@item @emph{Standard}: 13875Fortran 2008 and later 13876@item @emph{Class}: 13877Inquiry function 13878@item @emph{Syntax}: 13879@code{RESULT = STORAGE_SIZE(A [, KIND])} 13880 13881@item @emph{Arguments}: 13882@multitable @columnfractions .15 .70 13883@item @var{A} @tab Shall be a scalar or array of any type. 13884@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression. 13885@end multitable 13886 13887@item @emph{Return Value}: 13888The result is a scalar integer with the kind type parameter specified by KIND 13889(or default integer type if KIND is missing). The result value is the size 13890expressed in bits for an element of an array that has the dynamic type and type 13891parameters of A. 13892 13893@item @emph{See also}: 13894@ref{C_SIZEOF}, @gol 13895@ref{SIZEOF} 13896@end table 13897 13898 13899 13900@node SUM 13901@section @code{SUM} --- Sum of array elements 13902@fnindex SUM 13903@cindex array, sum 13904@cindex array, add elements 13905@cindex array, conditionally add elements 13906@cindex sum array elements 13907 13908@table @asis 13909@item @emph{Description}: 13910Adds the elements of @var{ARRAY} along dimension @var{DIM} if 13911the corresponding element in @var{MASK} is @code{TRUE}. 13912 13913@item @emph{Standard}: 13914Fortran 90 and later 13915 13916@item @emph{Class}: 13917Transformational function 13918 13919@item @emph{Syntax}: 13920@multitable @columnfractions .80 13921@item @code{RESULT = SUM(ARRAY[, MASK])} 13922@item @code{RESULT = SUM(ARRAY, DIM[, MASK])} 13923@end multitable 13924 13925@item @emph{Arguments}: 13926@multitable @columnfractions .15 .70 13927@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 13928@code{REAL} or @code{COMPLEX}. 13929@item @var{DIM} @tab (Optional) shall be a scalar of type 13930@code{INTEGER} with a value in the range from 1 to n, where n 13931equals the rank of @var{ARRAY}. 13932@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 13933and either be a scalar or an array of the same shape as @var{ARRAY}. 13934@end multitable 13935 13936@item @emph{Return value}: 13937The result is of the same type as @var{ARRAY}. 13938 13939If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY} 13940is returned. Otherwise, an array of rank n-1, where n equals the rank of 13941@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} 13942dropped is returned. 13943 13944@item @emph{Example}: 13945@smallexample 13946PROGRAM test_sum 13947 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 13948 print *, SUM(x) ! all elements, sum = 15 13949 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9 13950END PROGRAM 13951@end smallexample 13952 13953@item @emph{See also}: 13954@ref{PRODUCT} 13955@end table 13956 13957 13958 13959@node SYMLNK 13960@section @code{SYMLNK} --- Create a symbolic link 13961@fnindex SYMLNK 13962@cindex file system, create link 13963@cindex file system, soft link 13964 13965@table @asis 13966@item @emph{Description}: 13967Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null 13968character (@code{CHAR(0)}) can be used to mark the end of the names in 13969@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 13970names are ignored. If the @var{STATUS} argument is supplied, it 13971contains 0 on success or a nonzero error code upon return; see 13972@code{symlink(2)}. If the system does not supply @code{symlink(2)}, 13973@code{ENOSYS} is returned. 13974 13975This intrinsic is provided in both subroutine and function forms; 13976however, only one form can be used in any given program unit. 13977 13978@item @emph{Standard}: 13979GNU extension 13980 13981@item @emph{Class}: 13982Subroutine, function 13983 13984@item @emph{Syntax}: 13985@multitable @columnfractions .80 13986@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])} 13987@item @code{STATUS = SYMLNK(PATH1, PATH2)} 13988@end multitable 13989 13990@item @emph{Arguments}: 13991@multitable @columnfractions .15 .70 13992@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 13993@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 13994@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13995@end multitable 13996 13997@item @emph{See also}: 13998@ref{LINK}, @gol 13999@ref{UNLINK} 14000@end table 14001 14002 14003 14004@node SYSTEM 14005@section @code{SYSTEM} --- Execute a shell command 14006@fnindex SYSTEM 14007@cindex system, system call 14008 14009@table @asis 14010@item @emph{Description}: 14011Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If 14012argument @var{STATUS} is present, it contains the value returned by 14013@code{system(3)}, which is presumably 0 if the shell command succeeded. 14014Note that which shell is used to invoke the command is system-dependent 14015and environment-dependent. 14016 14017This intrinsic is provided in both subroutine and function forms; 14018however, only one form can be used in any given program unit. 14019 14020Note that the @code{system} function need not be thread-safe. It is 14021the responsibility of the user to ensure that @code{system} is not 14022called concurrently. 14023 14024@item @emph{Standard}: 14025GNU extension 14026 14027@item @emph{Class}: 14028Subroutine, function 14029 14030@item @emph{Syntax}: 14031@multitable @columnfractions .80 14032@item @code{CALL SYSTEM(COMMAND [, STATUS])} 14033@item @code{STATUS = SYSTEM(COMMAND)} 14034@end multitable 14035 14036@item @emph{Arguments}: 14037@multitable @columnfractions .15 .70 14038@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type. 14039@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 14040@end multitable 14041 14042@item @emph{See also}: 14043@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard 14044and should considered in new code for future portability. 14045@end table 14046 14047 14048 14049@node SYSTEM_CLOCK 14050@section @code{SYSTEM_CLOCK} --- Time function 14051@fnindex SYSTEM_CLOCK 14052@cindex time, clock ticks 14053@cindex clock ticks 14054 14055@table @asis 14056@item @emph{Description}: 14057Determines the @var{COUNT} of a processor clock since an unspecified 14058time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines 14059the number of clock ticks per second. If the platform supports a 14060monotonic clock, that clock is used and can, depending on the platform 14061clock implementation, provide up to nanosecond resolution. If a 14062monotonic clock is not available, the implementation falls back to a 14063realtime clock. 14064 14065@var{COUNT_RATE} is system dependent and can vary depending on the kind of 14066the arguments. For @var{kind=4} arguments (and smaller integer kinds), 14067@var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and 14068larger integer kinds), @var{COUNT} typically represents micro- or 14069nanoseconds depending on resolution of the underlying platform clock. 14070@var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the 14071millisecond resolution of the @var{kind=4} version implies that the 14072@var{COUNT} will wrap around in roughly 25 days. In order to avoid issues 14073with the wrap around and for more precise timing, please use the 14074@var{kind=8} version. 14075 14076If there is no clock, or querying the clock fails, @var{COUNT} is set 14077to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are 14078set to zero. 14079 14080When running on a platform using the GNU C library (glibc) version 140812.16 or older, or a derivative thereof, the high resolution monotonic 14082clock is available only when linking with the @var{rt} library. This 14083can be done explicitly by adding the @code{-lrt} flag when linking the 14084application, but is also done implicitly when using OpenMP. 14085 14086On the Windows platform, the version with @var{kind=4} arguments uses 14087the @code{GetTickCount} function, whereas the @var{kind=8} version 14088uses @code{QueryPerformanceCounter} and 14089@code{QueryPerformanceCounterFrequency}. For more information, and 14090potential caveats, please see the platform documentation. 14091 14092@item @emph{Standard}: 14093Fortran 90 and later 14094 14095@item @emph{Class}: 14096Subroutine 14097 14098@item @emph{Syntax}: 14099@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} 14100 14101@item @emph{Arguments}: 14102@multitable @columnfractions .20 .65 14103@item @var{COUNT} @tab (Optional) shall be a scalar of type 14104@code{INTEGER} with @code{INTENT(OUT)}. 14105@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type 14106@code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}. 14107@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type 14108@code{INTEGER} with @code{INTENT(OUT)}. 14109@end multitable 14110 14111@item @emph{Example}: 14112@smallexample 14113PROGRAM test_system_clock 14114 INTEGER :: count, count_rate, count_max 14115 CALL SYSTEM_CLOCK(count, count_rate, count_max) 14116 WRITE(*,*) count, count_rate, count_max 14117END PROGRAM 14118@end smallexample 14119 14120@item @emph{See also}: 14121@ref{DATE_AND_TIME}, @gol 14122@ref{CPU_TIME} 14123@end table 14124 14125 14126 14127@node TAN 14128@section @code{TAN} --- Tangent function 14129@fnindex TAN 14130@fnindex DTAN 14131@cindex trigonometric function, tangent 14132@cindex tangent 14133 14134@table @asis 14135@item @emph{Description}: 14136@code{TAN(X)} computes the tangent of @var{X}. 14137 14138@item @emph{Standard}: 14139Fortran 77 and later, for a complex argument Fortran 2008 or later 14140 14141@item @emph{Class}: 14142Elemental function 14143 14144@item @emph{Syntax}: 14145@code{RESULT = TAN(X)} 14146 14147@item @emph{Arguments}: 14148@multitable @columnfractions .15 .70 14149@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14150@end multitable 14151 14152@item @emph{Return value}: 14153The return value has same type and kind as @var{X}, and its value is in radians. 14154 14155@item @emph{Example}: 14156@smallexample 14157program test_tan 14158 real(8) :: x = 0.165_8 14159 x = tan(x) 14160end program test_tan 14161@end smallexample 14162 14163@item @emph{Specific names}: 14164@multitable @columnfractions .20 .20 .20 .25 14165@item Name @tab Argument @tab Return type @tab Standard 14166@item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 14167@item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 14168@end multitable 14169 14170@item @emph{See also}: 14171Inverse function: @gol 14172@ref{ATAN} @gol 14173Degrees function: @gol 14174@ref{TAND} 14175@end table 14176 14177 14178 14179@node TAND 14180@section @code{TAND} --- Tangent function, degrees 14181@fnindex TAND 14182@fnindex DTAND 14183@cindex trigonometric function, tangent, degrees 14184@cindex tangent, degrees 14185 14186@table @asis 14187@item @emph{Description}: 14188@code{TAND(X)} computes the tangent of @var{X} in degrees. 14189 14190This function is for compatibility only and should be avoided in favor of 14191standard constructs wherever possible. 14192 14193@item @emph{Standard}: 14194GNU extension, enabled with @option{-fdec-math}. 14195 14196@item @emph{Class}: 14197Elemental function 14198 14199@item @emph{Syntax}: 14200@code{RESULT = TAND(X)} 14201 14202@item @emph{Arguments}: 14203@multitable @columnfractions .15 .70 14204@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14205@end multitable 14206 14207@item @emph{Return value}: 14208The return value has same type and kind as @var{X}, and its value is in degrees. 14209 14210@item @emph{Example}: 14211@smallexample 14212program test_tand 14213 real(8) :: x = 0.165_8 14214 x = tand(x) 14215end program test_tand 14216@end smallexample 14217 14218@item @emph{Specific names}: 14219@multitable @columnfractions .20 .20 .20 .25 14220@item Name @tab Argument @tab Return type @tab Standard 14221@item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 14222@item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 14223@end multitable 14224 14225@item @emph{See also}: 14226Inverse function: @gol 14227@ref{ATAND} @gol 14228Radians function: @gol 14229@ref{TAN} 14230@end table 14231 14232 14233 14234@node TANH 14235@section @code{TANH} --- Hyperbolic tangent function 14236@fnindex TANH 14237@fnindex DTANH 14238@cindex hyperbolic tangent 14239@cindex hyperbolic function, tangent 14240@cindex tangent, hyperbolic 14241 14242@table @asis 14243@item @emph{Description}: 14244@code{TANH(X)} computes the hyperbolic tangent of @var{X}. 14245 14246@item @emph{Standard}: 14247Fortran 77 and later, for a complex argument Fortran 2008 or later 14248 14249@item @emph{Class}: 14250Elemental function 14251 14252@item @emph{Syntax}: 14253@code{X = TANH(X)} 14254 14255@item @emph{Arguments}: 14256@multitable @columnfractions .15 .70 14257@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14258@end multitable 14259 14260@item @emph{Return value}: 14261The return value has same type and kind as @var{X}. If @var{X} is 14262complex, the imaginary part of the result is in radians. If @var{X} 14263is @code{REAL}, the return value lies in the range 14264@math{ - 1 \leq tanh(x) \leq 1 }. 14265 14266@item @emph{Example}: 14267@smallexample 14268program test_tanh 14269 real(8) :: x = 2.1_8 14270 x = tanh(x) 14271end program test_tanh 14272@end smallexample 14273 14274@item @emph{Specific names}: 14275@multitable @columnfractions .20 .20 .20 .25 14276@item Name @tab Argument @tab Return type @tab Standard 14277@item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 14278@item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 14279@end multitable 14280 14281@item @emph{See also}: 14282@ref{ATANH} 14283@end table 14284 14285 14286 14287@node THIS_IMAGE 14288@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image 14289@fnindex THIS_IMAGE 14290@cindex coarray, @code{THIS_IMAGE} 14291@cindex images, index of this image 14292 14293@table @asis 14294@item @emph{Description}: 14295Returns the cosubscript for this image. 14296 14297@item @emph{Standard}: 14298Fortran 2008 and later. With @var{DISTANCE} argument, 14299Technical Specification (TS) 18508 or later 14300 14301@item @emph{Class}: 14302Transformational function 14303 14304@item @emph{Syntax}: 14305@multitable @columnfractions .80 14306@item @code{RESULT = THIS_IMAGE()} 14307@item @code{RESULT = THIS_IMAGE(DISTANCE)} 14308@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} 14309@end multitable 14310 14311@item @emph{Arguments}: 14312@multitable @columnfractions .15 .70 14313@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 14314(not permitted together with @var{COARRAY}). 14315@item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} 14316present, required). 14317@item @var{DIM} @tab default integer scalar (optional). If present, 14318@var{DIM} shall be between one and the corank of @var{COARRAY}. 14319@end multitable 14320 14321 14322@item @emph{Return value}: 14323Default integer. If @var{COARRAY} is not present, it is scalar; if 14324@var{DISTANCE} is not present or has value 0, its value is the image index on 14325the invoking image for the current team, for values smaller or equal 14326distance to the initial team, it returns the image index on the ancestor team 14327which has a distance of @var{DISTANCE} from the invoking team. If 14328@var{DISTANCE} is larger than the distance to the initial team, the image 14329index of the initial team is returned. Otherwise when the @var{COARRAY} is 14330present, if @var{DIM} is not present, a rank-1 array with corank elements is 14331returned, containing the cosubscripts for @var{COARRAY} specifying the invoking 14332image. If @var{DIM} is present, a scalar is returned, with the value of 14333the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}. 14334 14335@item @emph{Example}: 14336@smallexample 14337INTEGER :: value[*] 14338INTEGER :: i 14339value = THIS_IMAGE() 14340SYNC ALL 14341IF (THIS_IMAGE() == 1) THEN 14342 DO i = 1, NUM_IMAGES() 14343 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 14344 END DO 14345END IF 14346 14347! Check whether the current image is the initial image 14348IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) 14349 error stop "something is rotten here" 14350@end smallexample 14351 14352@item @emph{See also}: 14353@ref{NUM_IMAGES}, @gol 14354@ref{IMAGE_INDEX} 14355@end table 14356 14357 14358 14359@node TIME 14360@section @code{TIME} --- Time function 14361@fnindex TIME 14362@cindex time, current 14363@cindex current time 14364 14365@table @asis 14366@item @emph{Description}: 14367Returns the current time encoded as an integer (in the manner of the 14368function @code{time(3)} in the C standard library). This value is 14369suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 14370 14371This intrinsic is not fully portable, such as to systems with 32-bit 14372@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 14373the values returned by this intrinsic might be, or become, negative, or 14374numerically less than previous values, during a single run of the 14375compiled program. 14376 14377See @ref{TIME8}, for information on a similar intrinsic that might be 14378portable to more GNU Fortran implementations, though to fewer Fortran 14379compilers. 14380 14381@item @emph{Standard}: 14382GNU extension 14383 14384@item @emph{Class}: 14385Function 14386 14387@item @emph{Syntax}: 14388@code{RESULT = TIME()} 14389 14390@item @emph{Return value}: 14391The return value is a scalar of type @code{INTEGER(4)}. 14392 14393@item @emph{See also}: 14394@ref{DATE_AND_TIME}, @gol 14395@ref{CTIME}, @gol 14396@ref{GMTIME}, @gol 14397@ref{LTIME}, @gol 14398@ref{MCLOCK}, @gol 14399@ref{TIME8} 14400@end table 14401 14402 14403 14404@node TIME8 14405@section @code{TIME8} --- Time function (64-bit) 14406@fnindex TIME8 14407@cindex time, current 14408@cindex current time 14409 14410@table @asis 14411@item @emph{Description}: 14412Returns the current time encoded as an integer (in the manner of the 14413function @code{time(3)} in the C standard library). This value is 14414suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 14415 14416@emph{Warning:} this intrinsic does not increase the range of the timing 14417values over that returned by @code{time(3)}. On a system with a 32-bit 14418@code{time(3)}, @code{TIME8} will return a 32-bit value, even though 14419it is converted to a 64-bit @code{INTEGER(8)} value. That means 14420overflows of the 32-bit value can still occur. Therefore, the values 14421returned by this intrinsic might be or become negative or numerically 14422less than previous values during a single run of the compiled program. 14423 14424@item @emph{Standard}: 14425GNU extension 14426 14427@item @emph{Class}: 14428Function 14429 14430@item @emph{Syntax}: 14431@code{RESULT = TIME8()} 14432 14433@item @emph{Return value}: 14434The return value is a scalar of type @code{INTEGER(8)}. 14435 14436@item @emph{See also}: 14437@ref{DATE_AND_TIME}, @gol 14438@ref{CTIME}, @gol 14439@ref{GMTIME}, @gol 14440@ref{LTIME}, @gol 14441@ref{MCLOCK8}, @gol 14442@ref{TIME} 14443@end table 14444 14445 14446 14447@node TINY 14448@section @code{TINY} --- Smallest positive number of a real kind 14449@fnindex TINY 14450@cindex limits, smallest number 14451@cindex model representation, smallest number 14452 14453@table @asis 14454@item @emph{Description}: 14455@code{TINY(X)} returns the smallest positive (non zero) number 14456in the model of the type of @code{X}. 14457 14458@item @emph{Standard}: 14459Fortran 90 and later 14460 14461@item @emph{Class}: 14462Inquiry function 14463 14464@item @emph{Syntax}: 14465@code{RESULT = TINY(X)} 14466 14467@item @emph{Arguments}: 14468@multitable @columnfractions .15 .70 14469@item @var{X} @tab Shall be of type @code{REAL}. 14470@end multitable 14471 14472@item @emph{Return value}: 14473The return value is of the same type and kind as @var{X} 14474 14475@item @emph{Example}: 14476See @code{HUGE} for an example. 14477@end table 14478 14479 14480 14481@node TRAILZ 14482@section @code{TRAILZ} --- Number of trailing zero bits of an integer 14483@fnindex TRAILZ 14484@cindex zero bits 14485 14486@table @asis 14487@item @emph{Description}: 14488@code{TRAILZ} returns the number of trailing zero bits of an integer. 14489 14490@item @emph{Standard}: 14491Fortran 2008 and later 14492 14493@item @emph{Class}: 14494Elemental function 14495 14496@item @emph{Syntax}: 14497@code{RESULT = TRAILZ(I)} 14498 14499@item @emph{Arguments}: 14500@multitable @columnfractions .15 .70 14501@item @var{I} @tab Shall be of type @code{INTEGER}. 14502@end multitable 14503 14504@item @emph{Return value}: 14505The type of the return value is the default @code{INTEGER}. 14506If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 14507 14508@item @emph{Example}: 14509@smallexample 14510PROGRAM test_trailz 14511 WRITE (*,*) TRAILZ(8) ! prints 3 14512END PROGRAM 14513@end smallexample 14514 14515@item @emph{See also}: 14516@ref{BIT_SIZE}, @gol 14517@ref{LEADZ}, @gol 14518@ref{POPPAR}, @gol 14519@ref{POPCNT} 14520@end table 14521 14522 14523 14524@node TRANSFER 14525@section @code{TRANSFER} --- Transfer bit patterns 14526@fnindex TRANSFER 14527@cindex bits, move 14528@cindex type cast 14529 14530@table @asis 14531@item @emph{Description}: 14532Interprets the bitwise representation of @var{SOURCE} in memory as if it 14533is the representation of a variable or array of the same type and type 14534parameters as @var{MOLD}. 14535 14536This is approximately equivalent to the C concept of @emph{casting} one 14537type to another. 14538 14539@item @emph{Standard}: 14540Fortran 90 and later 14541 14542@item @emph{Class}: 14543Transformational function 14544 14545@item @emph{Syntax}: 14546@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])} 14547 14548@item @emph{Arguments}: 14549@multitable @columnfractions .15 .70 14550@item @var{SOURCE} @tab Shall be a scalar or an array of any type. 14551@item @var{MOLD} @tab Shall be a scalar or an array of any type. 14552@item @var{SIZE} @tab (Optional) shall be a scalar of type 14553@code{INTEGER}. 14554@end multitable 14555 14556@item @emph{Return value}: 14557The result has the same type as @var{MOLD}, with the bit level 14558representation of @var{SOURCE}. If @var{SIZE} is present, the result is 14559a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent 14560but @var{MOLD} is an array (of any size or shape), the result is a one- 14561dimensional array of the minimum length needed to contain the entirety 14562of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent 14563and @var{MOLD} is a scalar, the result is a scalar. 14564 14565If the bitwise representation of the result is longer than that of 14566@var{SOURCE}, then the leading bits of the result correspond to those of 14567@var{SOURCE} and any trailing bits are filled arbitrarily. 14568 14569When the resulting bit representation does not correspond to a valid 14570representation of a variable of the same type as @var{MOLD}, the results 14571are undefined, and subsequent operations on the result cannot be 14572guaranteed to produce sensible behavior. For example, it is possible to 14573create @code{LOGICAL} variables for which @code{@var{VAR}} and 14574@code{.NOT.@var{VAR}} both appear to be true. 14575 14576@item @emph{Example}: 14577@smallexample 14578PROGRAM test_transfer 14579 integer :: x = 2143289344 14580 print *, transfer(x, 1.0) ! prints "NaN" on i686 14581END PROGRAM 14582@end smallexample 14583@end table 14584 14585 14586 14587@node TRANSPOSE 14588@section @code{TRANSPOSE} --- Transpose an array of rank two 14589@fnindex TRANSPOSE 14590@cindex array, transpose 14591@cindex matrix, transpose 14592@cindex transpose 14593 14594@table @asis 14595@item @emph{Description}: 14596Transpose an array of rank two. Element (i, j) of the result has the value 14597@code{MATRIX(j, i)}, for all i, j. 14598 14599@item @emph{Standard}: 14600Fortran 90 and later 14601 14602@item @emph{Class}: 14603Transformational function 14604 14605@item @emph{Syntax}: 14606@code{RESULT = TRANSPOSE(MATRIX)} 14607 14608@item @emph{Arguments}: 14609@multitable @columnfractions .15 .70 14610@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two. 14611@end multitable 14612 14613@item @emph{Return value}: 14614The result has the same type as @var{MATRIX}, and has shape 14615@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}. 14616@end table 14617 14618 14619 14620@node TRIM 14621@section @code{TRIM} --- Remove trailing blank characters of a string 14622@fnindex TRIM 14623@cindex string, remove trailing whitespace 14624 14625@table @asis 14626@item @emph{Description}: 14627Removes trailing blank characters of a string. 14628 14629@item @emph{Standard}: 14630Fortran 90 and later 14631 14632@item @emph{Class}: 14633Transformational function 14634 14635@item @emph{Syntax}: 14636@code{RESULT = TRIM(STRING)} 14637 14638@item @emph{Arguments}: 14639@multitable @columnfractions .15 .70 14640@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}. 14641@end multitable 14642 14643@item @emph{Return value}: 14644A scalar of type @code{CHARACTER} which length is that of @var{STRING} 14645less the number of trailing blanks. 14646 14647@item @emph{Example}: 14648@smallexample 14649PROGRAM test_trim 14650 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " 14651 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks 14652END PROGRAM 14653@end smallexample 14654 14655@item @emph{See also}: 14656@ref{ADJUSTL}, @gol 14657@ref{ADJUSTR} 14658@end table 14659 14660 14661 14662@node TTYNAM 14663@section @code{TTYNAM} --- Get the name of a terminal device. 14664@fnindex TTYNAM 14665@cindex system, terminal 14666 14667@table @asis 14668@item @emph{Description}: 14669Get the name of a terminal device. For more information, 14670see @code{ttyname(3)}. 14671 14672This intrinsic is provided in both subroutine and function forms; 14673however, only one form can be used in any given program unit. 14674 14675@item @emph{Standard}: 14676GNU extension 14677 14678@item @emph{Class}: 14679Subroutine, function 14680 14681@item @emph{Syntax}: 14682@multitable @columnfractions .80 14683@item @code{CALL TTYNAM(UNIT, NAME)} 14684@item @code{NAME = TTYNAM(UNIT)} 14685@end multitable 14686 14687@item @emph{Arguments}: 14688@multitable @columnfractions .15 .70 14689@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 14690@item @var{NAME} @tab Shall be of type @code{CHARACTER}. 14691@end multitable 14692 14693@item @emph{Example}: 14694@smallexample 14695PROGRAM test_ttynam 14696 INTEGER :: unit 14697 DO unit = 1, 10 14698 IF (isatty(unit=unit)) write(*,*) ttynam(unit) 14699 END DO 14700END PROGRAM 14701@end smallexample 14702 14703@item @emph{See also}: 14704@ref{ISATTY} 14705@end table 14706 14707 14708 14709@node UBOUND 14710@section @code{UBOUND} --- Upper dimension bounds of an array 14711@fnindex UBOUND 14712@cindex array, upper bound 14713 14714@table @asis 14715@item @emph{Description}: 14716Returns the upper bounds of an array, or a single upper bound 14717along the @var{DIM} dimension. 14718@item @emph{Standard}: 14719Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 14720 14721@item @emph{Class}: 14722Inquiry function 14723 14724@item @emph{Syntax}: 14725@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])} 14726 14727@item @emph{Arguments}: 14728@multitable @columnfractions .15 .70 14729@item @var{ARRAY} @tab Shall be an array, of any type. 14730@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14731@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization 14732expression indicating the kind parameter of the result. 14733@end multitable 14734 14735@item @emph{Return value}: 14736The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14737@var{KIND} is absent, the return value is of default integer kind. 14738If @var{DIM} is absent, the result is an array of the upper bounds of 14739@var{ARRAY}. If @var{DIM} is present, the result is a scalar 14740corresponding to the upper bound of the array along that dimension. If 14741@var{ARRAY} is an expression rather than a whole array or array 14742structure component, or if it has a zero extent along the relevant 14743dimension, the upper bound is taken to be the number of elements along 14744the relevant dimension. 14745 14746@item @emph{See also}: 14747@ref{LBOUND}, @gol 14748@ref{LCOBOUND} 14749@end table 14750 14751 14752 14753@node UCOBOUND 14754@section @code{UCOBOUND} --- Upper codimension bounds of an array 14755@fnindex UCOBOUND 14756@cindex coarray, upper bound 14757 14758@table @asis 14759@item @emph{Description}: 14760Returns the upper cobounds of a coarray, or a single upper cobound 14761along the @var{DIM} codimension. 14762@item @emph{Standard}: 14763Fortran 2008 and later 14764 14765@item @emph{Class}: 14766Inquiry function 14767 14768@item @emph{Syntax}: 14769@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])} 14770 14771@item @emph{Arguments}: 14772@multitable @columnfractions .15 .70 14773@item @var{ARRAY} @tab Shall be an coarray, of any type. 14774@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14775@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14776expression indicating the kind parameter of the result. 14777@end multitable 14778 14779@item @emph{Return value}: 14780The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14781@var{KIND} is absent, the return value is of default integer kind. 14782If @var{DIM} is absent, the result is an array of the lower cobounds of 14783@var{COARRAY}. If @var{DIM} is present, the result is a scalar 14784corresponding to the lower cobound of the array along that codimension. 14785 14786@item @emph{See also}: 14787@ref{LCOBOUND}, @gol 14788@ref{LBOUND} 14789@end table 14790 14791 14792 14793@node UMASK 14794@section @code{UMASK} --- Set the file creation mask 14795@fnindex UMASK 14796@cindex file system, file creation mask 14797 14798@table @asis 14799@item @emph{Description}: 14800Sets the file creation mask to @var{MASK}. If called as a function, it 14801returns the old value. If called as a subroutine and argument @var{OLD} 14802if it is supplied, it is set to the old value. See @code{umask(2)}. 14803 14804@item @emph{Standard}: 14805GNU extension 14806 14807@item @emph{Class}: 14808Subroutine, function 14809 14810@item @emph{Syntax}: 14811@multitable @columnfractions .80 14812@item @code{CALL UMASK(MASK [, OLD])} 14813@item @code{OLD = UMASK(MASK)} 14814@end multitable 14815 14816@item @emph{Arguments}: 14817@multitable @columnfractions .15 .70 14818@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}. 14819@item @var{OLD} @tab (Optional) Shall be a scalar of type 14820@code{INTEGER}. 14821@end multitable 14822 14823@end table 14824 14825 14826 14827@node UNLINK 14828@section @code{UNLINK} --- Remove a file from the file system 14829@fnindex UNLINK 14830@cindex file system, remove file 14831 14832@table @asis 14833@item @emph{Description}: 14834Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be 14835used to mark the end of the name in @var{PATH}; otherwise, trailing 14836blanks in the file name are ignored. If the @var{STATUS} argument is 14837supplied, it contains 0 on success or a nonzero error code upon return; 14838see @code{unlink(2)}. 14839 14840This intrinsic is provided in both subroutine and function forms; 14841however, only one form can be used in any given program unit. 14842 14843@item @emph{Standard}: 14844GNU extension 14845 14846@item @emph{Class}: 14847Subroutine, function 14848 14849@item @emph{Syntax}: 14850@multitable @columnfractions .80 14851@item @code{CALL UNLINK(PATH [, STATUS])} 14852@item @code{STATUS = UNLINK(PATH)} 14853@end multitable 14854 14855@item @emph{Arguments}: 14856@multitable @columnfractions .15 .70 14857@item @var{PATH} @tab Shall be of default @code{CHARACTER} type. 14858@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 14859@end multitable 14860 14861@item @emph{See also}: 14862@ref{LINK}, @gol 14863@ref{SYMLNK} 14864@end table 14865 14866 14867 14868@node UNPACK 14869@section @code{UNPACK} --- Unpack an array of rank one into an array 14870@fnindex UNPACK 14871@cindex array, unpacking 14872@cindex array, increase dimension 14873@cindex array, scatter elements 14874 14875@table @asis 14876@item @emph{Description}: 14877Store the elements of @var{VECTOR} in an array of higher rank. 14878 14879@item @emph{Standard}: 14880Fortran 90 and later 14881 14882@item @emph{Class}: 14883Transformational function 14884 14885@item @emph{Syntax}: 14886@code{RESULT = UNPACK(VECTOR, MASK, FIELD)} 14887 14888@item @emph{Arguments}: 14889@multitable @columnfractions .15 .70 14890@item @var{VECTOR} @tab Shall be an array of any type and rank one. It 14891shall have at least as many elements as @var{MASK} has @code{TRUE} values. 14892@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}. 14893@item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have 14894the same shape as @var{MASK}. 14895@end multitable 14896 14897@item @emph{Return value}: 14898The resulting array corresponds to @var{FIELD} with @code{TRUE} elements 14899of @var{MASK} replaced by values from @var{VECTOR} in array element order. 14900 14901@item @emph{Example}: 14902@smallexample 14903PROGRAM test_unpack 14904 integer :: vector(2) = (/1,1/) 14905 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /) 14906 integer :: field(2,2) = 0, unity(2,2) 14907 14908 ! result: unity matrix 14909 unity = unpack(vector, reshape(mask, (/2,2/)), field) 14910END PROGRAM 14911@end smallexample 14912 14913@item @emph{See also}: 14914@ref{PACK}, @gol 14915@ref{SPREAD} 14916@end table 14917 14918 14919 14920@node VERIFY 14921@section @code{VERIFY} --- Scan a string for characters not a given set 14922@fnindex VERIFY 14923@cindex string, find missing set 14924 14925@table @asis 14926@item @emph{Description}: 14927Verifies that all the characters in @var{STRING} belong to the set of 14928characters in @var{SET}. 14929 14930If @var{BACK} is either absent or equals @code{FALSE}, this function 14931returns the position of the leftmost character of @var{STRING} that is 14932not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost 14933position is returned. If all characters of @var{STRING} are found in 14934@var{SET}, the result is zero. 14935 14936@item @emph{Standard}: 14937Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 14938 14939@item @emph{Class}: 14940Elemental function 14941 14942@item @emph{Syntax}: 14943@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])} 14944 14945@item @emph{Arguments}: 14946@multitable @columnfractions .15 .70 14947@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 14948@item @var{SET} @tab Shall be of type @code{CHARACTER}. 14949@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 14950@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14951expression indicating the kind parameter of the result. 14952@end multitable 14953 14954@item @emph{Return value}: 14955The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14956@var{KIND} is absent, the return value is of default integer kind. 14957 14958@item @emph{Example}: 14959@smallexample 14960PROGRAM test_verify 14961 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F' 14962 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R' 14963 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F' 14964 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N' 14965 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none 14966END PROGRAM 14967@end smallexample 14968 14969@item @emph{See also}: 14970@ref{SCAN}, @gol 14971@ref{INDEX intrinsic} 14972@end table 14973 14974 14975 14976@node XOR 14977@section @code{XOR} --- Bitwise logical exclusive OR 14978@fnindex XOR 14979@cindex bitwise logical exclusive or 14980@cindex logical exclusive or, bitwise 14981 14982@table @asis 14983@item @emph{Description}: 14984Bitwise logical exclusive or. 14985 14986This intrinsic routine is provided for backwards compatibility with 14987GNU Fortran 77. For integer arguments, programmers should consider 14988the use of the @ref{IEOR} intrinsic and for logical arguments the 14989@code{.NEQV.} operator, which are both defined by the Fortran standard. 14990 14991@item @emph{Standard}: 14992GNU extension 14993 14994@item @emph{Class}: 14995Function 14996 14997@item @emph{Syntax}: 14998@code{RESULT = XOR(I, J)} 14999 15000@item @emph{Arguments}: 15001@multitable @columnfractions .15 .70 15002@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 15003type or a scalar @code{LOGICAL} type or a boz-literal-constant. 15004@item @var{J} @tab The type shall be the same as the type of @var{I} or 15005a boz-literal-constant. @var{I} and @var{J} shall not both be 15006boz-literal-constants. If either @var{I} and @var{J} is a 15007boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 15008@end multitable 15009 15010@item @emph{Return value}: 15011The return type is either a scalar @code{INTEGER} or a scalar 15012@code{LOGICAL}. If the kind type parameters differ, then the 15013smaller kind type is implicitly converted to larger kind, and the 15014return has the larger kind. A boz-literal-constant is 15015converted to an @code{INTEGER} with the kind type parameter of 15016the other argument as-if a call to @ref{INT} occurred. 15017 15018@item @emph{Example}: 15019@smallexample 15020PROGRAM test_xor 15021 LOGICAL :: T = .TRUE., F = .FALSE. 15022 INTEGER :: a, b 15023 DATA a / Z'F' /, b / Z'3' / 15024 15025 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F) 15026 WRITE (*,*) XOR(a, b) 15027END PROGRAM 15028@end smallexample 15029 15030@item @emph{See also}: 15031Fortran 95 elemental function: @gol 15032@ref{IEOR} 15033@end table 15034 15035 15036 15037@node Intrinsic Modules 15038@chapter Intrinsic Modules 15039@cindex intrinsic Modules 15040 15041@menu 15042* ISO_FORTRAN_ENV:: 15043* ISO_C_BINDING:: 15044* IEEE modules:: 15045* OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: 15046* OpenACC Module OPENACC:: 15047@end menu 15048 15049@node ISO_FORTRAN_ENV 15050@section @code{ISO_FORTRAN_ENV} 15051@table @asis 15052@item @emph{Standard}: 15053Fortran 2003 and later, except when otherwise noted 15054@end table 15055 15056The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer 15057named constants: 15058 15059@table @asis 15060@item @code{ATOMIC_INT_KIND}: 15061Default-kind integer constant to be used as kind parameter when defining 15062integer variables used in atomic operations. (Fortran 2008 or later.) 15063 15064@item @code{ATOMIC_LOGICAL_KIND}: 15065Default-kind integer constant to be used as kind parameter when defining 15066logical variables used in atomic operations. (Fortran 2008 or later.) 15067 15068@item @code{CHARACTER_KINDS}: 15069Default-kind integer constant array of rank one containing the supported kind 15070parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) 15071 15072@item @code{CHARACTER_STORAGE_SIZE}: 15073Size in bits of the character storage unit. 15074 15075@item @code{ERROR_UNIT}: 15076Identifies the preconnected unit used for error reporting. 15077 15078@item @code{FILE_STORAGE_SIZE}: 15079Size in bits of the file-storage unit. 15080 15081@item @code{INPUT_UNIT}: 15082Identifies the preconnected unit identified by the asterisk 15083(@code{*}) in @code{READ} statement. 15084 15085@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}: 15086Kind type parameters to specify an INTEGER type with a storage 15087size of 16, 32, and 64 bits. It is negative if a target platform 15088does not support the particular kind. (Fortran 2008 or later.) 15089 15090@item @code{INTEGER_KINDS}: 15091Default-kind integer constant array of rank one containing the supported kind 15092parameters of the @code{INTEGER} type. (Fortran 2008 or later.) 15093 15094@item @code{IOSTAT_END}: 15095The value assigned to the variable passed to the @code{IOSTAT=} specifier of 15096an input/output statement if an end-of-file condition occurred. 15097 15098@item @code{IOSTAT_EOR}: 15099The value assigned to the variable passed to the @code{IOSTAT=} specifier of 15100an input/output statement if an end-of-record condition occurred. 15101 15102@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}: 15103Scalar default-integer constant, used by @code{INQUIRE} for the 15104@code{IOSTAT=} specifier to denote an that a unit number identifies an 15105internal unit. (Fortran 2008 or later.) 15106 15107@item @code{NUMERIC_STORAGE_SIZE}: 15108The size in bits of the numeric storage unit. 15109 15110@item @code{LOGICAL_KINDS}: 15111Default-kind integer constant array of rank one containing the supported kind 15112parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) 15113 15114@item @code{OUTPUT_UNIT}: 15115Identifies the preconnected unit identified by the asterisk 15116(@code{*}) in @code{WRITE} statement. 15117 15118@item @code{REAL32}, @code{REAL64}, @code{REAL128}: 15119Kind type parameters to specify a REAL type with a storage 15120size of 32, 64, and 128 bits. It is negative if a target platform 15121does not support the particular kind. (Fortran 2008 or later.) 15122 15123@item @code{REAL_KINDS}: 15124Default-kind integer constant array of rank one containing the supported kind 15125parameters of the @code{REAL} type. (Fortran 2008 or later.) 15126 15127@item @code{STAT_LOCKED}: 15128Scalar default-integer constant used as STAT= return value by @code{LOCK} to 15129denote that the lock variable is locked by the executing image. (Fortran 2008 15130or later.) 15131 15132@item @code{STAT_LOCKED_OTHER_IMAGE}: 15133Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 15134denote that the lock variable is locked by another image. (Fortran 2008 or 15135later.) 15136 15137@item @code{STAT_STOPPED_IMAGE}: 15138Positive, scalar default-integer constant used as STAT= return value if the 15139argument in the statement requires synchronisation with an image, which has 15140initiated the termination of the execution. (Fortran 2008 or later.) 15141 15142@item @code{STAT_FAILED_IMAGE}: 15143Positive, scalar default-integer constant used as STAT= return value if the 15144argument in the statement requires communication with an image, which has 15145is in the failed state. (TS 18508 or later.) 15146 15147@item @code{STAT_UNLOCKED}: 15148Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 15149denote that the lock variable is unlocked. (Fortran 2008 or later.) 15150@end table 15151 15152The module provides the following derived type: 15153 15154@table @asis 15155@item @code{LOCK_TYPE}: 15156Derived type with private components to be use with the @code{LOCK} and 15157@code{UNLOCK} statement. A variable of its type has to be always declared 15158as coarray and may not appear in a variable-definition context. 15159(Fortran 2008 or later.) 15160@end table 15161 15162The module also provides the following intrinsic procedures: 15163@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}. 15164 15165 15166 15167@node ISO_C_BINDING 15168@section @code{ISO_C_BINDING} 15169@table @asis 15170@item @emph{Standard}: 15171Fortran 2003 and later, GNU extensions 15172@end table 15173 15174The following intrinsic procedures are provided by the module; their 15175definition can be found in the section Intrinsic Procedures of this 15176manual. 15177 15178@table @asis 15179@item @code{C_ASSOCIATED} 15180@item @code{C_F_POINTER} 15181@item @code{C_F_PROCPOINTER} 15182@item @code{C_FUNLOC} 15183@item @code{C_LOC} 15184@item @code{C_SIZEOF} 15185@end table 15186@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF, 15187@c don't really know why. 15188 15189The @code{ISO_C_BINDING} module provides the following named constants of 15190type default integer, which can be used as KIND type parameters. 15191 15192In addition to the integer named constants required by the Fortran 2003 15193standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an 15194extension named constants for the 128-bit integer types supported by the 15195C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}. 15196Furthermore, if @code{__float128} is supported in C, the named constants 15197@code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined. 15198 15199@multitable @columnfractions .15 .35 .35 .35 15200@item Fortran Type @tab Named constant @tab C type @tab Extension 15201@item @code{INTEGER}@tab @code{C_INT} @tab @code{int} 15202@item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int} 15203@item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int} 15204@item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int} 15205@item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char} 15206@item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t} 15207@item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t} 15208@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t} 15209@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t} 15210@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t} 15211@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext. 15212@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t} 15213@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t} 15214@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t} 15215@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t} 15216@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext. 15217@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t} 15218@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t} 15219@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t} 15220@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t} 15221@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext. 15222@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t} 15223@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t} 15224@item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113 15225@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float} 15226@item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double} 15227@item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double} 15228@item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext. 15229@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex} 15230@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex} 15231@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex} 15232@item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext. 15233@item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool} 15234@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char} 15235@end multitable 15236 15237Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)} 15238are defined. 15239 15240@multitable @columnfractions .20 .45 .15 15241@item Name @tab C definition @tab Value 15242@item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'} 15243@item @code{C_ALERT} @tab alert @tab @code{'\a'} 15244@item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'} 15245@item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'} 15246@item @code{C_NEW_LINE} @tab new line @tab @code{'\n'} 15247@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'} 15248@item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'} 15249@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'} 15250@end multitable 15251 15252Moreover, the following two named constants are defined: 15253 15254@multitable @columnfractions .20 .80 15255@item Name @tab Type 15256@item @code{C_NULL_PTR} @tab @code{C_PTR} 15257@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR} 15258@end multitable 15259 15260Both are equivalent to the value @code{NULL} in C. 15261 15262 15263 15264@node IEEE modules 15265@section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 15266@table @asis 15267@item @emph{Standard}: 15268Fortran 2003 and later 15269@end table 15270 15271The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 15272intrinsic modules provide support for exceptions and IEEE arithmetic, as 15273defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard 15274(@emph{Binary floating-point arithmetic for microprocessor systems}). These 15275modules are only provided on the following supported platforms: 15276 15277@itemize @bullet 15278@item i386 and x86_64 processors 15279@item platforms which use the GNU C Library (glibc) 15280@item platforms with support for SysV/386 routines for floating point 15281interface (including Solaris and BSDs) 15282@item platforms with the AIX OS 15283@end itemize 15284 15285For full compliance with the Fortran standards, code using the 15286@code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled 15287with the following options: @code{-fno-unsafe-math-optimizations 15288-frounding-math -fsignaling-nans}. 15289 15290 15291 15292@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS 15293@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS} 15294@table @asis 15295@item @emph{Standard}: 15296OpenMP Application Program Interface v4.5 and 15297OpenMP Application Program Interface v5.0 (partially supported). 15298@end table 15299 15300The OpenMP Fortran runtime library routines are provided both in 15301a form of two Fortran modules, named @code{OMP_LIB} and 15302@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named 15303@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found 15304in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi 15305Processing Runtime Library} manual, 15306the named constants defined in the modules are listed 15307below. 15308 15309For details refer to the actual 15310@uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf, 15311OpenMP Application Program Interface v4.5} and 15312@uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf, 15313OpenMP Application Program Interface v5.0}. 15314 15315@code{OMP_LIB_KINDS} provides the following scalar default-integer 15316named constants: 15317 15318@table @asis 15319@item @code{omp_allocator_handle_kind} 15320@item @code{omp_alloctrait_key_kind} 15321@item @code{omp_alloctrait_val_kind} 15322@item @code{omp_depend_kind} 15323@item @code{omp_lock_kind} 15324@item @code{omp_lock_hint_kind} 15325@item @code{omp_nest_lock_kind} 15326@item @code{omp_pause_resource_kind} 15327@item @code{omp_memspace_handle_kind} 15328@item @code{omp_proc_bind_kind} 15329@item @code{omp_sched_kind} 15330@item @code{omp_sync_hint_kind} 15331@end table 15332 15333@code{OMP_LIB} provides the scalar default-integer 15334named constant @code{openmp_version} with a value of the form 15335@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 15336of the OpenMP version; for OpenMP v4.5 the value is @code{201511}. 15337 15338The following derived type: 15339 15340@table @asis 15341@item @code{omp_alloctrait} 15342@end table 15343 15344The following scalar integer named constants of the 15345kind @code{omp_sched_kind}: 15346 15347@table @asis 15348@item @code{omp_sched_static} 15349@item @code{omp_sched_dynamic} 15350@item @code{omp_sched_guided} 15351@item @code{omp_sched_auto} 15352@end table 15353 15354And the following scalar integer named constants of the 15355kind @code{omp_proc_bind_kind}: 15356 15357@table @asis 15358@item @code{omp_proc_bind_false} 15359@item @code{omp_proc_bind_true} 15360@item @code{omp_proc_bind_master} 15361@item @code{omp_proc_bind_close} 15362@item @code{omp_proc_bind_spread} 15363@end table 15364 15365The following scalar integer named constants are of the 15366kind @code{omp_lock_hint_kind}: 15367 15368@table @asis 15369@item @code{omp_lock_hint_none} 15370@item @code{omp_lock_hint_uncontended} 15371@item @code{omp_lock_hint_contended} 15372@item @code{omp_lock_hint_nonspeculative} 15373@item @code{omp_lock_hint_speculative} 15374@item @code{omp_sync_hint_none} 15375@item @code{omp_sync_hint_uncontended} 15376@item @code{omp_sync_hint_contended} 15377@item @code{omp_sync_hint_nonspeculative} 15378@item @code{omp_sync_hint_speculative} 15379@end table 15380 15381And the following two scalar integer named constants are of the 15382kind @code{omp_pause_resource_kind}: 15383 15384@table @asis 15385@item @code{omp_pause_soft} 15386@item @code{omp_pause_hard} 15387@end table 15388 15389The following scalar integer named constants are of the kind 15390@code{omp_alloctrait_key_kind}: 15391 15392@table @asis 15393@item @code{omp_atk_sync_hint} 15394@item @code{omp_atk_alignment} 15395@item @code{omp_atk_access} 15396@item @code{omp_atk_pool_size} 15397@item @code{omp_atk_fallback} 15398@item @code{omp_atk_fb_data} 15399@item @code{omp_atk_pinned} 15400@item @code{omp_atk_partition} 15401@end table 15402 15403The following scalar integer named constants are of the kind 15404@code{omp_alloctrait_val_kind}: 15405 15406@table @asis 15407@code{omp_alloctrait_key_kind}: 15408@item @code{omp_atv_default} 15409@item @code{omp_atv_false} 15410@item @code{omp_atv_true} 15411@item @code{omp_atv_contended} 15412@item @code{omp_atv_uncontended} 15413@item @code{omp_atv_serialized} 15414@item @code{omp_atv_sequential} 15415@item @code{omp_atv_private} 15416@item @code{omp_atv_all} 15417@item @code{omp_atv_thread} 15418@item @code{omp_atv_pteam} 15419@item @code{omp_atv_cgroup} 15420@item @code{omp_atv_default_mem_fb} 15421@item @code{omp_atv_null_fb} 15422@item @code{omp_atv_abort_fb} 15423@item @code{omp_atv_allocator_fb} 15424@item @code{omp_atv_environment} 15425@item @code{omp_atv_nearest} 15426@item @code{omp_atv_blocked} 15427@end table 15428 15429The following scalar integer named constants are of the kind 15430@code{omp_allocator_handle_kind}: 15431 15432@table @asis 15433@item @code{omp_null_allocator} 15434@item @code{omp_default_mem_alloc} 15435@item @code{omp_large_cap_mem_alloc} 15436@item @code{omp_const_mem_alloc} 15437@item @code{omp_high_bw_mem_alloc} 15438@item @code{omp_low_lat_mem_alloc} 15439@item @code{omp_cgroup_mem_alloc} 15440@item @code{omp_pteam_mem_alloc} 15441@item @code{omp_thread_mem_alloc} 15442@end table 15443 15444The following scalar integer named constants are of the kind 15445@code{omp_memspace_handle_kind}: 15446 15447@table @asis 15448@item @code{omp_default_mem_space} 15449@item @code{omp_large_cap_mem_space} 15450@item @code{omp_const_mem_space} 15451@item @code{omp_high_bw_mem_space} 15452@item @code{omp_low_lat_mem_space} 15453@end table 15454 15455 15456 15457@node OpenACC Module OPENACC 15458@section OpenACC Module @code{OPENACC} 15459@table @asis 15460@item @emph{Standard}: 15461OpenACC Application Programming Interface v2.6 15462@end table 15463 15464 15465The OpenACC Fortran runtime library routines are provided both in a 15466form of a Fortran 90 module, named @code{OPENACC}, and in form of a 15467Fortran @code{include} file named @file{openacc_lib.h}. The 15468procedures provided by @code{OPENACC} can be found in the 15469@ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing 15470Runtime Library} manual, the named constants defined in the modules 15471are listed below. 15472 15473For details refer to the actual 15474@uref{http://www.openacc.org/, 15475OpenACC Application Programming Interface v2.6}. 15476 15477@code{OPENACC} provides the scalar default-integer 15478named constant @code{openacc_version} with a value of the form 15479@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 15480of the OpenACC version; for OpenACC v2.6 the value is @code{201711}. 15481