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{LSHIFT}: LSHIFT, Left shift bits 225* @code{LSTAT}: LSTAT, Get file status 226* @code{LTIME}: LTIME, Convert time to local time info 227* @code{MALLOC}: MALLOC, Dynamic memory allocation function 228* @code{MASKL}: MASKL, Left justified mask 229* @code{MASKR}: MASKR, Right justified mask 230* @code{MATMUL}: MATMUL, matrix multiplication 231* @code{MAX}: MAX, Maximum value of an argument list 232* @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind 233* @code{MAXLOC}: MAXLOC, Location of the maximum value within an array 234* @code{MAXVAL}: MAXVAL, Maximum value of an array 235* @code{MCLOCK}: MCLOCK, Time function 236* @code{MCLOCK8}: MCLOCK8, Time function (64-bit) 237* @code{MERGE}: MERGE, Merge arrays 238* @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask 239* @code{MIN}: MIN, Minimum value of an argument list 240* @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind 241* @code{MINLOC}: MINLOC, Location of the minimum value within an array 242* @code{MINVAL}: MINVAL, Minimum value of an array 243* @code{MOD}: MOD, Remainder function 244* @code{MODULO}: MODULO, Modulo function 245* @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another 246* @code{MVBITS}: MVBITS, Move bits from one integer to another 247* @code{NEAREST}: NEAREST, Nearest representable number 248* @code{NEW_LINE}: NEW_LINE, New line character 249* @code{NINT}: NINT, Nearest whole number 250* @code{NORM2}: NORM2, Euclidean vector norm 251* @code{NOT}: NOT, Logical negation 252* @code{NULL}: NULL, Function that returns an disassociated pointer 253* @code{NUM_IMAGES}: NUM_IMAGES, Number of images 254* @code{OR}: OR, Bitwise logical OR 255* @code{PACK}: PACK, Pack an array into an array of rank one 256* @code{PARITY}: PARITY, Reduction with exclusive OR 257* @code{PERROR}: PERROR, Print system error message 258* @code{POPCNT}: POPCNT, Number of bits set 259* @code{POPPAR}: POPPAR, Parity of the number of bits set 260* @code{PRECISION}: PRECISION, Decimal precision of a real kind 261* @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified 262* @code{PRODUCT}: PRODUCT, Product of array elements 263* @code{RADIX}: RADIX, Base of a data model 264* @code{RAN}: RAN, Real pseudo-random number 265* @code{RAND}: RAND, Real pseudo-random number 266* @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator 267* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number 268* @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence 269* @code{RANGE}: RANGE, Decimal exponent range 270* @code{RANK} : RANK, Rank of a data object 271* @code{REAL}: REAL, Convert to real type 272* @code{RENAME}: RENAME, Rename a file 273* @code{REPEAT}: REPEAT, Repeated string concatenation 274* @code{RESHAPE}: RESHAPE, Function to reshape an array 275* @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing 276* @code{RSHIFT}: RSHIFT, Right shift bits 277* @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality 278* @code{SCALE}: SCALE, Scale a real value 279* @code{SCAN}: SCAN, Scan a string for the presence of a set of characters 280* @code{SECNDS}: SECNDS, Time function 281* @code{SECOND}: SECOND, CPU time function 282* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind 283* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind 284* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind 285* @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model 286* @code{SHAPE}: SHAPE, Determine the shape of an array 287* @code{SHIFTA}: SHIFTA, Right shift with fill 288* @code{SHIFTL}: SHIFTL, Left shift 289* @code{SHIFTR}: SHIFTR, Right shift 290* @code{SIGN}: SIGN, Sign copying function 291* @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function) 292* @code{SIN}: SIN, Sine function 293* @code{SIND}: SIND, Sine function, degrees 294* @code{SINH}: SINH, Hyperbolic sine function 295* @code{SIZE}: SIZE, Function to determine the size of an array 296* @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression 297* @code{SLEEP}: SLEEP, Sleep for the specified number of seconds 298* @code{SPACING}: SPACING, Smallest distance between two numbers of a given type 299* @code{SPREAD}: SPREAD, Add a dimension to an array 300* @code{SQRT}: SQRT, Square-root function 301* @code{SRAND}: SRAND, Reinitialize the random number generator 302* @code{STAT}: STAT, Get file status 303* @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits 304* @code{SUM}: SUM, Sum of array elements 305* @code{SYMLNK}: SYMLNK, Create a symbolic link 306* @code{SYSTEM}: SYSTEM, Execute a shell command 307* @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function 308* @code{TAN}: TAN, Tangent function 309* @code{TAND}: TAND, Tangent function, degrees 310* @code{TANH}: TANH, Hyperbolic tangent function 311* @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image 312* @code{TIME}: TIME, Time function 313* @code{TIME8}: TIME8, Time function (64-bit) 314* @code{TINY}: TINY, Smallest positive number of a real kind 315* @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer 316* @code{TRANSFER}: TRANSFER, Transfer bit patterns 317* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two 318* @code{TRIM}: TRIM, Remove trailing blank characters of a string 319* @code{TTYNAM}: TTYNAM, Get the name of a terminal device. 320* @code{UBOUND}: UBOUND, Upper dimension bounds of an array 321* @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array 322* @code{UMASK}: UMASK, Set the file creation mask 323* @code{UNLINK}: UNLINK, Remove a file from the file system 324* @code{UNPACK}: UNPACK, Unpack an array of rank one into an array 325* @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters 326* @code{XOR}: XOR, Bitwise logical exclusive or 327@end menu 328 329@node Introduction to Intrinsics 330@section Introduction to intrinsic procedures 331 332The intrinsic procedures provided by GNU Fortran include procedures required 333by the Fortran 95 and later supported standards, and a set of intrinsic 334procedures for backwards compatibility with G77. Any conflict between 335a description here and a description in the Fortran standards is 336unintentional, and the standard(s) should be considered authoritative. 337 338The enumeration of the @code{KIND} type parameter is processor defined in 339the Fortran 95 standard. GNU Fortran defines the default integer type and 340default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)}, 341respectively. The standard mandates that both data types shall have 342another kind, which have more precision. On typical target architectures 343supported by @command{gfortran}, this kind type parameter is @code{KIND=8}. 344Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent. 345In the description of generic intrinsic procedures, the kind type parameter 346will be specified by @code{KIND=*}, and in the description of specific 347names for an intrinsic procedure the kind type parameter will be explicitly 348given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for 349brevity the optional @code{KIND=} syntax will be omitted. 350 351Many of the intrinsic procedures take one or more optional arguments. 352This document follows the convention used in the Fortran 95 standard, 353and denotes such arguments by square brackets. 354 355GNU Fortran offers the @option{-std=} command-line option, 356which can be used to restrict the set of intrinsic procedures to a 357given standard. By default, @command{gfortran} sets the @option{-std=gnu} 358option, and so all intrinsic procedures described here are accepted. There 359is one caveat. For a select group of intrinsic procedures, @command{g77} 360implemented both a function and a subroutine. Both classes 361have been implemented in @command{gfortran} for backwards compatibility 362with @command{g77}. It is noted here that these functions and subroutines 363cannot be intermixed in a given subprogram. In the descriptions that follow, 364the applicable standard for each intrinsic procedure is noted. 365 366 367 368@node ABORT 369@section @code{ABORT} --- Abort the program 370@fnindex ABORT 371@cindex program termination, with core dump 372@cindex terminate program, with core dump 373@cindex core, dump 374 375@table @asis 376@item @emph{Description}: 377@code{ABORT} causes immediate termination of the program. On operating 378systems that support a core dump, @code{ABORT} will produce a core dump. 379It will also print a backtrace, unless @code{-fno-backtrace} is given. 380 381@item @emph{Standard}: 382GNU extension 383 384@item @emph{Class}: 385Subroutine 386 387@item @emph{Syntax}: 388@code{CALL ABORT} 389 390@item @emph{Return value}: 391Does not return. 392 393@item @emph{Example}: 394@smallexample 395program test_abort 396 integer :: i = 1, j = 2 397 if (i /= j) call abort 398end program test_abort 399@end smallexample 400 401@item @emph{See also}: 402@ref{EXIT}, @gol 403@ref{KILL}, @gol 404@ref{BACKTRACE} 405@end table 406 407 408 409@node ABS 410@section @code{ABS} --- Absolute value 411@fnindex ABS 412@fnindex CABS 413@fnindex DABS 414@fnindex IABS 415@fnindex ZABS 416@fnindex CDABS 417@fnindex BABS 418@fnindex IIABS 419@fnindex JIABS 420@fnindex KIABS 421@cindex absolute value 422 423@table @asis 424@item @emph{Description}: 425@code{ABS(A)} computes the absolute value of @code{A}. 426 427@item @emph{Standard}: 428Fortran 77 and later, has overloads that are GNU extensions 429 430@item @emph{Class}: 431Elemental function 432 433@item @emph{Syntax}: 434@code{RESULT = ABS(A)} 435 436@item @emph{Arguments}: 437@multitable @columnfractions .15 .70 438@item @var{A} @tab The type of the argument shall be an @code{INTEGER}, 439@code{REAL}, or @code{COMPLEX}. 440@end multitable 441 442@item @emph{Return value}: 443The return value is of the same type and 444kind as the argument except the return value is @code{REAL} for a 445@code{COMPLEX} argument. 446 447@item @emph{Example}: 448@smallexample 449program test_abs 450 integer :: i = -1 451 real :: x = -1.e0 452 complex :: z = (-1.e0,0.e0) 453 i = abs(i) 454 x = abs(x) 455 x = abs(z) 456end program test_abs 457@end smallexample 458 459@item @emph{Specific names}: 460@multitable @columnfractions .20 .23 .20 .33 461@headitem Name @tab Argument @tab Return type @tab Standard 462@item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 463@item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 464@item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 465@item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later 466@item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 467@item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 468@item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 469@item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 470@item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension 471@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension 472@end multitable 473@end table 474 475 476 477@node ACCESS 478@section @code{ACCESS} --- Checks file access modes 479@fnindex ACCESS 480@cindex file system, access mode 481 482@table @asis 483@item @emph{Description}: 484@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 485exists, is readable, writable or executable. Except for the 486executable check, @code{ACCESS} can be replaced by 487Fortran 95's @code{INQUIRE}. 488 489@item @emph{Standard}: 490GNU extension 491 492@item @emph{Class}: 493Inquiry function 494 495@item @emph{Syntax}: 496@code{RESULT = ACCESS(NAME, MODE)} 497 498@item @emph{Arguments}: 499@multitable @columnfractions .15 .70 500@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 501file name. Trailing blank are ignored unless the character @code{achar(0)} 502is present, then all characters up to and excluding @code{achar(0)} are 503used as file name. 504@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the 505file access mode, may be any concatenation of @code{"r"} (readable), 506@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check 507for existence. 508@end multitable 509 510@item @emph{Return value}: 511Returns a scalar @code{INTEGER}, which is @code{0} if the file is 512accessible in the given mode; otherwise or if an invalid argument 513has been given for @code{MODE} the value @code{1} is returned. 514 515@item @emph{Example}: 516@smallexample 517program access_test 518 implicit none 519 character(len=*), parameter :: file = 'test.dat' 520 character(len=*), parameter :: file2 = 'test.dat '//achar(0) 521 if(access(file,' ') == 0) print *, trim(file),' is exists' 522 if(access(file,'r') == 0) print *, trim(file),' is readable' 523 if(access(file,'w') == 0) print *, trim(file),' is writable' 524 if(access(file,'x') == 0) print *, trim(file),' is executable' 525 if(access(file2,'rwx') == 0) & 526 print *, trim(file2),' is readable, writable and executable' 527end program access_test 528@end smallexample 529@end table 530 531 532 533@node ACHAR 534@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 535@fnindex ACHAR 536@cindex @acronym{ASCII} collating sequence 537@cindex collating sequence, @acronym{ASCII} 538 539@table @asis 540@item @emph{Description}: 541@code{ACHAR(I)} returns the character located at position @code{I} 542in the @acronym{ASCII} collating sequence. 543 544@item @emph{Standard}: 545Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 546 547@item @emph{Class}: 548Elemental function 549 550@item @emph{Syntax}: 551@code{RESULT = ACHAR(I [, KIND])} 552 553@item @emph{Arguments}: 554@multitable @columnfractions .15 .70 555@item @var{I} @tab The type shall be @code{INTEGER}. 556@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 557expression indicating the kind parameter of the result. 558@end multitable 559 560@item @emph{Return value}: 561The return value is of type @code{CHARACTER} with a length of one. 562If the @var{KIND} argument is present, the return value is of the 563specified kind and of the default kind otherwise. 564 565@item @emph{Example}: 566@smallexample 567program test_achar 568 character c 569 c = achar(32) 570end program test_achar 571@end smallexample 572 573@item @emph{Note}: 574See @ref{ICHAR} for a discussion of converting between numerical values 575and formatted string representations. 576 577@item @emph{See also}: 578@ref{CHAR}, @gol 579@ref{IACHAR}, @gol 580@ref{ICHAR} 581@end table 582 583 584 585@node ACOS 586@section @code{ACOS} --- Arccosine function 587@fnindex ACOS 588@fnindex DACOS 589@cindex trigonometric function, cosine, inverse 590@cindex cosine, inverse 591 592@table @asis 593@item @emph{Description}: 594@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}). 595 596@item @emph{Standard}: 597Fortran 77 and later, for a complex argument Fortran 2008 or later 598 599@item @emph{Class}: 600Elemental function 601 602@item @emph{Syntax}: 603@code{RESULT = ACOS(X)} 604 605@item @emph{Arguments}: 606@multitable @columnfractions .15 .70 607@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 608less than or equal to one - or the type shall be @code{COMPLEX}. 609@end multitable 610 611@item @emph{Return value}: 612The return value is of the same type and kind as @var{X}. 613The real part of the result is in radians and lies in the range 614@math{0 \leq \Re \acos(x) \leq \pi}. 615 616@item @emph{Example}: 617@smallexample 618program test_acos 619 real(8) :: x = 0.866_8 620 x = acos(x) 621end program test_acos 622@end smallexample 623 624@item @emph{Specific names}: 625@multitable @columnfractions .20 .23 .20 .33 626@headitem Name @tab Argument @tab Return type @tab Standard 627@item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 628@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 629@end multitable 630 631@item @emph{See also}: 632Inverse function: @gol 633@ref{COS} @gol 634Degrees function: @gol 635@ref{ACOSD} 636@end table 637 638 639 640@node ACOSD 641@section @code{ACOSD} --- Arccosine function, degrees 642@fnindex ACOSD 643@fnindex DACOSD 644@cindex trigonometric function, cosine, inverse, degrees 645@cindex cosine, inverse, degrees 646 647@table @asis 648@item @emph{Description}: 649@code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of 650@code{COSD(X)}). 651 652This function is for compatibility only and should be avoided in favor of 653standard constructs wherever possible. 654 655@item @emph{Standard}: 656GNU extension, enabled with @option{-fdec-math} 657 658@item @emph{Class}: 659Elemental function 660 661@item @emph{Syntax}: 662@code{RESULT = ACOSD(X)} 663 664@item @emph{Arguments}: 665@multitable @columnfractions .15 .70 666@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 667less than or equal to one - or the type shall be @code{COMPLEX}. 668@end multitable 669 670@item @emph{Return value}: 671The return value is of the same type and kind as @var{X}. 672The real part of the result is in degrees and lies in the range 673@math{0 \leq \Re \acos(x) \leq 180}. 674 675@item @emph{Example}: 676@smallexample 677program test_acosd 678 real(8) :: x = 0.866_8 679 x = acosd(x) 680end program test_acosd 681@end smallexample 682 683@item @emph{Specific names}: 684@multitable @columnfractions .20 .23 .20 .33 685@headitem Name @tab Argument @tab Return type @tab Standard 686@item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 687@item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 688@end multitable 689 690@item @emph{See also}: 691Inverse function: @gol 692@ref{COSD} @gol 693Radians function: @gol 694@ref{ACOS} @gol 695@end table 696 697 698 699@node ACOSH 700@section @code{ACOSH} --- Inverse hyperbolic cosine function 701@fnindex ACOSH 702@fnindex DACOSH 703@cindex area hyperbolic cosine 704@cindex inverse hyperbolic cosine 705@cindex hyperbolic function, cosine, inverse 706@cindex cosine, hyperbolic, inverse 707 708@table @asis 709@item @emph{Description}: 710@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}. 711 712@item @emph{Standard}: 713Fortran 2008 and later 714 715@item @emph{Class}: 716Elemental function 717 718@item @emph{Syntax}: 719@code{RESULT = ACOSH(X)} 720 721@item @emph{Arguments}: 722@multitable @columnfractions .15 .70 723@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 724@end multitable 725 726@item @emph{Return value}: 727The return value has the same type and kind as @var{X}. If @var{X} is 728complex, the imaginary part of the result is in radians and lies between 729@math{ 0 \leq \Im \acosh(x) \leq \pi}. 730 731@item @emph{Example}: 732@smallexample 733PROGRAM test_acosh 734 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) 735 WRITE (*,*) ACOSH(x) 736END PROGRAM 737@end smallexample 738 739@item @emph{Specific names}: 740@multitable @columnfractions .20 .23 .20 .33 741@headitem Name @tab Argument @tab Return type @tab Standard 742@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 743@end multitable 744 745@item @emph{See also}: 746Inverse function: @gol 747@ref{COSH} 748@end table 749 750 751 752@node ADJUSTL 753@section @code{ADJUSTL} --- Left adjust a string 754@fnindex ADJUSTL 755@cindex string, adjust left 756@cindex adjust string 757 758@table @asis 759@item @emph{Description}: 760@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces. 761Spaces are inserted at the end of the string as needed. 762 763@item @emph{Standard}: 764Fortran 90 and later 765 766@item @emph{Class}: 767Elemental function 768 769@item @emph{Syntax}: 770@code{RESULT = ADJUSTL(STRING)} 771 772@item @emph{Arguments}: 773@multitable @columnfractions .15 .70 774@item @var{STRING} @tab The type shall be @code{CHARACTER}. 775@end multitable 776 777@item @emph{Return value}: 778The return value is of type @code{CHARACTER} and of the same kind as 779@var{STRING} where leading spaces are removed and the same number of 780spaces are inserted on the end of @var{STRING}. 781 782@item @emph{Example}: 783@smallexample 784program test_adjustl 785 character(len=20) :: str = ' gfortran' 786 str = adjustl(str) 787 print *, str 788end program test_adjustl 789@end smallexample 790 791@item @emph{See also}: 792@ref{ADJUSTR}, @gol 793@ref{TRIM} 794@end table 795 796 797 798@node ADJUSTR 799@section @code{ADJUSTR} --- Right adjust a string 800@fnindex ADJUSTR 801@cindex string, adjust right 802@cindex adjust string 803 804@table @asis 805@item @emph{Description}: 806@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces. 807Spaces are inserted at the start of the string as needed. 808 809@item @emph{Standard}: 810Fortran 90 and later 811 812@item @emph{Class}: 813Elemental function 814 815@item @emph{Syntax}: 816@code{RESULT = ADJUSTR(STRING)} 817 818@item @emph{Arguments}: 819@multitable @columnfractions .15 .70 820@item @var{STR} @tab The type shall be @code{CHARACTER}. 821@end multitable 822 823@item @emph{Return value}: 824The return value is of type @code{CHARACTER} and of the same kind as 825@var{STRING} where trailing spaces are removed and the same number of 826spaces are inserted at the start of @var{STRING}. 827 828@item @emph{Example}: 829@smallexample 830program test_adjustr 831 character(len=20) :: str = 'gfortran' 832 str = adjustr(str) 833 print *, str 834end program test_adjustr 835@end smallexample 836 837@item @emph{See also}: 838@ref{ADJUSTL}, @gol 839@ref{TRIM} 840@end table 841 842 843 844@node AIMAG 845@section @code{AIMAG} --- Imaginary part of complex number 846@fnindex AIMAG 847@fnindex DIMAG 848@fnindex IMAG 849@fnindex IMAGPART 850@cindex complex numbers, imaginary part 851 852@table @asis 853@item @emph{Description}: 854@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}. 855The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided 856for compatibility with @command{g77}, and their use in new code is 857strongly discouraged. 858 859@item @emph{Standard}: 860Fortran 77 and later, has overloads that are GNU extensions 861 862@item @emph{Class}: 863Elemental function 864 865@item @emph{Syntax}: 866@code{RESULT = AIMAG(Z)} 867 868@item @emph{Arguments}: 869@multitable @columnfractions .15 .70 870@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}. 871@end multitable 872 873@item @emph{Return value}: 874The return value is of type @code{REAL} with the 875kind type parameter of the argument. 876 877@item @emph{Example}: 878@smallexample 879program test_aimag 880 complex(4) z4 881 complex(8) z8 882 z4 = cmplx(1.e0_4, 0.e0_4) 883 z8 = cmplx(0.e0_8, 1.e0_8) 884 print *, aimag(z4), dimag(z8) 885end program test_aimag 886@end smallexample 887 888@item @emph{Specific names}: 889@multitable @columnfractions .20 .23 .20 .33 890@headitem Name @tab Argument @tab Return type @tab Standard 891@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later 892@item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension 893@item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 894@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 895@end multitable 896@end table 897 898 899 900@node AINT 901@section @code{AINT} --- Truncate to a whole number 902@fnindex AINT 903@fnindex DINT 904@cindex floor 905@cindex rounding, floor 906 907@table @asis 908@item @emph{Description}: 909@code{AINT(A [, KIND])} truncates its argument to a whole number. 910 911@item @emph{Standard}: 912Fortran 77 and later 913 914@item @emph{Class}: 915Elemental function 916 917@item @emph{Syntax}: 918@code{RESULT = AINT(A [, KIND])} 919 920@item @emph{Arguments}: 921@multitable @columnfractions .15 .70 922@item @var{A} @tab The type of the argument shall be @code{REAL}. 923@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 924expression indicating the kind parameter of the result. 925@end multitable 926 927@item @emph{Return value}: 928The return value is of type @code{REAL} with the kind type parameter of the 929argument if the optional @var{KIND} is absent; otherwise, the kind 930type parameter will be given by @var{KIND}. If the magnitude of 931@var{X} is less than one, @code{AINT(X)} returns zero. If the 932magnitude is equal to or greater than one then it returns the largest 933whole number that does not exceed its magnitude. The sign is the same 934as the sign of @var{X}. 935 936@item @emph{Example}: 937@smallexample 938program test_aint 939 real(4) x4 940 real(8) x8 941 x4 = 1.234E0_4 942 x8 = 4.321_8 943 print *, aint(x4), dint(x8) 944 x8 = aint(x4,8) 945end program test_aint 946@end smallexample 947 948@item @emph{Specific names}: 949@multitable @columnfractions .20 .23 .20 .33 950@headitem Name @tab Argument @tab Return type @tab Standard 951@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 952@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 953@end multitable 954@end table 955 956 957 958@node ALARM 959@section @code{ALARM} --- Execute a routine after a given delay 960@fnindex ALARM 961@cindex delayed execution 962 963@table @asis 964@item @emph{Description}: 965@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} 966to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to 967set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is 968supplied, it will be returned with the number of seconds remaining until 969any previously scheduled alarm was due to be delivered, or zero if there 970was no previously scheduled alarm. 971 972@item @emph{Standard}: 973GNU extension 974 975@item @emph{Class}: 976Subroutine 977 978@item @emph{Syntax}: 979@code{CALL ALARM(SECONDS, HANDLER [, STATUS])} 980 981@item @emph{Arguments}: 982@multitable @columnfractions .15 .70 983@item @var{SECONDS} @tab The type of the argument shall be a scalar 984@code{INTEGER}. It is @code{INTENT(IN)}. 985@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or 986@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 987values may be either @code{SIG_IGN=1} to ignore the alarm generated 988or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}. 989@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 990variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}. 991@end multitable 992 993@item @emph{Example}: 994@smallexample 995program test_alarm 996 external handler_print 997 integer i 998 call alarm (3, handler_print, i) 999 print *, i 1000 call sleep(10) 1001end program test_alarm 1002@end smallexample 1003This will cause the external routine @var{handler_print} to be called 1004after 3 seconds. 1005@end table 1006 1007 1008 1009@node ALL 1010@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 1011@fnindex ALL 1012@cindex array, apply condition 1013@cindex array, condition testing 1014 1015@table @asis 1016@item @emph{Description}: 1017@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK} 1018in the array along dimension @var{DIM}. 1019 1020@item @emph{Standard}: 1021Fortran 90 and later 1022 1023@item @emph{Class}: 1024Transformational function 1025 1026@item @emph{Syntax}: 1027@code{RESULT = ALL(MASK [, DIM])} 1028 1029@item @emph{Arguments}: 1030@multitable @columnfractions .15 .70 1031@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1032it shall not be scalar. 1033@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1034with a value that lies between one and the rank of @var{MASK}. 1035@end multitable 1036 1037@item @emph{Return value}: 1038@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where 1039the kind type parameter is the same as the kind type parameter of 1040@var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns 1041an array with the rank of @var{MASK} minus 1. The shape is determined from 1042the shape of @var{MASK} where the @var{DIM} dimension is elided. 1043 1044@table @asis 1045@item (A) 1046@code{ALL(MASK)} is true if all elements of @var{MASK} are true. 1047It also is true if @var{MASK} has zero size; otherwise, it is false. 1048@item (B) 1049If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent 1050to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)} 1051is determined by applying @code{ALL} to the array sections. 1052@end table 1053 1054@item @emph{Example}: 1055@smallexample 1056program test_all 1057 logical l 1058 l = all((/.true., .true., .true./)) 1059 print *, l 1060 call section 1061 contains 1062 subroutine section 1063 integer a(2,3), b(2,3) 1064 a = 1 1065 b = 1 1066 b(2,2) = 2 1067 print *, all(a .eq. b, 1) 1068 print *, all(a .eq. b, 2) 1069 end subroutine section 1070end program test_all 1071@end smallexample 1072@end table 1073 1074 1075 1076@node ALLOCATED 1077@section @code{ALLOCATED} --- Status of an allocatable entity 1078@fnindex ALLOCATED 1079@cindex allocation, status 1080 1081@table @asis 1082@item @emph{Description}: 1083@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation 1084status of @var{ARRAY} and @var{SCALAR}, respectively. 1085 1086@item @emph{Standard}: 1087Fortran 90 and later. Note, the @code{SCALAR=} keyword and allocatable 1088scalar entities are available in Fortran 2003 and later. 1089 1090@item @emph{Class}: 1091Inquiry function 1092 1093@item @emph{Syntax}: 1094@multitable @columnfractions .80 1095@item @code{RESULT = ALLOCATED(ARRAY)} 1096@item @code{RESULT = ALLOCATED(SCALAR)} 1097@end multitable 1098 1099@item @emph{Arguments}: 1100@multitable @columnfractions .15 .70 1101@item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array. 1102@item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar. 1103@end multitable 1104 1105@item @emph{Return value}: 1106The return value is a scalar @code{LOGICAL} with the default logical 1107kind type parameter. If the argument is allocated, then the result is 1108@code{.TRUE.}; otherwise, it returns @code{.FALSE.} 1109 1110@item @emph{Example}: 1111@smallexample 1112program test_allocated 1113 integer :: i = 4 1114 real(4), allocatable :: x(:) 1115 if (.not. allocated(x)) allocate(x(i)) 1116end program test_allocated 1117@end smallexample 1118@end table 1119 1120 1121 1122@node AND 1123@section @code{AND} --- Bitwise logical AND 1124@fnindex AND 1125@cindex bitwise logical and 1126@cindex logical and, bitwise 1127 1128@table @asis 1129@item @emph{Description}: 1130Bitwise logical @code{AND}. 1131 1132This intrinsic routine is provided for backwards compatibility with 1133GNU Fortran 77. For integer arguments, programmers should consider 1134the use of the @ref{IAND} intrinsic defined by the Fortran standard. 1135 1136@item @emph{Standard}: 1137GNU extension 1138 1139@item @emph{Class}: 1140Function 1141 1142@item @emph{Syntax}: 1143@code{RESULT = AND(I, J)} 1144 1145@item @emph{Arguments}: 1146@multitable @columnfractions .15 .70 1147@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 1148type or a scalar @code{LOGICAL} type or a boz-literal-constant. 1149@item @var{J} @tab The type shall be the same as the type of @var{I} or 1150a boz-literal-constant. @var{I} and @var{J} shall not both be 1151boz-literal-constants. If either @var{I} or @var{J} is a 1152boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 1153@end multitable 1154 1155@item @emph{Return value}: 1156The return type is either a scalar @code{INTEGER} or a scalar 1157@code{LOGICAL}. If the kind type parameters differ, then the 1158smaller kind type is implicitly converted to larger kind, and the 1159return has the larger kind. A boz-literal-constant is 1160converted to an @code{INTEGER} with the kind type parameter of 1161the other argument as-if a call to @ref{INT} occurred. 1162 1163@item @emph{Example}: 1164@smallexample 1165PROGRAM test_and 1166 LOGICAL :: T = .TRUE., F = .FALSE. 1167 INTEGER :: a, b 1168 DATA a / Z'F' /, b / Z'3' / 1169 1170 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F) 1171 WRITE (*,*) AND(a, b) 1172END PROGRAM 1173@end smallexample 1174 1175@item @emph{See also}: 1176Fortran 95 elemental function: @gol 1177@ref{IAND} 1178@end table 1179 1180 1181 1182@node ANINT 1183@section @code{ANINT} --- Nearest whole number 1184@fnindex ANINT 1185@fnindex DNINT 1186@cindex ceiling 1187@cindex rounding, ceiling 1188 1189@table @asis 1190@item @emph{Description}: 1191@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number. 1192 1193@item @emph{Standard}: 1194Fortran 77 and later 1195 1196@item @emph{Class}: 1197Elemental function 1198 1199@item @emph{Syntax}: 1200@code{RESULT = ANINT(A [, KIND])} 1201 1202@item @emph{Arguments}: 1203@multitable @columnfractions .15 .70 1204@item @var{A} @tab The type of the argument shall be @code{REAL}. 1205@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 1206expression indicating the kind parameter of the result. 1207@end multitable 1208 1209@item @emph{Return value}: 1210The return value is of type real with the kind type parameter of the 1211argument if the optional @var{KIND} is absent; otherwise, the kind 1212type parameter will be given by @var{KIND}. If @var{A} is greater than 1213zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is 1214less than or equal to zero then it returns @code{AINT(X-0.5)}. 1215 1216@item @emph{Example}: 1217@smallexample 1218program test_anint 1219 real(4) x4 1220 real(8) x8 1221 x4 = 1.234E0_4 1222 x8 = 4.321_8 1223 print *, anint(x4), dnint(x8) 1224 x8 = anint(x4,8) 1225end program test_anint 1226@end smallexample 1227 1228@item @emph{Specific names}: 1229@multitable @columnfractions .20 .23 .20 .33 1230@headitem Name @tab Argument @tab Return type @tab Standard 1231@item @code{ANINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 1232@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 1233@end multitable 1234@end table 1235 1236 1237 1238@node ANY 1239@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 1240@fnindex ANY 1241@cindex array, apply condition 1242@cindex array, condition testing 1243 1244@table @asis 1245@item @emph{Description}: 1246@code{ANY(MASK [, DIM])} determines if any of the values in the logical array 1247@var{MASK} along dimension @var{DIM} are @code{.TRUE.}. 1248 1249@item @emph{Standard}: 1250Fortran 90 and later 1251 1252@item @emph{Class}: 1253Transformational function 1254 1255@item @emph{Syntax}: 1256@code{RESULT = ANY(MASK [, DIM])} 1257 1258@item @emph{Arguments}: 1259@multitable @columnfractions .15 .70 1260@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1261it shall not be scalar. 1262@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1263with a value that lies between one and the rank of @var{MASK}. 1264@end multitable 1265 1266@item @emph{Return value}: 1267@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where 1268the kind type parameter is the same as the kind type parameter of 1269@var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns 1270an array with the rank of @var{MASK} minus 1. The shape is determined from 1271the shape of @var{MASK} where the @var{DIM} dimension is elided. 1272 1273@table @asis 1274@item (A) 1275@code{ANY(MASK)} is true if any element of @var{MASK} is true; 1276otherwise, it is false. It also is false if @var{MASK} has zero size. 1277@item (B) 1278If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent 1279to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)} 1280is determined by applying @code{ANY} to the array sections. 1281@end table 1282 1283@item @emph{Example}: 1284@smallexample 1285program test_any 1286 logical l 1287 l = any((/.true., .true., .true./)) 1288 print *, l 1289 call section 1290 contains 1291 subroutine section 1292 integer a(2,3), b(2,3) 1293 a = 1 1294 b = 1 1295 b(2,2) = 2 1296 print *, any(a .eq. b, 1) 1297 print *, any(a .eq. b, 2) 1298 end subroutine section 1299end program test_any 1300@end smallexample 1301@end table 1302 1303 1304 1305@node ASIN 1306@section @code{ASIN} --- Arcsine function 1307@fnindex ASIN 1308@fnindex DASIN 1309@cindex trigonometric function, sine, inverse 1310@cindex sine, inverse 1311 1312@table @asis 1313@item @emph{Description}: 1314@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}). 1315 1316@item @emph{Standard}: 1317Fortran 77 and later, for a complex argument Fortran 2008 or later 1318 1319@item @emph{Class}: 1320Elemental function 1321 1322@item @emph{Syntax}: 1323@code{RESULT = ASIN(X)} 1324 1325@item @emph{Arguments}: 1326@multitable @columnfractions .15 .70 1327@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1328less than or equal to one - or be @code{COMPLEX}. 1329@end multitable 1330 1331@item @emph{Return value}: 1332The return value is of the same type and kind as @var{X}. 1333The real part of the result is in radians and lies in the range 1334@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}. 1335 1336@item @emph{Example}: 1337@smallexample 1338program test_asin 1339 real(8) :: x = 0.866_8 1340 x = asin(x) 1341end program test_asin 1342@end smallexample 1343 1344@item @emph{Specific names}: 1345@multitable @columnfractions .20 .23 .20 .33 1346@headitem Name @tab Argument @tab Return type @tab Standard 1347@item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1348@item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1349@end multitable 1350 1351@item @emph{See also}: 1352Inverse function: @gol 1353@ref{SIN} @gol 1354Degrees function: @gol 1355@ref{ASIND} 1356@end table 1357 1358 1359 1360@node ASIND 1361@section @code{ASIND} --- Arcsine function, degrees 1362@fnindex ASIND 1363@fnindex DASIND 1364@cindex trigonometric function, sine, inverse, degrees 1365@cindex sine, inverse, degrees 1366 1367@table @asis 1368@item @emph{Description}: 1369@code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of 1370@code{SIND(X)}). 1371 1372This function is for compatibility only and should be avoided in favor of 1373standard constructs wherever possible. 1374 1375@item @emph{Standard}: 1376GNU extension, enabled with @option{-fdec-math}. 1377 1378@item @emph{Class}: 1379Elemental function 1380 1381@item @emph{Syntax}: 1382@code{RESULT = ASIND(X)} 1383 1384@item @emph{Arguments}: 1385@multitable @columnfractions .15 .70 1386@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1387less than or equal to one - or be @code{COMPLEX}. 1388@end multitable 1389 1390@item @emph{Return value}: 1391The return value is of the same type and kind as @var{X}. 1392The real part of the result is in degrees and lies in the range 1393@math{-90 \leq \Re \asin(x) \leq 90}. 1394 1395@item @emph{Example}: 1396@smallexample 1397program test_asind 1398 real(8) :: x = 0.866_8 1399 x = asind(x) 1400end program test_asind 1401@end smallexample 1402 1403@item @emph{Specific names}: 1404@multitable @columnfractions .20 .23 .20 .33 1405@headitem Name @tab Argument @tab Return type @tab Standard 1406@item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 1407@item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1408@end multitable 1409 1410@item @emph{See also}: 1411Inverse function: @gol 1412@ref{SIND} @gol 1413Radians function: @gol 1414@ref{ASIN} 1415@end table 1416 1417 1418 1419@node ASINH 1420@section @code{ASINH} --- Inverse hyperbolic sine function 1421@fnindex ASINH 1422@fnindex DASINH 1423@cindex area hyperbolic sine 1424@cindex inverse hyperbolic sine 1425@cindex hyperbolic function, sine, inverse 1426@cindex sine, hyperbolic, inverse 1427 1428@table @asis 1429@item @emph{Description}: 1430@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}. 1431 1432@item @emph{Standard}: 1433Fortran 2008 and later 1434 1435@item @emph{Class}: 1436Elemental function 1437 1438@item @emph{Syntax}: 1439@code{RESULT = ASINH(X)} 1440 1441@item @emph{Arguments}: 1442@multitable @columnfractions .15 .70 1443@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1444@end multitable 1445 1446@item @emph{Return value}: 1447The return value is of the same type and kind as @var{X}. If @var{X} is 1448complex, the imaginary part of the result is in radians and lies between 1449@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}. 1450 1451@item @emph{Example}: 1452@smallexample 1453PROGRAM test_asinh 1454 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1455 WRITE (*,*) ASINH(x) 1456END PROGRAM 1457@end smallexample 1458 1459@item @emph{Specific names}: 1460@multitable @columnfractions .20 .23 .20 .33 1461@headitem Name @tab Argument @tab Return type @tab Standard 1462@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension. 1463@end multitable 1464 1465@item @emph{See also}: 1466Inverse function: @gol 1467@ref{SINH} 1468@end table 1469 1470 1471 1472@node ASSOCIATED 1473@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 1474@fnindex ASSOCIATED 1475@cindex pointer, status 1476@cindex association status 1477 1478@table @asis 1479@item @emph{Description}: 1480@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer 1481@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}. 1482 1483@item @emph{Standard}: 1484Fortran 90 and later 1485 1486@item @emph{Class}: 1487Inquiry function 1488 1489@item @emph{Syntax}: 1490@code{RESULT = ASSOCIATED(POINTER [, TARGET])} 1491 1492@item @emph{Arguments}: 1493@multitable @columnfractions .15 .70 1494@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute 1495and it can be of any type. 1496@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or 1497a target. It must have the same type, kind type parameter, and 1498array rank as @var{POINTER}. 1499@end multitable 1500The association status of neither @var{POINTER} nor @var{TARGET} shall be 1501undefined. 1502 1503@item @emph{Return value}: 1504@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}. 1505There are several cases: 1506@table @asis 1507@item (A) When the optional @var{TARGET} is not present then 1508@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false. 1509@item (B) If @var{TARGET} is present and a scalar target, the result is true if 1510@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 1511disassociated, the result is false. 1512@item (C) If @var{TARGET} is present and an array target, the result is true if 1513@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays, 1514are arrays whose elements are not zero-sized storage sequences, and 1515@var{TARGET} and @var{POINTER} occupy the same storage units in array element 1516order. 1517As in case(B), the result is false, if @var{POINTER} is disassociated. 1518@item (D) If @var{TARGET} is present and an scalar pointer, the result is true 1519if @var{TARGET} is associated with @var{POINTER}, the target associated with 1520@var{TARGET} are not zero-sized storage sequences and occupy the same storage 1521units. 1522The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1523@item (E) If @var{TARGET} is present and an array pointer, the result is true if 1524target associated with @var{POINTER} and the target associated with @var{TARGET} 1525have the same shape, are not zero-sized arrays, are arrays whose elements are 1526not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy 1527the same storage units in array element order. 1528The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1529@end table 1530 1531@item @emph{Example}: 1532@smallexample 1533program test_associated 1534 implicit none 1535 real, target :: tgt(2) = (/1., 2./) 1536 real, pointer :: ptr(:) 1537 ptr => tgt 1538 if (associated(ptr) .eqv. .false.) call abort 1539 if (associated(ptr,tgt) .eqv. .false.) call abort 1540end program test_associated 1541@end smallexample 1542 1543@item @emph{See also}: 1544@ref{NULL} 1545@end table 1546 1547 1548 1549@node ATAN 1550@section @code{ATAN} --- Arctangent function 1551@fnindex ATAN 1552@fnindex DATAN 1553@cindex trigonometric function, tangent, inverse 1554@cindex tangent, inverse 1555 1556@table @asis 1557@item @emph{Description}: 1558@code{ATAN(X)} computes the arctangent of @var{X}. 1559 1560@item @emph{Standard}: 1561Fortran 77 and later, for a complex argument and for two arguments 1562Fortran 2008 or later 1563 1564@item @emph{Class}: 1565Elemental function 1566 1567@item @emph{Syntax}: 1568@multitable @columnfractions .80 1569@item @code{RESULT = ATAN(X)} 1570@item @code{RESULT = ATAN(Y, X)} 1571@end multitable 1572 1573@item @emph{Arguments}: 1574@multitable @columnfractions .15 .70 1575@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1576if @var{Y} is present, @var{X} shall be REAL. 1577@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. 1578@end multitable 1579 1580@item @emph{Return value}: 1581The return value is of the same type and kind as @var{X}. 1582If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}. 1583Otherwise, it the arcus tangent of @var{X}, where the real part of 1584the result is in radians and lies in the range 1585@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}. 1586 1587@item @emph{Example}: 1588@smallexample 1589program test_atan 1590 real(8) :: x = 2.866_8 1591 x = atan(x) 1592end program test_atan 1593@end smallexample 1594 1595@item @emph{Specific names}: 1596@multitable @columnfractions .20 .23 .20 .33 1597@headitem Name @tab Argument @tab Return type @tab Standard 1598@item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1599@item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1600@end multitable 1601 1602@item @emph{See also}: 1603Inverse function: @gol 1604@ref{TAN} @gol 1605Degrees function: @gol 1606@ref{ATAND} 1607@end table 1608 1609 1610 1611@node ATAND 1612@section @code{ATAND} --- Arctangent function, degrees 1613@fnindex ATAND 1614@fnindex DATAND 1615@cindex trigonometric function, tangent, inverse, degrees 1616@cindex tangent, inverse, degrees 1617 1618@table @asis 1619@item @emph{Description}: 1620@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of 1621@ref{TAND}). 1622 1623This function is for compatibility only and should be avoided in favor of 1624standard constructs wherever possible. 1625 1626@item @emph{Standard}: 1627GNU extension, enabled with @option{-fdec-math}. 1628 1629@item @emph{Class}: 1630Elemental function 1631 1632@item @emph{Syntax}: 1633@multitable @columnfractions .80 1634@item @code{RESULT = ATAND(X)} 1635@item @code{RESULT = ATAND(Y, X)} 1636@end multitable 1637 1638@item @emph{Arguments}: 1639@multitable @columnfractions .15 .70 1640@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1641if @var{Y} is present, @var{X} shall be REAL. 1642@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. 1643@end multitable 1644 1645@item @emph{Return value}: 1646The return value is of the same type and kind as @var{X}. 1647If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}. 1648Otherwise, it is the arcus tangent of @var{X}, where the real part of 1649the result is in degrees and lies in the range 1650@math{-90 \leq \Re \atand(x) \leq 90}. 1651 1652@item @emph{Example}: 1653@smallexample 1654program test_atand 1655 real(8) :: x = 2.866_8 1656 x = atand(x) 1657end program test_atand 1658@end smallexample 1659 1660@item @emph{Specific names}: 1661@multitable @columnfractions .23 .23 .20 .30 1662@headitem Name @tab Argument @tab Return type @tab Standard 1663@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 1664@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1665@end multitable 1666 1667@item @emph{See also}: 1668Inverse function: @gol 1669@ref{TAND} @gol 1670Radians function: @gol 1671@ref{ATAN} 1672@end table 1673 1674 1675 1676@node ATAN2 1677@section @code{ATAN2} --- Arctangent function 1678@fnindex ATAN2 1679@fnindex DATAN2 1680@cindex trigonometric function, tangent, inverse 1681@cindex tangent, inverse 1682 1683@table @asis 1684@item @emph{Description}: 1685@code{ATAN2(Y, X)} computes the principal value of the argument 1686function of the complex number @math{X + i Y}. This function can 1687be used to transform from Cartesian into polar coordinates and 1688allows to determine the angle in the correct quadrant. 1689 1690@item @emph{Standard}: 1691Fortran 77 and later 1692 1693@item @emph{Class}: 1694Elemental function 1695 1696@item @emph{Syntax}: 1697@code{RESULT = ATAN2(Y, X)} 1698 1699@item @emph{Arguments}: 1700@multitable @columnfractions .15 .70 1701@item @var{Y} @tab The type shall be @code{REAL}. 1702@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1703If @var{Y} is zero, then @var{X} must be nonzero. 1704@end multitable 1705 1706@item @emph{Return value}: 1707The return value has the same type and kind type parameter as @var{Y}. It 1708is the principal value of the complex number @math{X + i Y}. If @var{X} 1709is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}. 1710The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1711the return value is zero if @var{X} is strictly positive, @math{\pi} if 1712@var{X} is negative and @var{Y} is positive zero (or the processor does 1713not handle signed zeros), and @math{-\pi} if @var{X} is negative and 1714@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1715magnitude of the result is @math{\pi/2}. 1716 1717@item @emph{Example}: 1718@smallexample 1719program test_atan2 1720 real(4) :: x = 1.e0_4, y = 0.5e0_4 1721 x = atan2(y,x) 1722end program test_atan2 1723@end smallexample 1724 1725@item @emph{Specific names}: 1726@multitable @columnfractions .22 .22 .20 .32 1727@headitem Name @tab Argument @tab Return type @tab Standard 1728@item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 1729@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 1730@end multitable 1731 1732@item @emph{See also}: 1733Alias: @gol 1734@ref{ATAN} @gol 1735Degrees function: @gol 1736@ref{ATAN2D} 1737@end table 1738 1739 1740 1741@node ATAN2D 1742@section @code{ATAN2D} --- Arctangent function, degrees 1743@fnindex ATAN2D 1744@fnindex DATAN2D 1745@cindex trigonometric function, tangent, inverse, degrees 1746@cindex tangent, inverse, degrees 1747 1748@table @asis 1749@item @emph{Description}: 1750@code{ATAN2D(Y, X)} computes the principal value of the argument 1751function of the complex number @math{X + i Y} in degrees. This function can 1752be used to transform from Cartesian into polar coordinates and 1753allows to determine the angle in the correct quadrant. 1754 1755This function is for compatibility only and should be avoided in favor of 1756standard constructs wherever possible. 1757 1758@item @emph{Standard}: 1759GNU extension, enabled with @option{-fdec-math}. 1760 1761@item @emph{Class}: 1762Elemental function 1763 1764@item @emph{Syntax}: 1765@code{RESULT = ATAN2D(Y, X)} 1766 1767@item @emph{Arguments}: 1768@multitable @columnfractions .15 .70 1769@item @var{Y} @tab The type shall be @code{REAL}. 1770@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1771If @var{Y} is zero, then @var{X} must be nonzero. 1772@end multitable 1773 1774@item @emph{Return value}: 1775The return value has the same type and kind type parameter as @var{Y}. It 1776is the principal value of the complex number @math{X + i Y}. If @var{X} 1777is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}. 1778The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1779the return value is zero if @var{X} is strictly positive, @math{180} if 1780@var{X} is negative and @var{Y} is positive zero (or the processor does 1781not handle signed zeros), and @math{-180} if @var{X} is negative and 1782@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1783magnitude of the result is @math{90}. 1784 1785@item @emph{Example}: 1786@smallexample 1787program test_atan2d 1788 real(4) :: x = 1.e0_4, y = 0.5e0_4 1789 x = atan2d(y,x) 1790end program test_atan2d 1791@end smallexample 1792 1793@item @emph{Specific names}: 1794@multitable @columnfractions .23 .23 .20 .30 1795@headitem Name @tab Argument @tab Return type @tab Standard 1796@item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU extension 1797@item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension 1798@end multitable 1799 1800@item @emph{See also}: 1801Alias: @gol 1802@ref{ATAND} @gol 1803Radians function: @gol 1804@ref{ATAN2} 1805@end table 1806 1807 1808 1809@node ATANH 1810@section @code{ATANH} --- Inverse hyperbolic tangent function 1811@fnindex ATANH 1812@fnindex DATANH 1813@cindex area hyperbolic tangent 1814@cindex inverse hyperbolic tangent 1815@cindex hyperbolic function, tangent, inverse 1816@cindex tangent, hyperbolic, inverse 1817 1818@table @asis 1819@item @emph{Description}: 1820@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}. 1821 1822@item @emph{Standard}: 1823Fortran 2008 and later 1824 1825@item @emph{Class}: 1826Elemental function 1827 1828@item @emph{Syntax}: 1829@code{RESULT = ATANH(X)} 1830 1831@item @emph{Arguments}: 1832@multitable @columnfractions .15 .70 1833@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1834@end multitable 1835 1836@item @emph{Return value}: 1837The return value has same type and kind as @var{X}. If @var{X} is 1838complex, the imaginary part of the result is in radians and lies between 1839@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}. 1840 1841@item @emph{Example}: 1842@smallexample 1843PROGRAM test_atanh 1844 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1845 WRITE (*,*) ATANH(x) 1846END PROGRAM 1847@end smallexample 1848 1849@item @emph{Specific names}: 1850@multitable @columnfractions .20 .23 .20 .33 1851@headitem Name @tab Argument @tab Return type @tab Standard 1852@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1853@end multitable 1854 1855@item @emph{See also}: 1856Inverse function: @gol 1857@ref{TANH} 1858@end table 1859 1860 1861 1862@node ATOMIC_ADD 1863@section @code{ATOMIC_ADD} --- Atomic ADD operation 1864@fnindex ATOMIC_ADD 1865@cindex Atomic subroutine, add 1866 1867@table @asis 1868@item @emph{Description}: 1869@code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VALUE} to the 1870variable @var{ATOM}. When @var{STAT} is present and the invocation was 1871successful, it is assigned the value 0. If it is present and the invocation 1872has failed, it is assigned a positive value; in particular, for a coindexed 1873@var{ATOM}, if the remote image has stopped, it is assigned the value of 1874@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1875failed, the value @code{STAT_FAILED_IMAGE}. 1876 1877@item @emph{Standard}: 1878TS 18508 or later 1879 1880@item @emph{Class}: 1881Atomic subroutine 1882 1883@item @emph{Syntax}: 1884@code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])} 1885 1886@item @emph{Arguments}: 1887@multitable @columnfractions .15 .70 1888@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1889type with @code{ATOMIC_INT_KIND} kind. 1890@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1891is different, the value is converted to the kind of @var{ATOM}. 1892@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1893@end multitable 1894 1895@item @emph{Example}: 1896@smallexample 1897program atomic 1898 use iso_fortran_env 1899 integer(atomic_int_kind) :: atom[*] 1900 call atomic_add (atom[1], this_image()) 1901end program atomic 1902@end smallexample 1903 1904@item @emph{See also}: 1905@ref{ATOMIC_DEFINE}, @gol 1906@ref{ATOMIC_FETCH_ADD}, @gol 1907@ref{ISO_FORTRAN_ENV}, @gol 1908@ref{ATOMIC_AND}, @gol 1909@ref{ATOMIC_OR}, @gol 1910@ref{ATOMIC_XOR} 1911@end table 1912 1913 1914 1915 1916@node ATOMIC_AND 1917@section @code{ATOMIC_AND} --- Atomic bitwise AND operation 1918@fnindex ATOMIC_AND 1919@cindex Atomic subroutine, AND 1920 1921@table @asis 1922@item @emph{Description}: 1923@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 1924AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 1925and the invocation was successful, it is assigned the value 0. If it is present 1926and the invocation has failed, it is assigned a positive value; in particular, 1927for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 1928value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 1929image has failed, the value @code{STAT_FAILED_IMAGE}. 1930 1931@item @emph{Standard}: 1932TS 18508 or later 1933 1934@item @emph{Class}: 1935Atomic subroutine 1936 1937@item @emph{Syntax}: 1938@code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])} 1939 1940@item @emph{Arguments}: 1941@multitable @columnfractions .15 .70 1942@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1943type with @code{ATOMIC_INT_KIND} kind. 1944@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1945is different, the value is converted to the kind of @var{ATOM}. 1946@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1947@end multitable 1948 1949@item @emph{Example}: 1950@smallexample 1951program atomic 1952 use iso_fortran_env 1953 integer(atomic_int_kind) :: atom[*] 1954 call atomic_and (atom[1], int(b'10100011101')) 1955end program atomic 1956@end smallexample 1957 1958@item @emph{See also}: 1959@ref{ATOMIC_DEFINE}, @gol 1960@ref{ATOMIC_FETCH_AND}, @gol 1961@ref{ISO_FORTRAN_ENV}, @gol 1962@ref{ATOMIC_ADD}, @gol 1963@ref{ATOMIC_OR}, @gol 1964@ref{ATOMIC_XOR} 1965@end table 1966 1967 1968 1969@node ATOMIC_CAS 1970@section @code{ATOMIC_CAS} --- Atomic compare and swap 1971@fnindex ATOMIC_DEFINE 1972@cindex Atomic subroutine, compare and swap 1973 1974@table @asis 1975@item @emph{Description}: 1976@code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of 1977@var{COMPARE}; if the value is the same, @var{ATOM} is set to the value 1978of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM} 1979that was used for the comparison. When @var{STAT} is present and the invocation 1980was successful, it is assigned the value 0. If it is present and the invocation 1981has failed, it is assigned a positive value; in particular, for a coindexed 1982@var{ATOM}, if the remote image has stopped, it is assigned the value of 1983@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1984failed, the value @code{STAT_FAILED_IMAGE}. 1985 1986@item @emph{Standard}: 1987TS 18508 or later 1988 1989@item @emph{Class}: 1990Atomic subroutine 1991 1992@item @emph{Syntax}: 1993@code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])} 1994 1995@item @emph{Arguments}: 1996@multitable @columnfractions .15 .70 1997@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 1998type with @code{ATOMIC_INT_KIND} kind or logical type with 1999@code{ATOMIC_LOGICAL_KIND} kind. 2000@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2001@item @var{COMPARE} @tab Scalar variable of the same type and kind as 2002@var{ATOM}. 2003@item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind 2004is different, the value is converted to the kind of @var{ATOM}. 2005@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2006@end multitable 2007 2008@item @emph{Example}: 2009@smallexample 2010program atomic 2011 use iso_fortran_env 2012 logical(atomic_logical_kind) :: atom[*], prev 2013 call atomic_cas (atom[1], prev, .false., .true.)) 2014end program atomic 2015@end smallexample 2016 2017@item @emph{See also}: 2018@ref{ATOMIC_DEFINE}, @gol 2019@ref{ATOMIC_REF}, @gol 2020@ref{ISO_FORTRAN_ENV} 2021@end table 2022 2023 2024 2025@node ATOMIC_DEFINE 2026@section @code{ATOMIC_DEFINE} --- Setting a variable atomically 2027@fnindex ATOMIC_DEFINE 2028@cindex Atomic subroutine, define 2029 2030@table @asis 2031@item @emph{Description}: 2032@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value 2033@var{VALUE} atomically. When @var{STAT} is present and the invocation was 2034successful, it is assigned the value 0. If it is present and the invocation 2035has failed, it is assigned a positive value; in particular, for a coindexed 2036@var{ATOM}, if the remote image has stopped, it is assigned the value of 2037@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2038failed, the value @code{STAT_FAILED_IMAGE}. 2039 2040@item @emph{Standard}: 2041Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2042 2043@item @emph{Class}: 2044Atomic subroutine 2045 2046@item @emph{Syntax}: 2047@code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])} 2048 2049@item @emph{Arguments}: 2050@multitable @columnfractions .15 .70 2051@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2052type with @code{ATOMIC_INT_KIND} kind or logical type with 2053@code{ATOMIC_LOGICAL_KIND} kind. 2054 2055@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2056is different, the value is converted to the kind of @var{ATOM}. 2057@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2058@end multitable 2059 2060@item @emph{Example}: 2061@smallexample 2062program atomic 2063 use iso_fortran_env 2064 integer(atomic_int_kind) :: atom[*] 2065 call atomic_define (atom[1], this_image()) 2066end program atomic 2067@end smallexample 2068 2069@item @emph{See also}: 2070@ref{ATOMIC_REF}, @gol 2071@ref{ATOMIC_CAS}, @gol 2072@ref{ISO_FORTRAN_ENV}, @gol 2073@ref{ATOMIC_ADD}, @gol 2074@ref{ATOMIC_AND}, @gol 2075@ref{ATOMIC_OR}, @gol 2076@ref{ATOMIC_XOR} 2077@end table 2078 2079 2080 2081@node ATOMIC_FETCH_ADD 2082@section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch 2083@fnindex ATOMIC_FETCH_ADD 2084@cindex Atomic subroutine, ADD with fetch 2085 2086@table @asis 2087@item @emph{Description}: 2088@code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of 2089@var{ATOM} in @var{OLD} and adds the value of @var{VALUE} to the 2090variable @var{ATOM}. When @var{STAT} is present and the invocation was 2091successful, it is assigned the value 0. If it is present and the invocation 2092has failed, it is assigned a positive value; in particular, for a coindexed 2093@var{ATOM}, if the remote image has stopped, it is assigned the value of 2094@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2095failed, the value @code{STAT_FAILED_IMAGE}. 2096 2097@item @emph{Standard}: 2098TS 18508 or later 2099 2100@item @emph{Class}: 2101Atomic subroutine 2102 2103@item @emph{Syntax}: 2104@code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])} 2105 2106@item @emph{Arguments}: 2107@multitable @columnfractions .15 .70 2108@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2109type with @code{ATOMIC_INT_KIND} kind. 2110@code{ATOMIC_LOGICAL_KIND} kind. 2111 2112@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2113is different, the value is converted to the kind of @var{ATOM}. 2114@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2115@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2116@end multitable 2117 2118@item @emph{Example}: 2119@smallexample 2120program atomic 2121 use iso_fortran_env 2122 integer(atomic_int_kind) :: atom[*], old 2123 call atomic_add (atom[1], this_image(), old) 2124end program atomic 2125@end smallexample 2126 2127@item @emph{See also}: 2128@ref{ATOMIC_DEFINE}, @gol 2129@ref{ATOMIC_ADD}, @gol 2130@ref{ISO_FORTRAN_ENV}, @gol 2131@ref{ATOMIC_FETCH_AND}, @gol 2132@ref{ATOMIC_FETCH_OR}, @gol 2133@ref{ATOMIC_FETCH_XOR} 2134@end table 2135 2136 2137 2138@node ATOMIC_FETCH_AND 2139@section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch 2140@fnindex ATOMIC_FETCH_AND 2141@cindex Atomic subroutine, AND with fetch 2142 2143@table @asis 2144@item @emph{Description}: 2145@code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2146@var{OLD} and defines @var{ATOM} with the bitwise AND between the values of 2147@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2148successful, it is assigned the value 0. If it is present and the invocation has 2149failed, it is assigned a positive value; in particular, for a coindexed 2150@var{ATOM}, if the remote image has stopped, it is assigned the value of 2151@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2152failed, the value @code{STAT_FAILED_IMAGE}. 2153 2154@item @emph{Standard}: 2155TS 18508 or later 2156 2157@item @emph{Class}: 2158Atomic subroutine 2159 2160@item @emph{Syntax}: 2161@code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])} 2162 2163@item @emph{Arguments}: 2164@multitable @columnfractions .15 .70 2165@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2166type with @code{ATOMIC_INT_KIND} kind. 2167@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2168is different, the value is converted to the kind of @var{ATOM}. 2169@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2170@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2171@end multitable 2172 2173@item @emph{Example}: 2174@smallexample 2175program atomic 2176 use iso_fortran_env 2177 integer(atomic_int_kind) :: atom[*], old 2178 call atomic_fetch_and (atom[1], int(b'10100011101'), old) 2179end program atomic 2180@end smallexample 2181 2182@item @emph{See also}: 2183@ref{ATOMIC_DEFINE}, @gol 2184@ref{ATOMIC_AND}, @gol 2185@ref{ISO_FORTRAN_ENV}, @gol 2186@ref{ATOMIC_FETCH_ADD}, @gol 2187@ref{ATOMIC_FETCH_OR}, @gol 2188@ref{ATOMIC_FETCH_XOR} 2189@end table 2190 2191 2192 2193@node ATOMIC_FETCH_OR 2194@section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch 2195@fnindex ATOMIC_FETCH_OR 2196@cindex Atomic subroutine, OR with fetch 2197 2198@table @asis 2199@item @emph{Description}: 2200@code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2201@var{OLD} and defines @var{ATOM} with the bitwise OR between the values of 2202@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2203successful, it is assigned the value 0. If it is present and the invocation has 2204failed, it is assigned a positive value; in particular, for a coindexed 2205@var{ATOM}, if the remote image has stopped, it is assigned the value of 2206@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2207failed, the value @code{STAT_FAILED_IMAGE}. 2208 2209@item @emph{Standard}: 2210TS 18508 or later 2211 2212@item @emph{Class}: 2213Atomic subroutine 2214 2215@item @emph{Syntax}: 2216@code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])} 2217 2218@item @emph{Arguments}: 2219@multitable @columnfractions .15 .70 2220@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2221type with @code{ATOMIC_INT_KIND} kind. 2222@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2223is different, the value is converted to the kind of @var{ATOM}. 2224@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2225@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2226@end multitable 2227 2228@item @emph{Example}: 2229@smallexample 2230program atomic 2231 use iso_fortran_env 2232 integer(atomic_int_kind) :: atom[*], old 2233 call atomic_fetch_or (atom[1], int(b'10100011101'), old) 2234end program atomic 2235@end smallexample 2236 2237@item @emph{See also}: 2238@ref{ATOMIC_DEFINE}, @gol 2239@ref{ATOMIC_OR}, @gol 2240@ref{ISO_FORTRAN_ENV}, @gol 2241@ref{ATOMIC_FETCH_ADD}, @gol 2242@ref{ATOMIC_FETCH_AND}, @gol 2243@ref{ATOMIC_FETCH_XOR} 2244@end table 2245 2246 2247 2248@node ATOMIC_FETCH_XOR 2249@section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch 2250@fnindex ATOMIC_FETCH_XOR 2251@cindex Atomic subroutine, XOR with fetch 2252 2253@table @asis 2254@item @emph{Description}: 2255@code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2256@var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of 2257@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2258successful, it is assigned the value 0. If it is present and the invocation has 2259failed, it is assigned a positive value; in particular, for a coindexed 2260@var{ATOM}, if the remote image has stopped, it is assigned the value of 2261@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2262failed, the value @code{STAT_FAILED_IMAGE}. 2263 2264@item @emph{Standard}: 2265TS 18508 or later 2266 2267@item @emph{Class}: 2268Atomic subroutine 2269 2270@item @emph{Syntax}: 2271@code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])} 2272 2273@item @emph{Arguments}: 2274@multitable @columnfractions .15 .70 2275@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2276type with @code{ATOMIC_INT_KIND} kind. 2277@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2278is different, the value is converted to the kind of @var{ATOM}. 2279@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2280@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2281@end multitable 2282 2283@item @emph{Example}: 2284@smallexample 2285program atomic 2286 use iso_fortran_env 2287 integer(atomic_int_kind) :: atom[*], old 2288 call atomic_fetch_xor (atom[1], int(b'10100011101'), old) 2289end program atomic 2290@end smallexample 2291 2292@item @emph{See also}: 2293@ref{ATOMIC_DEFINE}, @gol 2294@ref{ATOMIC_XOR}, @gol 2295@ref{ISO_FORTRAN_ENV}, @gol 2296@ref{ATOMIC_FETCH_ADD}, @gol 2297@ref{ATOMIC_FETCH_AND}, @gol 2298@ref{ATOMIC_FETCH_OR} 2299@end table 2300 2301 2302 2303@node ATOMIC_OR 2304@section @code{ATOMIC_OR} --- Atomic bitwise OR operation 2305@fnindex ATOMIC_OR 2306@cindex Atomic subroutine, OR 2307 2308@table @asis 2309@item @emph{Description}: 2310@code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2311AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2312and the invocation was successful, it is assigned the value 0. If it is present 2313and the invocation has failed, it is assigned a positive value; in particular, 2314for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2315value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2316image has failed, the value @code{STAT_FAILED_IMAGE}. 2317 2318@item @emph{Standard}: 2319TS 18508 or later 2320 2321@item @emph{Class}: 2322Atomic subroutine 2323 2324@item @emph{Syntax}: 2325@code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])} 2326 2327@item @emph{Arguments}: 2328@multitable @columnfractions .15 .70 2329@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2330type with @code{ATOMIC_INT_KIND} kind. 2331@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2332is different, the value is converted to the kind of @var{ATOM}. 2333@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2334@end multitable 2335 2336@item @emph{Example}: 2337@smallexample 2338program atomic 2339 use iso_fortran_env 2340 integer(atomic_int_kind) :: atom[*] 2341 call atomic_or (atom[1], int(b'10100011101')) 2342end program atomic 2343@end smallexample 2344 2345@item @emph{See also}: 2346@ref{ATOMIC_DEFINE}, @gol 2347@ref{ATOMIC_FETCH_OR}, @gol 2348@ref{ISO_FORTRAN_ENV}, @gol 2349@ref{ATOMIC_ADD}, @gol 2350@ref{ATOMIC_OR}, @gol 2351@ref{ATOMIC_XOR} 2352@end table 2353 2354 2355 2356@node ATOMIC_REF 2357@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically 2358@fnindex ATOMIC_REF 2359@cindex Atomic subroutine, reference 2360 2361@table @asis 2362@item @emph{Description}: 2363@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the 2364variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the 2365invocation was successful, it is assigned the value 0. If it is present and the 2366invocation has failed, it is assigned a positive value; in particular, for a 2367coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value 2368of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image 2369has failed, the value @code{STAT_FAILED_IMAGE}. 2370 2371 2372@item @emph{Standard}: 2373Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2374 2375@item @emph{Class}: 2376Atomic subroutine 2377 2378@item @emph{Syntax}: 2379@code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])} 2380 2381@item @emph{Arguments}: 2382@multitable @columnfractions .15 .70 2383@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2384is different, the value is converted to the kind of @var{ATOM}. 2385@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2386type with @code{ATOMIC_INT_KIND} kind or logical type with 2387@code{ATOMIC_LOGICAL_KIND} kind. 2388@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2389@end multitable 2390 2391@item @emph{Example}: 2392@smallexample 2393program atomic 2394 use iso_fortran_env 2395 logical(atomic_logical_kind) :: atom[*] 2396 logical :: val 2397 call atomic_ref (atom, .false.) 2398 ! ... 2399 call atomic_ref (atom, val) 2400 if (val) then 2401 print *, "Obtained" 2402 end if 2403end program atomic 2404@end smallexample 2405 2406@item @emph{See also}: 2407@ref{ATOMIC_DEFINE}, @gol 2408@ref{ATOMIC_CAS}, @gol 2409@ref{ISO_FORTRAN_ENV}, @gol 2410@ref{ATOMIC_FETCH_ADD}, @gol 2411@ref{ATOMIC_FETCH_AND}, @gol 2412@ref{ATOMIC_FETCH_OR}, @gol 2413@ref{ATOMIC_FETCH_XOR} 2414@end table 2415 2416 2417@node ATOMIC_XOR 2418@section @code{ATOMIC_XOR} --- Atomic bitwise OR operation 2419@fnindex ATOMIC_XOR 2420@cindex Atomic subroutine, XOR 2421 2422@table @asis 2423@item @emph{Description}: 2424@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2425XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2426and the invocation was successful, it is assigned the value 0. If it is present 2427and the invocation has failed, it is assigned a positive value; in particular, 2428for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2429value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2430image has failed, the value @code{STAT_FAILED_IMAGE}. 2431 2432@item @emph{Standard}: 2433TS 18508 or later 2434 2435@item @emph{Class}: 2436Atomic subroutine 2437 2438@item @emph{Syntax}: 2439@code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])} 2440 2441@item @emph{Arguments}: 2442@multitable @columnfractions .15 .70 2443@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2444type with @code{ATOMIC_INT_KIND} kind. 2445@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2446is different, the value is converted to the kind of @var{ATOM}. 2447@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2448@end multitable 2449 2450@item @emph{Example}: 2451@smallexample 2452program atomic 2453 use iso_fortran_env 2454 integer(atomic_int_kind) :: atom[*] 2455 call atomic_xor (atom[1], int(b'10100011101')) 2456end program atomic 2457@end smallexample 2458 2459@item @emph{See also}: 2460@ref{ATOMIC_DEFINE}, @gol 2461@ref{ATOMIC_FETCH_XOR}, @gol 2462@ref{ISO_FORTRAN_ENV}, @gol 2463@ref{ATOMIC_ADD}, @gol 2464@ref{ATOMIC_OR}, @gol 2465@ref{ATOMIC_XOR} 2466@end table 2467 2468 2469@node BACKTRACE 2470@section @code{BACKTRACE} --- Show a backtrace 2471@fnindex BACKTRACE 2472@cindex backtrace 2473 2474@table @asis 2475@item @emph{Description}: 2476@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program 2477execution continues normally afterwards. The backtrace information is printed 2478to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}. 2479 2480@item @emph{Standard}: 2481GNU extension 2482 2483@item @emph{Class}: 2484Subroutine 2485 2486@item @emph{Syntax}: 2487@code{CALL BACKTRACE} 2488 2489@item @emph{Arguments}: 2490None 2491 2492@item @emph{See also}: 2493@ref{ABORT} 2494@end table 2495 2496 2497 2498@node BESSEL_J0 2499@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0 2500@fnindex BESSEL_J0 2501@fnindex BESJ0 2502@fnindex DBESJ0 2503@cindex Bessel function, first kind 2504 2505@table @asis 2506@item @emph{Description}: 2507@code{BESSEL_J0(X)} computes the Bessel function of the first kind of 2508order 0 of @var{X}. This function is available under the name 2509@code{BESJ0} as a GNU extension. 2510 2511@item @emph{Standard}: 2512Fortran 2008 and later 2513 2514@item @emph{Class}: 2515Elemental function 2516 2517@item @emph{Syntax}: 2518@code{RESULT = BESSEL_J0(X)} 2519 2520@item @emph{Arguments}: 2521@multitable @columnfractions .15 .70 2522@item @var{X} @tab The type shall be @code{REAL}. 2523@end multitable 2524 2525@item @emph{Return value}: 2526The return value is of type @code{REAL} and lies in the 2527range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same 2528kind as @var{X}. 2529 2530@item @emph{Example}: 2531@smallexample 2532program test_besj0 2533 real(8) :: x = 0.0_8 2534 x = bessel_j0(x) 2535end program test_besj0 2536@end smallexample 2537 2538@item @emph{Specific names}: 2539@multitable @columnfractions .21 .22 .20 .33 2540@headitem Name @tab Argument @tab Return type @tab Standard 2541@item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2542@end multitable 2543@end table 2544 2545 2546 2547@node BESSEL_J1 2548@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1 2549@fnindex BESSEL_J1 2550@fnindex BESJ1 2551@fnindex DBESJ1 2552@cindex Bessel function, first kind 2553 2554@table @asis 2555@item @emph{Description}: 2556@code{BESSEL_J1(X)} computes the Bessel function of the first kind of 2557order 1 of @var{X}. This function is available under the name 2558@code{BESJ1} as a GNU extension. 2559 2560@item @emph{Standard}: 2561Fortran 2008 2562 2563@item @emph{Class}: 2564Elemental function 2565 2566@item @emph{Syntax}: 2567@code{RESULT = BESSEL_J1(X)} 2568 2569@item @emph{Arguments}: 2570@multitable @columnfractions .15 .70 2571@item @var{X} @tab The type shall be @code{REAL}. 2572@end multitable 2573 2574@item @emph{Return value}: 2575The return value is of type @code{REAL} and lies in the 2576range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same 2577kind as @var{X}. 2578 2579@item @emph{Example}: 2580@smallexample 2581program test_besj1 2582 real(8) :: x = 1.0_8 2583 x = bessel_j1(x) 2584end program test_besj1 2585@end smallexample 2586 2587@item @emph{Specific names}: 2588@multitable @columnfractions .20 .23 .20 .33 2589@headitem Name @tab Argument @tab Return type @tab Standard 2590@item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2591@end multitable 2592@end table 2593 2594 2595 2596@node BESSEL_JN 2597@section @code{BESSEL_JN} --- Bessel function of the first kind 2598@fnindex BESSEL_JN 2599@fnindex BESJN 2600@fnindex DBESJN 2601@cindex Bessel function, first kind 2602 2603@table @asis 2604@item @emph{Description}: 2605@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of 2606order @var{N} of @var{X}. This function is available under the name 2607@code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays, 2608their ranks and shapes shall conform. 2609 2610@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions 2611of the first kind of the orders @var{N1} to @var{N2}. 2612 2613@item @emph{Standard}: 2614Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2615 2616@item @emph{Class}: 2617Elemental function, except for the transformational function 2618@code{BESSEL_JN(N1, N2, X)} 2619 2620@item @emph{Syntax}: 2621@multitable @columnfractions .80 2622@item @code{RESULT = BESSEL_JN(N, X)} 2623@item @code{RESULT = BESSEL_JN(N1, N2, X)} 2624@end multitable 2625 2626@item @emph{Arguments}: 2627@multitable @columnfractions .15 .70 2628@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}. 2629@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2630@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2631@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2632for @code{BESSEL_JN(N1, N2, X)} it shall be scalar. 2633@end multitable 2634 2635@item @emph{Return value}: 2636The return value is a scalar of type @code{REAL}. It has the same 2637kind as @var{X}. 2638 2639@item @emph{Note}: 2640The transformational function uses a recurrence algorithm which might, 2641for some values of @var{X}, lead to different results than calls to 2642the elemental function. 2643 2644@item @emph{Example}: 2645@smallexample 2646program test_besjn 2647 real(8) :: x = 1.0_8 2648 x = bessel_jn(5,x) 2649end program test_besjn 2650@end smallexample 2651 2652@item @emph{Specific names}: 2653@multitable @columnfractions .22 .22 .20 .32 2654@headitem Name @tab Argument @tab Return type @tab Standard 2655@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2656@item @tab @code{REAL(8) X} @tab @tab 2657@end multitable 2658@end table 2659 2660 2661 2662@node BESSEL_Y0 2663@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0 2664@fnindex BESSEL_Y0 2665@fnindex BESY0 2666@fnindex DBESY0 2667@cindex Bessel function, second kind 2668 2669@table @asis 2670@item @emph{Description}: 2671@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of 2672order 0 of @var{X}. This function is available under the name 2673@code{BESY0} as a GNU extension. 2674 2675@item @emph{Standard}: 2676Fortran 2008 and later 2677 2678@item @emph{Class}: 2679Elemental function 2680 2681@item @emph{Syntax}: 2682@code{RESULT = BESSEL_Y0(X)} 2683 2684@item @emph{Arguments}: 2685@multitable @columnfractions .15 .70 2686@item @var{X} @tab The type shall be @code{REAL}. 2687@end multitable 2688 2689@item @emph{Return value}: 2690The return value is of type @code{REAL}. It has the same kind as @var{X}. 2691 2692@item @emph{Example}: 2693@smallexample 2694program test_besy0 2695 real(8) :: x = 0.0_8 2696 x = bessel_y0(x) 2697end program test_besy0 2698@end smallexample 2699 2700@item @emph{Specific names}: 2701@multitable @columnfractions .20 .23 .20 .33 2702@headitem Name @tab Argument @tab Return type @tab Standard 2703@item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2704@end multitable 2705@end table 2706 2707 2708 2709@node BESSEL_Y1 2710@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1 2711@fnindex BESSEL_Y1 2712@fnindex BESY1 2713@fnindex DBESY1 2714@cindex Bessel function, second kind 2715 2716@table @asis 2717@item @emph{Description}: 2718@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of 2719order 1 of @var{X}. This function is available under the name 2720@code{BESY1} as a GNU extension. 2721 2722@item @emph{Standard}: 2723Fortran 2008 and later 2724 2725@item @emph{Class}: 2726Elemental function 2727 2728@item @emph{Syntax}: 2729@code{RESULT = BESSEL_Y1(X)} 2730 2731@item @emph{Arguments}: 2732@multitable @columnfractions .15 .70 2733@item @var{X} @tab The type shall be @code{REAL}. 2734@end multitable 2735 2736@item @emph{Return value}: 2737The return value is of type @code{REAL}. It has the same kind as @var{X}. 2738 2739@item @emph{Example}: 2740@smallexample 2741program test_besy1 2742 real(8) :: x = 1.0_8 2743 x = bessel_y1(x) 2744end program test_besy1 2745@end smallexample 2746 2747@item @emph{Specific names}: 2748@multitable @columnfractions .20 .23 .20 .33 2749@headitem Name @tab Argument @tab Return type @tab Standard 2750@item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2751@end multitable 2752@end table 2753 2754 2755 2756@node BESSEL_YN 2757@section @code{BESSEL_YN} --- Bessel function of the second kind 2758@fnindex BESSEL_YN 2759@fnindex BESYN 2760@fnindex DBESYN 2761@cindex Bessel function, second kind 2762 2763@table @asis 2764@item @emph{Description}: 2765@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of 2766order @var{N} of @var{X}. This function is available under the name 2767@code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays, 2768their ranks and shapes shall conform. 2769 2770@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions 2771of the first kind of the orders @var{N1} to @var{N2}. 2772 2773@item @emph{Standard}: 2774Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2775 2776@item @emph{Class}: 2777Elemental function, except for the transformational function 2778@code{BESSEL_YN(N1, N2, X)} 2779 2780@item @emph{Syntax}: 2781@multitable @columnfractions .80 2782@item @code{RESULT = BESSEL_YN(N, X)} 2783@item @code{RESULT = BESSEL_YN(N1, N2, X)} 2784@end multitable 2785 2786@item @emph{Arguments}: 2787@multitable @columnfractions .15 .70 2788@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} . 2789@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2790@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2791@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2792for @code{BESSEL_YN(N1, N2, X)} it shall be scalar. 2793@end multitable 2794 2795@item @emph{Return value}: 2796The return value is a scalar of type @code{REAL}. It has the same 2797kind as @var{X}. 2798 2799@item @emph{Note}: 2800The transformational function uses a recurrence algorithm which might, 2801for some values of @var{X}, lead to different results than calls to 2802the elemental function. 2803 2804@item @emph{Example}: 2805@smallexample 2806program test_besyn 2807 real(8) :: x = 1.0_8 2808 x = bessel_yn(5,x) 2809end program test_besyn 2810@end smallexample 2811 2812@item @emph{Specific names}: 2813@multitable @columnfractions .20 .23 .20 .33 2814@headitem Name @tab Argument @tab Return type @tab Standard 2815@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2816@item @tab @code{REAL(8) X} @tab @tab 2817@end multitable 2818@end table 2819 2820 2821 2822@node BGE 2823@section @code{BGE} --- Bitwise greater than or equal to 2824@fnindex BGE 2825@cindex bitwise comparison 2826 2827@table @asis 2828@item @emph{Description}: 2829Determines whether an integral is a bitwise greater than or equal to 2830another. 2831 2832@item @emph{Standard}: 2833Fortran 2008 and later 2834 2835@item @emph{Class}: 2836Elemental function 2837 2838@item @emph{Syntax}: 2839@code{RESULT = BGE(I, J)} 2840 2841@item @emph{Arguments}: 2842@multitable @columnfractions .15 .70 2843@item @var{I} @tab Shall be of @code{INTEGER} type. 2844@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2845as @var{I}. 2846@end multitable 2847 2848@item @emph{Return value}: 2849The return value is of type @code{LOGICAL} and of the default kind. 2850 2851@item @emph{See also}: 2852@ref{BGT}, @gol 2853@ref{BLE}, @gol 2854@ref{BLT} 2855@end table 2856 2857 2858 2859@node BGT 2860@section @code{BGT} --- Bitwise greater than 2861@fnindex BGT 2862@cindex bitwise comparison 2863 2864@table @asis 2865@item @emph{Description}: 2866Determines whether an integral is a bitwise greater than another. 2867 2868@item @emph{Standard}: 2869Fortran 2008 and later 2870 2871@item @emph{Class}: 2872Elemental function 2873 2874@item @emph{Syntax}: 2875@code{RESULT = BGT(I, J)} 2876 2877@item @emph{Arguments}: 2878@multitable @columnfractions .15 .70 2879@item @var{I} @tab Shall be of @code{INTEGER} type. 2880@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2881as @var{I}. 2882@end multitable 2883 2884@item @emph{Return value}: 2885The return value is of type @code{LOGICAL} and of the default kind. 2886 2887@item @emph{See also}: 2888@ref{BGE}, @gol 2889@ref{BLE}, @gol 2890@ref{BLT} 2891@end table 2892 2893 2894 2895@node BIT_SIZE 2896@section @code{BIT_SIZE} --- Bit size inquiry function 2897@fnindex BIT_SIZE 2898@cindex bits, number of 2899@cindex size of a variable, in bits 2900 2901@table @asis 2902@item @emph{Description}: 2903@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) 2904represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is 2905independent of the actual value of @var{I}. 2906 2907@item @emph{Standard}: 2908Fortran 90 and later 2909 2910@item @emph{Class}: 2911Inquiry function 2912 2913@item @emph{Syntax}: 2914@code{RESULT = BIT_SIZE(I)} 2915 2916@item @emph{Arguments}: 2917@multitable @columnfractions .15 .70 2918@item @var{I} @tab The type shall be @code{INTEGER}. 2919@end multitable 2920 2921@item @emph{Return value}: 2922The return value is of type @code{INTEGER} 2923 2924@item @emph{Example}: 2925@smallexample 2926program test_bit_size 2927 integer :: i = 123 2928 integer :: size 2929 size = bit_size(i) 2930 print *, size 2931end program test_bit_size 2932@end smallexample 2933@end table 2934 2935 2936 2937@node BLE 2938@section @code{BLE} --- Bitwise less than or equal to 2939@fnindex BLE 2940@cindex bitwise comparison 2941 2942@table @asis 2943@item @emph{Description}: 2944Determines whether an integral is a bitwise less than or equal to 2945another. 2946 2947@item @emph{Standard}: 2948Fortran 2008 and later 2949 2950@item @emph{Class}: 2951Elemental function 2952 2953@item @emph{Syntax}: 2954@code{RESULT = BLE(I, J)} 2955 2956@item @emph{Arguments}: 2957@multitable @columnfractions .15 .70 2958@item @var{I} @tab Shall be of @code{INTEGER} type. 2959@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2960as @var{I}. 2961@end multitable 2962 2963@item @emph{Return value}: 2964The return value is of type @code{LOGICAL} and of the default kind. 2965 2966@item @emph{See also}: 2967@ref{BGT}, @gol 2968@ref{BGE}, @gol 2969@ref{BLT} 2970@end table 2971 2972 2973 2974@node BLT 2975@section @code{BLT} --- Bitwise less than 2976@fnindex BLT 2977@cindex bitwise comparison 2978 2979@table @asis 2980@item @emph{Description}: 2981Determines whether an integral is a bitwise less than another. 2982 2983@item @emph{Standard}: 2984Fortran 2008 and later 2985 2986@item @emph{Class}: 2987Elemental function 2988 2989@item @emph{Syntax}: 2990@code{RESULT = BLT(I, J)} 2991 2992@item @emph{Arguments}: 2993@multitable @columnfractions .15 .70 2994@item @var{I} @tab Shall be of @code{INTEGER} type. 2995@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2996as @var{I}. 2997@end multitable 2998 2999@item @emph{Return value}: 3000The return value is of type @code{LOGICAL} and of the default kind. 3001 3002@item @emph{See also}: 3003@ref{BGE}, @gol 3004@ref{BGT}, @gol 3005@ref{BLE} 3006@end table 3007 3008 3009 3010@node BTEST 3011@section @code{BTEST} --- Bit test function 3012@fnindex BTEST 3013@fnindex BBTEST 3014@fnindex BITEST 3015@fnindex BJTEST 3016@fnindex BKTEST 3017@cindex bits, testing 3018 3019@table @asis 3020@item @emph{Description}: 3021@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} 3022in @var{I} is set. The counting of the bits starts at 0. 3023 3024@item @emph{Standard}: 3025Fortran 90 and later, has overloads that are GNU extensions 3026 3027@item @emph{Class}: 3028Elemental function 3029 3030@item @emph{Syntax}: 3031@code{RESULT = BTEST(I, POS)} 3032 3033@item @emph{Arguments}: 3034@multitable @columnfractions .15 .70 3035@item @var{I} @tab The type shall be @code{INTEGER}. 3036@item @var{POS} @tab The type shall be @code{INTEGER}. 3037@end multitable 3038 3039@item @emph{Return value}: 3040The return value is of type @code{LOGICAL} 3041 3042@item @emph{Example}: 3043@smallexample 3044program test_btest 3045 integer :: i = 32768 + 1024 + 64 3046 integer :: pos 3047 logical :: bool 3048 do pos=0,16 3049 bool = btest(i, pos) 3050 print *, pos, bool 3051 end do 3052end program test_btest 3053@end smallexample 3054 3055@item @emph{Specific names}: 3056@multitable @columnfractions .21 .28 .18 .30 3057@headitem Name @tab Argument @tab Return type @tab Standard 3058@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later 3059@item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension 3060@item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension 3061@item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension 3062@item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension 3063@end multitable 3064@end table 3065 3066@node C_ASSOCIATED 3067@section @code{C_ASSOCIATED} --- Status of a C pointer 3068@fnindex C_ASSOCIATED 3069@cindex association status, C pointer 3070@cindex pointer, C association status 3071 3072@table @asis 3073@item @emph{Description}: 3074@code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer 3075@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}. 3076 3077@item @emph{Standard}: 3078Fortran 2003 and later 3079 3080@item @emph{Class}: 3081Inquiry function 3082 3083@item @emph{Syntax}: 3084@code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])} 3085 3086@item @emph{Arguments}: 3087@multitable @columnfractions .15 .70 3088@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}. 3089@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}. 3090@end multitable 3091 3092@item @emph{Return value}: 3093The return value is of type @code{LOGICAL}; it is @code{.false.} if either 3094@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2} 3095point to different addresses. 3096 3097@item @emph{Example}: 3098@smallexample 3099subroutine association_test(a,b) 3100 use iso_c_binding, only: c_associated, c_loc, c_ptr 3101 implicit none 3102 real, pointer :: a 3103 type(c_ptr) :: b 3104 if(c_associated(b, c_loc(a))) & 3105 stop 'b and a do not point to same target' 3106end subroutine association_test 3107@end smallexample 3108 3109@item @emph{See also}: 3110@ref{C_LOC}, @gol 3111@ref{C_FUNLOC} 3112@end table 3113 3114 3115@node C_F_POINTER 3116@section @code{C_F_POINTER} --- Convert C into Fortran pointer 3117@fnindex C_F_POINTER 3118@cindex pointer, convert C to Fortran 3119 3120@table @asis 3121@item @emph{Description}: 3122@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer 3123@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape. 3124 3125@item @emph{Standard}: 3126Fortran 2003 and later 3127 3128@item @emph{Class}: 3129Subroutine 3130 3131@item @emph{Syntax}: 3132@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])} 3133 3134@item @emph{Arguments}: 3135@multitable @columnfractions .15 .70 3136@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is 3137@code{INTENT(IN)}. 3138@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is 3139@code{INTENT(OUT)}. 3140@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER} 3141with @code{INTENT(IN)}. It shall be present 3142if and only if @var{fptr} is an array. The size 3143must be equal to the rank of @var{fptr}. 3144@end multitable 3145 3146@item @emph{Example}: 3147@smallexample 3148program main 3149 use iso_c_binding 3150 implicit none 3151 interface 3152 subroutine my_routine(p) bind(c,name='myC_func') 3153 import :: c_ptr 3154 type(c_ptr), intent(out) :: p 3155 end subroutine 3156 end interface 3157 type(c_ptr) :: cptr 3158 real,pointer :: a(:) 3159 call my_routine(cptr) 3160 call c_f_pointer(cptr, a, [12]) 3161end program main 3162@end smallexample 3163 3164@item @emph{See also}: 3165@ref{C_LOC}, @gol 3166@ref{C_F_PROCPOINTER} 3167@end table 3168 3169 3170@node C_F_PROCPOINTER 3171@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer 3172@fnindex C_F_PROCPOINTER 3173@cindex pointer, C address of pointers 3174 3175@table @asis 3176@item @emph{Description}: 3177@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer 3178@var{CPTR} to the Fortran procedure pointer @var{FPTR}. 3179 3180@item @emph{Standard}: 3181Fortran 2003 and later 3182 3183@item @emph{Class}: 3184Subroutine 3185 3186@item @emph{Syntax}: 3187@code{CALL C_F_PROCPOINTER(cptr, fptr)} 3188 3189@item @emph{Arguments}: 3190@multitable @columnfractions .15 .70 3191@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is 3192@code{INTENT(IN)}. 3193@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is 3194@code{INTENT(OUT)}. 3195@end multitable 3196 3197@item @emph{Example}: 3198@smallexample 3199program main 3200 use iso_c_binding 3201 implicit none 3202 abstract interface 3203 function func(a) 3204 import :: c_float 3205 real(c_float), intent(in) :: a 3206 real(c_float) :: func 3207 end function 3208 end interface 3209 interface 3210 function getIterFunc() bind(c,name="getIterFunc") 3211 import :: c_funptr 3212 type(c_funptr) :: getIterFunc 3213 end function 3214 end interface 3215 type(c_funptr) :: cfunptr 3216 procedure(func), pointer :: myFunc 3217 cfunptr = getIterFunc() 3218 call c_f_procpointer(cfunptr, myFunc) 3219end program main 3220@end smallexample 3221 3222@item @emph{See also}: 3223@ref{C_LOC}, @gol 3224@ref{C_F_POINTER} 3225@end table 3226 3227 3228@node C_FUNLOC 3229@section @code{C_FUNLOC} --- Obtain the C address of a procedure 3230@fnindex C_FUNLOC 3231@cindex pointer, C address of procedures 3232 3233@table @asis 3234@item @emph{Description}: 3235@code{C_FUNLOC(x)} determines the C address of the argument. 3236 3237@item @emph{Standard}: 3238Fortran 2003 and later 3239 3240@item @emph{Class}: 3241Inquiry function 3242 3243@item @emph{Syntax}: 3244@code{RESULT = C_FUNLOC(x)} 3245 3246@item @emph{Arguments}: 3247@multitable @columnfractions .15 .70 3248@item @var{x} @tab Interoperable function or pointer to such function. 3249@end multitable 3250 3251@item @emph{Return value}: 3252The return value is of type @code{C_FUNPTR} and contains the C address 3253of the argument. 3254 3255@item @emph{Example}: 3256@smallexample 3257module x 3258 use iso_c_binding 3259 implicit none 3260contains 3261 subroutine sub(a) bind(c) 3262 real(c_float) :: a 3263 a = sqrt(a)+5.0 3264 end subroutine sub 3265end module x 3266program main 3267 use iso_c_binding 3268 use x 3269 implicit none 3270 interface 3271 subroutine my_routine(p) bind(c,name='myC_func') 3272 import :: c_funptr 3273 type(c_funptr), intent(in) :: p 3274 end subroutine 3275 end interface 3276 call my_routine(c_funloc(sub)) 3277end program main 3278@end smallexample 3279 3280@item @emph{See also}: 3281@ref{C_ASSOCIATED}, @gol 3282@ref{C_LOC}, @gol 3283@ref{C_F_POINTER}, @gol 3284@ref{C_F_PROCPOINTER} 3285@end table 3286 3287 3288@node C_LOC 3289@section @code{C_LOC} --- Obtain the C address of an object 3290@fnindex C_LOC 3291@cindex procedure pointer, convert C to Fortran 3292 3293@table @asis 3294@item @emph{Description}: 3295@code{C_LOC(X)} determines the C address of the argument. 3296 3297@item @emph{Standard}: 3298Fortran 2003 and later 3299 3300@item @emph{Class}: 3301Inquiry function 3302 3303@item @emph{Syntax}: 3304@code{RESULT = C_LOC(X)} 3305 3306@item @emph{Arguments}: 3307@multitable @columnfractions .10 .75 3308@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. 3309 3310@end multitable 3311 3312@item @emph{Return value}: 3313The return value is of type @code{C_PTR} and contains the C address 3314of the argument. 3315 3316@item @emph{Example}: 3317@smallexample 3318subroutine association_test(a,b) 3319 use iso_c_binding, only: c_associated, c_loc, c_ptr 3320 implicit none 3321 real, pointer :: a 3322 type(c_ptr) :: b 3323 if(c_associated(b, c_loc(a))) & 3324 stop 'b and a do not point to same target' 3325end subroutine association_test 3326@end smallexample 3327 3328@item @emph{See also}: 3329@ref{C_ASSOCIATED}, @gol 3330@ref{C_FUNLOC}, @gol 3331@ref{C_F_POINTER}, @gol 3332@ref{C_F_PROCPOINTER} 3333@end table 3334 3335 3336@node C_SIZEOF 3337@section @code{C_SIZEOF} --- Size in bytes of an expression 3338@fnindex C_SIZEOF 3339@cindex expression size 3340@cindex size of an expression 3341 3342@table @asis 3343@item @emph{Description}: 3344@code{C_SIZEOF(X)} calculates the number of bytes of storage the 3345expression @code{X} occupies. 3346 3347@item @emph{Standard}: 3348Fortran 2008 3349 3350@item @emph{Class}: 3351Inquiry function of the module @code{ISO_C_BINDING} 3352 3353@item @emph{Syntax}: 3354@code{N = C_SIZEOF(X)} 3355 3356@item @emph{Arguments}: 3357@multitable @columnfractions .15 .70 3358@item @var{X} @tab The argument shall be an interoperable data entity. 3359@end multitable 3360 3361@item @emph{Return value}: 3362The return value is of type integer and of the system-dependent kind 3363@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the 3364number of bytes occupied by the argument. If the argument has the 3365@code{POINTER} attribute, the number of bytes of the storage area pointed 3366to is returned. If the argument is of a derived type with @code{POINTER} 3367or @code{ALLOCATABLE} components, the return value does not account for 3368the sizes of the data pointed to by these components. 3369 3370@item @emph{Example}: 3371@smallexample 3372 use iso_c_binding 3373 integer(c_int) :: i 3374 real(c_float) :: r, s(5) 3375 print *, (c_sizeof(s)/c_sizeof(r) == 5) 3376 end 3377@end smallexample 3378The example will print @code{T} unless you are using a platform 3379where default @code{REAL} variables are unusually padded. 3380 3381@item @emph{See also}: 3382@ref{SIZEOF}, @gol 3383@ref{STORAGE_SIZE} 3384@end table 3385 3386 3387@node CEILING 3388@section @code{CEILING} --- Integer ceiling function 3389@fnindex CEILING 3390@cindex ceiling 3391@cindex rounding, ceiling 3392 3393@table @asis 3394@item @emph{Description}: 3395@code{CEILING(A)} returns the least integer greater than or equal to @var{A}. 3396 3397@item @emph{Standard}: 3398Fortran 95 and later 3399 3400@item @emph{Class}: 3401Elemental function 3402 3403@item @emph{Syntax}: 3404@code{RESULT = CEILING(A [, KIND])} 3405 3406@item @emph{Arguments}: 3407@multitable @columnfractions .15 .70 3408@item @var{A} @tab The type shall be @code{REAL}. 3409@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3410expression indicating the kind parameter of the result. 3411@end multitable 3412 3413@item @emph{Return value}: 3414The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 3415and a default-kind @code{INTEGER} otherwise. 3416 3417@item @emph{Example}: 3418@smallexample 3419program test_ceiling 3420 real :: x = 63.29 3421 real :: y = -63.59 3422 print *, ceiling(x) ! returns 64 3423 print *, ceiling(y) ! returns -63 3424end program test_ceiling 3425@end smallexample 3426 3427@item @emph{See also}: 3428@ref{FLOOR}, @gol 3429@ref{NINT} 3430@end table 3431 3432 3433 3434@node CHAR 3435@section @code{CHAR} --- Character conversion function 3436@fnindex CHAR 3437@cindex conversion, to character 3438 3439@table @asis 3440@item @emph{Description}: 3441@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}. 3442 3443@item @emph{Standard}: 3444Fortran 77 and later 3445 3446@item @emph{Class}: 3447Elemental function 3448 3449@item @emph{Syntax}: 3450@code{RESULT = CHAR(I [, KIND])} 3451 3452@item @emph{Arguments}: 3453@multitable @columnfractions .15 .70 3454@item @var{I} @tab The type shall be @code{INTEGER}. 3455@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3456expression indicating the kind parameter of the result. 3457@end multitable 3458 3459@item @emph{Return value}: 3460The return value is of type @code{CHARACTER(1)} 3461 3462@item @emph{Example}: 3463@smallexample 3464program test_char 3465 integer :: i = 74 3466 character(1) :: c 3467 c = char(i) 3468 print *, i, c ! returns 'J' 3469end program test_char 3470@end smallexample 3471 3472@item @emph{Specific names}: 3473@multitable @columnfractions .19 .19 .25 .33 3474@headitem Name @tab Argument @tab Return type @tab Standard 3475@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later 3476@end multitable 3477 3478@item @emph{Note}: 3479See @ref{ICHAR} for a discussion of converting between numerical values 3480and formatted string representations. 3481 3482@item @emph{See also}: 3483@ref{ACHAR}, @gol 3484@ref{IACHAR}, @gol 3485@ref{ICHAR} 3486 3487@end table 3488 3489 3490 3491@node CHDIR 3492@section @code{CHDIR} --- Change working directory 3493@fnindex CHDIR 3494@cindex system, working directory 3495 3496@table @asis 3497@item @emph{Description}: 3498Change current working directory to a specified path. 3499 3500This intrinsic is provided in both subroutine and function forms; however, 3501only one form can be used in any given program unit. 3502 3503@item @emph{Standard}: 3504GNU extension 3505 3506@item @emph{Class}: 3507Subroutine, function 3508 3509@item @emph{Syntax}: 3510@multitable @columnfractions .80 3511@item @code{CALL CHDIR(NAME [, STATUS])} 3512@item @code{STATUS = CHDIR(NAME)} 3513@end multitable 3514 3515@item @emph{Arguments}: 3516@multitable @columnfractions .15 .70 3517@item @var{NAME} @tab The type shall be @code{CHARACTER} of default 3518kind and shall specify a valid path within the file system. 3519@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default 3520kind. Returns 0 on success, and a system specific and nonzero error code 3521otherwise. 3522@end multitable 3523 3524@item @emph{Example}: 3525@smallexample 3526PROGRAM test_chdir 3527 CHARACTER(len=255) :: path 3528 CALL getcwd(path) 3529 WRITE(*,*) TRIM(path) 3530 CALL chdir("/tmp") 3531 CALL getcwd(path) 3532 WRITE(*,*) TRIM(path) 3533END PROGRAM 3534@end smallexample 3535 3536@item @emph{See also}: 3537@ref{GETCWD} 3538@end table 3539 3540 3541 3542@node CHMOD 3543@section @code{CHMOD} --- Change access permissions of files 3544@fnindex CHMOD 3545@cindex file system, change access mode 3546 3547@table @asis 3548@item @emph{Description}: 3549@code{CHMOD} changes the permissions of a file. 3550 3551This intrinsic is provided in both subroutine and function forms; however, 3552only one form can be used in any given program unit. 3553 3554@item @emph{Standard}: 3555GNU extension 3556 3557@item @emph{Class}: 3558Subroutine, function 3559 3560@item @emph{Syntax}: 3561@multitable @columnfractions .80 3562@item @code{CALL CHMOD(NAME, MODE[, STATUS])} 3563@item @code{STATUS = CHMOD(NAME, MODE)} 3564@end multitable 3565 3566@item @emph{Arguments}: 3567@multitable @columnfractions .15 .70 3568 3569@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 3570file name. Trailing blanks are ignored unless the character 3571@code{achar(0)} is present, then all characters up to and excluding 3572@code{achar(0)} are used as the file name. 3573 3574@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the 3575file permission. @var{MODE} uses the same syntax as the @code{chmod} utility 3576as defined by the POSIX standard. The argument shall either be a string of 3577a nonnegative octal number or a symbolic mode. 3578 3579@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is 3580@code{0} on success and nonzero otherwise. 3581@end multitable 3582 3583@item @emph{Return value}: 3584In either syntax, @var{STATUS} is set to @code{0} on success and nonzero 3585otherwise. 3586 3587@item @emph{Example}: 3588@code{CHMOD} as subroutine 3589@smallexample 3590program chmod_test 3591 implicit none 3592 integer :: status 3593 call chmod('test.dat','u+x',status) 3594 print *, 'Status: ', status 3595end program chmod_test 3596@end smallexample 3597@code{CHMOD} as function: 3598@smallexample 3599program chmod_test 3600 implicit none 3601 integer :: status 3602 status = chmod('test.dat','u+x') 3603 print *, 'Status: ', status 3604end program chmod_test 3605@end smallexample 3606 3607@end table 3608 3609 3610 3611@node CMPLX 3612@section @code{CMPLX} --- Complex conversion function 3613@fnindex CMPLX 3614@cindex complex numbers, conversion to 3615@cindex conversion, to complex 3616 3617@table @asis 3618@item @emph{Description}: 3619@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to 3620the real component. If @var{Y} is present it is converted to the imaginary 3621component. If @var{Y} is not present then the imaginary component is set to 36220.0. If @var{X} is complex then @var{Y} must not be present. 3623 3624@item @emph{Standard}: 3625Fortran 77 and later 3626 3627@item @emph{Class}: 3628Elemental function 3629 3630@item @emph{Syntax}: 3631@code{RESULT = CMPLX(X [, Y [, KIND]])} 3632 3633@item @emph{Arguments}: 3634@multitable @columnfractions .15 .70 3635@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 3636or @code{COMPLEX}. 3637@item @var{Y} @tab (Optional; only allowed if @var{X} is not 3638@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. 3639@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3640expression indicating the kind parameter of the result. 3641@end multitable 3642 3643@item @emph{Return value}: 3644The return value is of @code{COMPLEX} type, with a kind equal to 3645@var{KIND} if it is specified. If @var{KIND} is not specified, the 3646result is of the default @code{COMPLEX} kind, regardless of the kinds of 3647@var{X} and @var{Y}. 3648 3649@item @emph{Example}: 3650@smallexample 3651program test_cmplx 3652 integer :: i = 42 3653 real :: x = 3.14 3654 complex :: z 3655 z = cmplx(i, x) 3656 print *, z, cmplx(x) 3657end program test_cmplx 3658@end smallexample 3659 3660@item @emph{See also}: 3661@ref{COMPLEX} 3662@end table 3663 3664 3665 3666@node CO_BROADCAST 3667@section @code{CO_BROADCAST} --- Copy a value to all images the current set of images 3668@fnindex CO_BROADCAST 3669@cindex Collectives, value broadcasting 3670 3671@table @asis 3672@item @emph{Description}: 3673@code{CO_BROADCAST} copies the value of argument @var{A} on the image with 3674image index @code{SOURCE_IMAGE} to all images in the current team. @var{A} 3675becomes defined as if by intrinsic assignment. If the execution was 3676successful and @var{STAT} is present, it is assigned the value zero. If the 3677execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3678@var{ERRMSG} gets assigned a value describing the occurred error. 3679 3680@item @emph{Standard}: 3681Technical Specification (TS) 18508 or later 3682 3683@item @emph{Class}: 3684Collective subroutine 3685 3686@item @emph{Syntax}: 3687@code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])} 3688 3689@item @emph{Arguments}: 3690@multitable @columnfractions .20 .65 3691@item @var{A} @tab INTENT(INOUT) argument; shall have the same 3692dynamic type and type parameters on all images of the current team. If it 3693is an array, it shall have the same shape on all images. 3694@item @var{SOURCE_IMAGE} @tab a scalar integer expression. 3695It shall have the same value on all images and refer to an 3696image of the current team. 3697@item @var{STAT} @tab (optional) a scalar integer variable 3698@item @var{ERRMSG} @tab (optional) a scalar character variable 3699@end multitable 3700 3701@item @emph{Example}: 3702@smallexample 3703program test 3704 integer :: val(3) 3705 if (this_image() == 1) then 3706 val = [1, 5, 3] 3707 end if 3708 call co_broadcast (val, source_image=1) 3709 print *, this_image, ":", val 3710end program test 3711@end smallexample 3712 3713@item @emph{See also}: 3714@ref{CO_MAX}, @gol 3715@ref{CO_MIN}, @gol 3716@ref{CO_SUM}, @gol 3717@ref{CO_REDUCE} 3718@end table 3719 3720 3721 3722@node CO_MAX 3723@section @code{CO_MAX} --- Maximal value on the current set of images 3724@fnindex CO_MAX 3725@cindex Collectives, maximal value 3726 3727@table @asis 3728@item @emph{Description}: 3729@code{CO_MAX} determines element-wise the maximal value of @var{A} on all 3730images of the current team. If @var{RESULT_IMAGE} is present, the maximum 3731values are returned in @var{A} on the specified image only and the value 3732of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3733not present, the value is returned on all images. If the execution was 3734successful and @var{STAT} is present, it is assigned the value zero. If the 3735execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3736@var{ERRMSG} gets assigned a value describing the occurred error. 3737 3738@item @emph{Standard}: 3739Technical Specification (TS) 18508 or later 3740 3741@item @emph{Class}: 3742Collective subroutine 3743 3744@item @emph{Syntax}: 3745@code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])} 3746 3747@item @emph{Arguments}: 3748@multitable @columnfractions .20 .65 3749@item @var{A} @tab shall be an integer, real or character variable, 3750which has the same type and type parameters on all images of the team. 3751@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3752present, it shall have the same value on all images and refer to an 3753image of the current team. 3754@item @var{STAT} @tab (optional) a scalar integer variable 3755@item @var{ERRMSG} @tab (optional) a scalar character variable 3756@end multitable 3757 3758@item @emph{Example}: 3759@smallexample 3760program test 3761 integer :: val 3762 val = this_image () 3763 call co_max (val, result_image=1) 3764 if (this_image() == 1) then 3765 write(*,*) "Maximal value", val ! prints num_images() 3766 end if 3767end program test 3768@end smallexample 3769 3770@item @emph{See also}: 3771@ref{CO_MIN}, @gol 3772@ref{CO_SUM}, @gol 3773@ref{CO_REDUCE}, @gol 3774@ref{CO_BROADCAST} 3775@end table 3776 3777 3778 3779@node CO_MIN 3780@section @code{CO_MIN} --- Minimal value on the current set of images 3781@fnindex CO_MIN 3782@cindex Collectives, minimal value 3783 3784@table @asis 3785@item @emph{Description}: 3786@code{CO_MIN} determines element-wise the minimal value of @var{A} on all 3787images of the current team. If @var{RESULT_IMAGE} is present, the minimal 3788values are returned in @var{A} on the specified image only and the value 3789of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3790not present, the value is returned on all images. If the execution was 3791successful and @var{STAT} is present, it is assigned the value zero. If the 3792execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3793@var{ERRMSG} gets assigned a value describing the occurred error. 3794 3795@item @emph{Standard}: 3796Technical Specification (TS) 18508 or later 3797 3798@item @emph{Class}: 3799Collective subroutine 3800 3801@item @emph{Syntax}: 3802@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3803 3804@item @emph{Arguments}: 3805@multitable @columnfractions .20 .65 3806@item @var{A} @tab shall be an integer, real or character variable, 3807which has the same type and type parameters on all images of the team. 3808@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3809present, it shall have the same value on all images and refer to an 3810image of the current team. 3811@item @var{STAT} @tab (optional) a scalar integer variable 3812@item @var{ERRMSG} @tab (optional) a scalar character variable 3813@end multitable 3814 3815@item @emph{Example}: 3816@smallexample 3817program test 3818 integer :: val 3819 val = this_image () 3820 call co_min (val, result_image=1) 3821 if (this_image() == 1) then 3822 write(*,*) "Minimal value", val ! prints 1 3823 end if 3824end program test 3825@end smallexample 3826 3827@item @emph{See also}: 3828@ref{CO_MAX}, @gol 3829@ref{CO_SUM}, @gol 3830@ref{CO_REDUCE}, @gol 3831@ref{CO_BROADCAST} 3832@end table 3833 3834 3835 3836@node CO_REDUCE 3837@section @code{CO_REDUCE} --- Reduction of values on the current set of images 3838@fnindex CO_REDUCE 3839@cindex Collectives, generic reduction 3840 3841@table @asis 3842@item @emph{Description}: 3843@code{CO_REDUCE} determines element-wise the reduction of the value of @var{A} 3844on all images of the current team. The pure function passed as @var{OPERATION} 3845is used to pairwise reduce the values of @var{A} by passing either the value 3846of @var{A} of different images or the result values of such a reduction as 3847argument. If @var{A} is an array, the deduction is done element wise. If 3848@var{RESULT_IMAGE} is present, the result values are returned in @var{A} on 3849the specified image only and the value of @var{A} on the other images become 3850undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all 3851images. If the execution was successful and @var{STAT} is present, it is 3852assigned the value zero. If the execution failed, @var{STAT} gets assigned 3853a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing 3854the occurred error. 3855 3856@item @emph{Standard}: 3857Technical Specification (TS) 18508 or later 3858 3859@item @emph{Class}: 3860Collective subroutine 3861 3862@item @emph{Syntax}: 3863@code{CALL CO_REDUCE(A, OPERATION, [, RESULT_IMAGE, STAT, ERRMSG])} 3864 3865@item @emph{Arguments}: 3866@multitable @columnfractions .20 .65 3867@item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be 3868nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, 3869it shall be associated. @var{A} shall have the same type and type parameters on 3870all images of the team; if it is an array, it shall have the same shape on all 3871images. 3872@item @var{OPERATION} @tab pure function with two scalar nonallocatable 3873arguments, which shall be nonpolymorphic and have the same type and type 3874parameters as @var{A}. The function shall return a nonallocatable scalar of 3875the same type and type parameters as @var{A}. The function shall be the same on 3876all images and with regards to the arguments mathematically commutative and 3877associative. Note that @var{OPERATION} may not be an elemental function, unless 3878it is an intrisic function. 3879@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3880present, it shall have the same value on all images and refer to an 3881image of the current team. 3882@item @var{STAT} @tab (optional) a scalar integer variable 3883@item @var{ERRMSG} @tab (optional) a scalar character variable 3884@end multitable 3885 3886@item @emph{Example}: 3887@smallexample 3888program test 3889 integer :: val 3890 val = this_image () 3891 call co_reduce (val, result_image=1, operation=myprod) 3892 if (this_image() == 1) then 3893 write(*,*) "Product value", val ! prints num_images() factorial 3894 end if 3895contains 3896 pure function myprod(a, b) 3897 integer, value :: a, b 3898 integer :: myprod 3899 myprod = a * b 3900 end function myprod 3901end program test 3902@end smallexample 3903 3904@item @emph{Note}: 3905While the rules permit in principle an intrinsic function, none of the 3906intrinsics in the standard fulfill the criteria of having a specific 3907function, which takes two arguments of the same type and returning that 3908type as result. 3909 3910@item @emph{See also}: 3911@ref{CO_MIN}, @gol 3912@ref{CO_MAX}, @gol 3913@ref{CO_SUM}, @gol 3914@ref{CO_BROADCAST} 3915@end table 3916 3917 3918 3919@node CO_SUM 3920@section @code{CO_SUM} --- Sum of values on the current set of images 3921@fnindex CO_SUM 3922@cindex Collectives, sum of values 3923 3924@table @asis 3925@item @emph{Description}: 3926@code{CO_SUM} sums up the values of each element of @var{A} on all 3927images of the current team. If @var{RESULT_IMAGE} is present, the summed-up 3928values are returned in @var{A} on the specified image only and the value 3929of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3930not present, the value is returned on all images. If the execution was 3931successful and @var{STAT} is present, it is assigned the value zero. If the 3932execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3933@var{ERRMSG} gets assigned a value describing the occurred error. 3934 3935@item @emph{Standard}: 3936Technical Specification (TS) 18508 or later 3937 3938@item @emph{Class}: 3939Collective subroutine 3940 3941@item @emph{Syntax}: 3942@code{CALL CO_SUM(A [, RESULT_IMAGE, STAT, ERRMSG])} 3943 3944@item @emph{Arguments}: 3945@multitable @columnfractions .20 .65 3946@item @var{A} @tab shall be an integer, real or complex variable, 3947which has the same type and type parameters on all images of the team. 3948@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3949present, it shall have the same value on all images and refer to an 3950image of the current team. 3951@item @var{STAT} @tab (optional) a scalar integer variable 3952@item @var{ERRMSG} @tab (optional) a scalar character variable 3953@end multitable 3954 3955@item @emph{Example}: 3956@smallexample 3957program test 3958 integer :: val 3959 val = this_image () 3960 call co_sum (val, result_image=1) 3961 if (this_image() == 1) then 3962 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, 3963 ! with n = num_images() 3964 end if 3965end program test 3966@end smallexample 3967 3968@item @emph{See also}: 3969@ref{CO_MAX}, @gol 3970@ref{CO_MIN}, @gol 3971@ref{CO_REDUCE}, @gol 3972@ref{CO_BROADCAST} 3973@end table 3974 3975 3976 3977@node COMMAND_ARGUMENT_COUNT 3978@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments 3979@fnindex COMMAND_ARGUMENT_COUNT 3980@cindex command-line arguments 3981@cindex command-line arguments, number of 3982@cindex arguments, to program 3983 3984@table @asis 3985@item @emph{Description}: 3986@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the 3987command line when the containing program was invoked. 3988 3989@item @emph{Standard}: 3990Fortran 2003 and later 3991 3992@item @emph{Class}: 3993Inquiry function 3994 3995@item @emph{Syntax}: 3996@code{RESULT = COMMAND_ARGUMENT_COUNT()} 3997 3998@item @emph{Arguments}: 3999@multitable @columnfractions .15 .70 4000@item None 4001@end multitable 4002 4003@item @emph{Return value}: 4004The return value is an @code{INTEGER} of default kind. 4005 4006@item @emph{Example}: 4007@smallexample 4008program test_command_argument_count 4009 integer :: count 4010 count = command_argument_count() 4011 print *, count 4012end program test_command_argument_count 4013@end smallexample 4014 4015@item @emph{See also}: 4016@ref{GET_COMMAND}, @gol 4017@ref{GET_COMMAND_ARGUMENT} 4018@end table 4019 4020 4021 4022@node COMPILER_OPTIONS 4023@section @code{COMPILER_OPTIONS} --- Options passed to the compiler 4024@fnindex COMPILER_OPTIONS 4025@cindex flags inquiry function 4026@cindex options inquiry function 4027@cindex compiler flags inquiry function 4028 4029@table @asis 4030@item @emph{Description}: 4031@code{COMPILER_OPTIONS} returns a string with the options used for 4032compiling. 4033 4034@item @emph{Standard}: 4035Fortran 2008 4036 4037@item @emph{Class}: 4038Inquiry function of the module @code{ISO_FORTRAN_ENV} 4039 4040@item @emph{Syntax}: 4041@code{STR = COMPILER_OPTIONS()} 4042 4043@item @emph{Arguments}: 4044None 4045 4046@item @emph{Return value}: 4047The return value is a default-kind string with system-dependent length. 4048It contains the compiler flags used to compile the file, which called 4049the @code{COMPILER_OPTIONS} intrinsic. 4050 4051@item @emph{Example}: 4052@smallexample 4053 use iso_fortran_env 4054 print '(4a)', 'This file was compiled by ', & 4055 compiler_version(), ' using the options ', & 4056 compiler_options() 4057 end 4058@end smallexample 4059 4060@item @emph{See also}: 4061@ref{COMPILER_VERSION}, @gol 4062@ref{ISO_FORTRAN_ENV} 4063@end table 4064 4065 4066 4067@node COMPILER_VERSION 4068@section @code{COMPILER_VERSION} --- Compiler version string 4069@fnindex COMPILER_VERSION 4070@cindex compiler, name and version 4071@cindex version of the compiler 4072 4073@table @asis 4074@item @emph{Description}: 4075@code{COMPILER_VERSION} returns a string with the name and the 4076version of the compiler. 4077 4078@item @emph{Standard}: 4079Fortran 2008 4080 4081@item @emph{Class}: 4082Inquiry function of the module @code{ISO_FORTRAN_ENV} 4083 4084@item @emph{Syntax}: 4085@code{STR = COMPILER_VERSION()} 4086 4087@item @emph{Arguments}: 4088None 4089 4090@item @emph{Return value}: 4091The return value is a default-kind string with system-dependent length. 4092It contains the name of the compiler and its version number. 4093 4094@item @emph{Example}: 4095@smallexample 4096 use iso_fortran_env 4097 print '(4a)', 'This file was compiled by ', & 4098 compiler_version(), ' using the options ', & 4099 compiler_options() 4100 end 4101@end smallexample 4102 4103@item @emph{See also}: 4104@ref{COMPILER_OPTIONS}, @gol 4105@ref{ISO_FORTRAN_ENV} 4106@end table 4107 4108 4109 4110@node COMPLEX 4111@section @code{COMPLEX} --- Complex conversion function 4112@fnindex COMPLEX 4113@cindex complex numbers, conversion to 4114@cindex conversion, to complex 4115 4116@table @asis 4117@item @emph{Description}: 4118@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted 4119to the real component and @var{Y} is converted to the imaginary 4120component. 4121 4122@item @emph{Standard}: 4123GNU extension 4124 4125@item @emph{Class}: 4126Elemental function 4127 4128@item @emph{Syntax}: 4129@code{RESULT = COMPLEX(X, Y)} 4130 4131@item @emph{Arguments}: 4132@multitable @columnfractions .15 .70 4133@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4134@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}. 4135@end multitable 4136 4137@item @emph{Return value}: 4138If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return 4139value is of default @code{COMPLEX} type. 4140 4141If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL} 4142type and one is of @code{INTEGER} type, then the return value is of 4143@code{COMPLEX} type with a kind equal to that of the @code{REAL} 4144argument with the highest precision. 4145 4146@item @emph{Example}: 4147@smallexample 4148program test_complex 4149 integer :: i = 42 4150 real :: x = 3.14 4151 print *, complex(i, x) 4152end program test_complex 4153@end smallexample 4154 4155@item @emph{See also}: 4156@ref{CMPLX} 4157@end table 4158 4159 4160 4161@node CONJG 4162@section @code{CONJG} --- Complex conjugate function 4163@fnindex CONJG 4164@fnindex DCONJG 4165@cindex complex conjugate 4166 4167@table @asis 4168@item @emph{Description}: 4169@code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)} 4170then the result is @code{(x, -y)} 4171 4172@item @emph{Standard}: 4173Fortran 77 and later, has an overload that is a GNU extension 4174 4175@item @emph{Class}: 4176Elemental function 4177 4178@item @emph{Syntax}: 4179@code{Z = CONJG(Z)} 4180 4181@item @emph{Arguments}: 4182@multitable @columnfractions .15 .70 4183@item @var{Z} @tab The type shall be @code{COMPLEX}. 4184@end multitable 4185 4186@item @emph{Return value}: 4187The return value is of type @code{COMPLEX}. 4188 4189@item @emph{Example}: 4190@smallexample 4191program test_conjg 4192 complex :: z = (2.0, 3.0) 4193 complex(8) :: dz = (2.71_8, -3.14_8) 4194 z= conjg(z) 4195 print *, z 4196 dz = dconjg(dz) 4197 print *, dz 4198end program test_conjg 4199@end smallexample 4200 4201@item @emph{Specific names}: 4202@multitable @columnfractions .20 .23 .20 .33 4203@headitem Name @tab Argument @tab Return type @tab Standard 4204@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension 4205@end multitable 4206@end table 4207 4208 4209 4210@node COS 4211@section @code{COS} --- Cosine function 4212@fnindex COS 4213@fnindex DCOS 4214@fnindex CCOS 4215@fnindex ZCOS 4216@fnindex CDCOS 4217@cindex trigonometric function, cosine 4218@cindex cosine 4219 4220@table @asis 4221@item @emph{Description}: 4222@code{COS(X)} computes the cosine of @var{X}. 4223 4224@item @emph{Standard}: 4225Fortran 77 and later, has overloads that are GNU extensions 4226 4227@item @emph{Class}: 4228Elemental function 4229 4230@item @emph{Syntax}: 4231@code{RESULT = COS(X)} 4232 4233@item @emph{Arguments}: 4234@multitable @columnfractions .15 .70 4235@item @var{X} @tab The type shall be @code{REAL} or 4236@code{COMPLEX}. 4237@end multitable 4238 4239@item @emph{Return value}: 4240The return value is of the same type and kind as @var{X}. The real part 4241of the result is in radians. If @var{X} is of the type @code{REAL}, 4242the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}. 4243 4244@item @emph{Example}: 4245@smallexample 4246program test_cos 4247 real :: x = 0.0 4248 x = cos(x) 4249end program test_cos 4250@end smallexample 4251 4252@item @emph{Specific names}: 4253@multitable @columnfractions .20 .23 .20 .33 4254@headitem Name @tab Argument @tab Return type @tab Standard 4255@item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4256@item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4257@item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 4258@item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4259@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4260@end multitable 4261 4262@item @emph{See also}: 4263Inverse function: @gol 4264@ref{ACOS} @gol 4265Degrees function: @gol 4266@ref{COSD} 4267@end table 4268 4269 4270 4271@node COSD 4272@section @code{COSD} --- Cosine function, degrees 4273@fnindex COSD 4274@fnindex DCOSD 4275@fnindex CCOSD 4276@fnindex ZCOSD 4277@fnindex CDCOSD 4278@cindex trigonometric function, cosine, degrees 4279@cindex cosine, degrees 4280 4281@table @asis 4282@item @emph{Description}: 4283@code{COSD(X)} computes the cosine of @var{X} in degrees. 4284 4285This function is for compatibility only and should be avoided in favor of 4286standard constructs wherever possible. 4287 4288@item @emph{Standard}: 4289GNU extension, enabled with @option{-fdec-math}. 4290 4291@item @emph{Class}: 4292Elemental function 4293 4294@item @emph{Syntax}: 4295@code{RESULT = COSD(X)} 4296 4297@item @emph{Arguments}: 4298@multitable @columnfractions .15 .70 4299@item @var{X} @tab The type shall be @code{REAL} or 4300@code{COMPLEX}. 4301@end multitable 4302 4303@item @emph{Return value}: 4304The return value is of the same type and kind as @var{X}. The real part 4305of the result is in degrees. If @var{X} is of the type @code{REAL}, 4306the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}. 4307 4308@item @emph{Example}: 4309@smallexample 4310program test_cosd 4311 real :: x = 0.0 4312 x = cosd(x) 4313end program test_cosd 4314@end smallexample 4315 4316@item @emph{Specific names}: 4317@multitable @columnfractions .20 .23 .20 .33 4318@headitem Name @tab Argument @tab Return type @tab Standard 4319@item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4320@item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4321@item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension 4322@item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4323@item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4324@end multitable 4325 4326@item @emph{See also}: 4327Inverse function: @gol 4328@ref{ACOSD} @gol 4329Radians function: @gol 4330@ref{COS} 4331@end table 4332 4333 4334 4335@node COSH 4336@section @code{COSH} --- Hyperbolic cosine function 4337@fnindex COSH 4338@fnindex DCOSH 4339@cindex hyperbolic cosine 4340@cindex hyperbolic function, cosine 4341@cindex cosine, hyperbolic 4342 4343@table @asis 4344@item @emph{Description}: 4345@code{COSH(X)} computes the hyperbolic cosine of @var{X}. 4346 4347@item @emph{Standard}: 4348Fortran 77 and later, for a complex argument Fortran 2008 or later 4349 4350@item @emph{Class}: 4351Elemental function 4352 4353@item @emph{Syntax}: 4354@code{X = COSH(X)} 4355 4356@item @emph{Arguments}: 4357@multitable @columnfractions .15 .70 4358@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4359@end multitable 4360 4361@item @emph{Return value}: 4362The return value has same type and kind as @var{X}. If @var{X} is 4363complex, the imaginary part of the result is in radians. If @var{X} 4364is @code{REAL}, the return value has a lower bound of one, 4365@math{\cosh (x) \geq 1}. 4366 4367@item @emph{Example}: 4368@smallexample 4369program test_cosh 4370 real(8) :: x = 1.0_8 4371 x = cosh(x) 4372end program test_cosh 4373@end smallexample 4374 4375@item @emph{Specific names}: 4376@multitable @columnfractions .20 .23 .20 .33 4377@headitem Name @tab Argument @tab Return type @tab Standard 4378@item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4379@item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4380@end multitable 4381 4382@item @emph{See also}: 4383Inverse function: @gol 4384@ref{ACOSH} 4385@end table 4386 4387 4388 4389@node COTAN 4390@section @code{COTAN} --- Cotangent function 4391@fnindex COTAN 4392@fnindex DCOTAN 4393@cindex trigonometric function, cotangent 4394@cindex cotangent 4395 4396@table @asis 4397@item @emph{Description}: 4398@code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)} 4399divided by @code{SIN(x)}, or @code{1 / TAN(x)}. 4400 4401This function is for compatibility only and should be avoided in favor of 4402standard constructs wherever possible. 4403 4404@item @emph{Standard}: 4405GNU extension, enabled with @option{-fdec-math}. 4406 4407@item @emph{Class}: 4408Elemental function 4409 4410@item @emph{Syntax}: 4411@code{RESULT = COTAN(X)} 4412 4413@item @emph{Arguments}: 4414@multitable @columnfractions .15 .70 4415@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4416@end multitable 4417 4418@item @emph{Return value}: 4419The return value has same type and kind as @var{X}, and its value is in radians. 4420 4421@item @emph{Example}: 4422@smallexample 4423program test_cotan 4424 real(8) :: x = 0.165_8 4425 x = cotan(x) 4426end program test_cotan 4427@end smallexample 4428 4429@item @emph{Specific names}: 4430@multitable @columnfractions .20 .23 .20 .33 4431@headitem Name @tab Argument @tab Return type @tab Standard 4432@item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4433@item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4434@end multitable 4435 4436@item @emph{See also}: 4437Converse function: @gol 4438@ref{TAN} @gol 4439Degrees function: @gol 4440@ref{COTAND} 4441@end table 4442 4443 4444 4445@node COTAND 4446@section @code{COTAND} --- Cotangent function, degrees 4447@fnindex COTAND 4448@fnindex DCOTAND 4449@cindex trigonometric function, cotangent, degrees 4450@cindex cotangent, degrees 4451 4452@table @asis 4453@item @emph{Description}: 4454@code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to 4455@code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}. 4456 4457@item @emph{Standard}: 4458GNU extension, enabled with @option{-fdec-math}. 4459 4460This function is for compatibility only and should be avoided in favor of 4461standard constructs wherever possible. 4462 4463@item @emph{Class}: 4464Elemental function 4465 4466@item @emph{Syntax}: 4467@code{RESULT = COTAND(X)} 4468 4469@item @emph{Arguments}: 4470@multitable @columnfractions .15 .70 4471@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4472@end multitable 4473 4474@item @emph{Return value}: 4475The return value has same type and kind as @var{X}, and its value is in degrees. 4476 4477@item @emph{Example}: 4478@smallexample 4479program test_cotand 4480 real(8) :: x = 0.165_8 4481 x = cotand(x) 4482end program test_cotand 4483@end smallexample 4484 4485@item @emph{Specific names}: 4486@multitable @columnfractions .20 .23 .20 .33 4487@headitem Name @tab Argument @tab Return type @tab Standard 4488@item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4489@item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4490@end multitable 4491 4492@item @emph{See also}: 4493Converse function: @gol 4494@ref{TAND} @gol 4495Radians function: @gol 4496@ref{COTAN} 4497@end table 4498 4499 4500 4501@node COUNT 4502@section @code{COUNT} --- Count function 4503@fnindex COUNT 4504@cindex array, conditionally count elements 4505@cindex array, element counting 4506@cindex array, number of elements 4507 4508@table @asis 4509@item @emph{Description}: 4510 4511Counts the number of @code{.TRUE.} elements in a logical @var{MASK}, 4512or, if the @var{DIM} argument is supplied, counts the number of 4513elements along each row of the array in the @var{DIM} direction. 4514If the array has zero size, or all of the elements of @var{MASK} are 4515@code{.FALSE.}, then the result is @code{0}. 4516 4517@item @emph{Standard}: 4518Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 4519 4520@item @emph{Class}: 4521Transformational function 4522 4523@item @emph{Syntax}: 4524@code{RESULT = COUNT(MASK [, DIM, KIND])} 4525 4526@item @emph{Arguments}: 4527@multitable @columnfractions .15 .70 4528@item @var{MASK} @tab The type shall be @code{LOGICAL}. 4529@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}. 4530@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 4531expression indicating the kind parameter of the result. 4532@end multitable 4533 4534@item @emph{Return value}: 4535The return value is of type @code{INTEGER} and of kind @var{KIND}. If 4536@var{KIND} is absent, the return value is of default integer kind. 4537If @var{DIM} is present, the result is an array with a rank one less 4538than the rank of @var{ARRAY}, and a size corresponding to the shape 4539of @var{ARRAY} with the @var{DIM} dimension removed. 4540 4541@item @emph{Example}: 4542@smallexample 4543program test_count 4544 integer, dimension(2,3) :: a, b 4545 logical, dimension(2,3) :: mask 4546 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) 4547 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /)) 4548 print '(3i3)', a(1,:) 4549 print '(3i3)', a(2,:) 4550 print * 4551 print '(3i3)', b(1,:) 4552 print '(3i3)', b(2,:) 4553 print * 4554 mask = a.ne.b 4555 print '(3l3)', mask(1,:) 4556 print '(3l3)', mask(2,:) 4557 print * 4558 print '(3i3)', count(mask) 4559 print * 4560 print '(3i3)', count(mask, 1) 4561 print * 4562 print '(3i3)', count(mask, 2) 4563end program test_count 4564@end smallexample 4565@end table 4566 4567 4568 4569@node CPU_TIME 4570@section @code{CPU_TIME} --- CPU elapsed time in seconds 4571@fnindex CPU_TIME 4572@cindex time, elapsed 4573 4574@table @asis 4575@item @emph{Description}: 4576Returns a @code{REAL} value representing the elapsed CPU time in 4577seconds. This is useful for testing segments of code to determine 4578execution time. 4579 4580If a time source is available, time will be reported with microsecond 4581resolution. If no time source is available, @var{TIME} is set to 4582@code{-1.0}. 4583 4584Note that @var{TIME} may contain a, system dependent, arbitrary offset 4585and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute 4586value is meaningless, only differences between subsequent calls to 4587this subroutine, as shown in the example below, should be used. 4588 4589 4590@item @emph{Standard}: 4591Fortran 95 and later 4592 4593@item @emph{Class}: 4594Subroutine 4595 4596@item @emph{Syntax}: 4597@code{CALL CPU_TIME(TIME)} 4598 4599@item @emph{Arguments}: 4600@multitable @columnfractions .15 .70 4601@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}. 4602@end multitable 4603 4604@item @emph{Return value}: 4605None 4606 4607@item @emph{Example}: 4608@smallexample 4609program test_cpu_time 4610 real :: start, finish 4611 call cpu_time(start) 4612 ! put code to test here 4613 call cpu_time(finish) 4614 print '("Time = ",f6.3," seconds.")',finish-start 4615end program test_cpu_time 4616@end smallexample 4617 4618@item @emph{See also}: 4619@ref{SYSTEM_CLOCK}, @gol 4620@ref{DATE_AND_TIME} 4621@end table 4622 4623 4624 4625@node CSHIFT 4626@section @code{CSHIFT} --- Circular shift elements of an array 4627@fnindex CSHIFT 4628@cindex array, shift circularly 4629@cindex array, permutation 4630@cindex array, rotate 4631 4632@table @asis 4633@item @emph{Description}: 4634@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of 4635@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is 4636taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the 4637range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. 4638If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted 4639by @var{SHIFT} places. If rank is greater than one, then all complete rank one 4640sections of @var{ARRAY} along the given dimension are shifted. Elements 4641shifted out one end of each rank one section are shifted back in the other end. 4642 4643@item @emph{Standard}: 4644Fortran 90 and later 4645 4646@item @emph{Class}: 4647Transformational function 4648 4649@item @emph{Syntax}: 4650@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])} 4651 4652@item @emph{Arguments}: 4653@multitable @columnfractions .15 .70 4654@item @var{ARRAY} @tab Shall be an array of any type. 4655@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 4656@item @var{DIM} @tab The type shall be @code{INTEGER}. 4657@end multitable 4658 4659@item @emph{Return value}: 4660Returns an array of same type and rank as the @var{ARRAY} argument. 4661 4662@item @emph{Example}: 4663@smallexample 4664program test_cshift 4665 integer, dimension(3,3) :: a 4666 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 4667 print '(3i3)', a(1,:) 4668 print '(3i3)', a(2,:) 4669 print '(3i3)', a(3,:) 4670 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2) 4671 print * 4672 print '(3i3)', a(1,:) 4673 print '(3i3)', a(2,:) 4674 print '(3i3)', a(3,:) 4675end program test_cshift 4676@end smallexample 4677@end table 4678 4679 4680 4681@node CTIME 4682@section @code{CTIME} --- Convert a time into a string 4683@fnindex CTIME 4684@cindex time, conversion to string 4685@cindex conversion, to string 4686 4687@table @asis 4688@item @emph{Description}: 4689@code{CTIME} converts a system time value, such as returned by 4690@ref{TIME8}, to a string. The output will be of the form @samp{Sat 4691Aug 19 18:13:14 1995}. 4692 4693This intrinsic is provided in both subroutine and function forms; however, 4694only one form can be used in any given program unit. 4695 4696@item @emph{Standard}: 4697GNU extension 4698 4699@item @emph{Class}: 4700Subroutine, function 4701 4702@item @emph{Syntax}: 4703@multitable @columnfractions .80 4704@item @code{CALL CTIME(TIME, RESULT)}. 4705@item @code{RESULT = CTIME(TIME)}. 4706@end multitable 4707 4708@item @emph{Arguments}: 4709@multitable @columnfractions .15 .70 4710@item @var{TIME} @tab The type shall be of type @code{INTEGER}. 4711@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and 4712of default kind. It is an @code{INTENT(OUT)} argument. If the length 4713of this variable is too short for the time and date string to fit 4714completely, it will be blank on procedure return. 4715@end multitable 4716 4717@item @emph{Return value}: 4718The converted date and time as a string. 4719 4720@item @emph{Example}: 4721@smallexample 4722program test_ctime 4723 integer(8) :: i 4724 character(len=30) :: date 4725 i = time8() 4726 4727 ! Do something, main part of the program 4728 4729 call ctime(i,date) 4730 print *, 'Program was started on ', date 4731end program test_ctime 4732@end smallexample 4733 4734@item @emph{See Also}: 4735@ref{DATE_AND_TIME}, @gol 4736@ref{GMTIME}, @gol 4737@ref{LTIME}, @gol 4738@ref{TIME}, @gol 4739@ref{TIME8} 4740@end table 4741 4742 4743 4744@node DATE_AND_TIME 4745@section @code{DATE_AND_TIME} --- Date and time subroutine 4746@fnindex DATE_AND_TIME 4747@cindex date, current 4748@cindex current date 4749@cindex time, current 4750@cindex current time 4751 4752@table @asis 4753@item @emph{Description}: 4754@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and 4755time information from the real-time system clock. @var{DATE} is 4756@code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and 4757has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, 4758representing the difference with respect to Coordinated Universal Time (UTC). 4759Unavailable time and date parameters return blanks. 4760 4761@var{VALUES} is @code{INTENT(OUT)} and provides the following: 4762 4763@multitable @columnfractions .15 .70 4764@item @code{VALUE(1)}: @tab The year 4765@item @code{VALUE(2)}: @tab The month 4766@item @code{VALUE(3)}: @tab The day of the month 4767@item @code{VALUE(4)}: @tab Time difference with UTC in minutes 4768@item @code{VALUE(5)}: @tab The hour of the day 4769@item @code{VALUE(6)}: @tab The minutes of the hour 4770@item @code{VALUE(7)}: @tab The seconds of the minute 4771@item @code{VALUE(8)}: @tab The milliseconds of the second 4772@end multitable 4773 4774@item @emph{Standard}: 4775Fortran 90 and later 4776 4777@item @emph{Class}: 4778Subroutine 4779 4780@item @emph{Syntax}: 4781@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])} 4782 4783@item @emph{Arguments}: 4784@multitable @columnfractions .15 .70 4785@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)} 4786or larger, and of default kind. 4787@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)} 4788or larger, and of default kind. 4789@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)} 4790or larger, and of default kind. 4791@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}. 4792@end multitable 4793 4794@item @emph{Return value}: 4795None 4796 4797@item @emph{Example}: 4798@smallexample 4799program test_time_and_date 4800 character(8) :: date 4801 character(10) :: time 4802 character(5) :: zone 4803 integer,dimension(8) :: values 4804 ! using keyword arguments 4805 call date_and_time(date,time,zone,values) 4806 call date_and_time(DATE=date,ZONE=zone) 4807 call date_and_time(TIME=time) 4808 call date_and_time(VALUES=values) 4809 print '(a,2x,a,2x,a)', date, time, zone 4810 print '(8i5)', values 4811end program test_time_and_date 4812@end smallexample 4813 4814@item @emph{See also}: 4815@ref{CPU_TIME}, @gol 4816@ref{SYSTEM_CLOCK} 4817@end table 4818 4819 4820 4821@node DBLE 4822@section @code{DBLE} --- Double conversion function 4823@fnindex DBLE 4824@cindex conversion, to real 4825 4826@table @asis 4827@item @emph{Description}: 4828@code{DBLE(A)} Converts @var{A} to double precision real type. 4829 4830@item @emph{Standard}: 4831Fortran 77 and later 4832 4833@item @emph{Class}: 4834Elemental function 4835 4836@item @emph{Syntax}: 4837@code{RESULT = DBLE(A)} 4838 4839@item @emph{Arguments}: 4840@multitable @columnfractions .15 .70 4841@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL}, 4842or @code{COMPLEX}. 4843@end multitable 4844 4845@item @emph{Return value}: 4846The return value is of type double precision real. 4847 4848@item @emph{Example}: 4849@smallexample 4850program test_dble 4851 real :: x = 2.18 4852 integer :: i = 5 4853 complex :: z = (2.3,1.14) 4854 print *, dble(x), dble(i), dble(z) 4855end program test_dble 4856@end smallexample 4857 4858@item @emph{See also}: 4859@ref{REAL} 4860@end table 4861 4862 4863 4864@node DCMPLX 4865@section @code{DCMPLX} --- Double complex conversion function 4866@fnindex DCMPLX 4867@cindex complex numbers, conversion to 4868@cindex conversion, to complex 4869 4870@table @asis 4871@item @emph{Description}: 4872@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is 4873converted to the real component. If @var{Y} is present it is converted to the 4874imaginary component. If @var{Y} is not present then the imaginary component is 4875set to 0.0. If @var{X} is complex then @var{Y} must not be present. 4876 4877@item @emph{Standard}: 4878GNU extension 4879 4880@item @emph{Class}: 4881Elemental function 4882 4883@item @emph{Syntax}: 4884@code{RESULT = DCMPLX(X [, Y])} 4885 4886@item @emph{Arguments}: 4887@multitable @columnfractions .15 .70 4888@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 4889or @code{COMPLEX}. 4890@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be 4891@code{INTEGER} or @code{REAL}. 4892@end multitable 4893 4894@item @emph{Return value}: 4895The return value is of type @code{COMPLEX(8)} 4896 4897@item @emph{Example}: 4898@smallexample 4899program test_dcmplx 4900 integer :: i = 42 4901 real :: x = 3.14 4902 complex :: z 4903 z = cmplx(i, x) 4904 print *, dcmplx(i) 4905 print *, dcmplx(x) 4906 print *, dcmplx(z) 4907 print *, dcmplx(x,i) 4908end program test_dcmplx 4909@end smallexample 4910@end table 4911 4912 4913@node DIGITS 4914@section @code{DIGITS} --- Significant binary digits function 4915@fnindex DIGITS 4916@cindex model representation, significant digits 4917 4918@table @asis 4919@item @emph{Description}: 4920@code{DIGITS(X)} returns the number of significant binary digits of the internal 4921model representation of @var{X}. For example, on a system using a 32-bit 4922floating point representation, a default real number would likely return 24. 4923 4924@item @emph{Standard}: 4925Fortran 90 and later 4926 4927@item @emph{Class}: 4928Inquiry function 4929 4930@item @emph{Syntax}: 4931@code{RESULT = DIGITS(X)} 4932 4933@item @emph{Arguments}: 4934@multitable @columnfractions .15 .70 4935@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4936@end multitable 4937 4938@item @emph{Return value}: 4939The return value is of type @code{INTEGER}. 4940 4941@item @emph{Example}: 4942@smallexample 4943program test_digits 4944 integer :: i = 12345 4945 real :: x = 3.143 4946 real(8) :: y = 2.33 4947 print *, digits(i) 4948 print *, digits(x) 4949 print *, digits(y) 4950end program test_digits 4951@end smallexample 4952@end table 4953 4954 4955 4956@node DIM 4957@section @code{DIM} --- Positive difference 4958@fnindex DIM 4959@fnindex IDIM 4960@fnindex DDIM 4961@cindex positive difference 4962 4963@table @asis 4964@item @emph{Description}: 4965@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive; 4966otherwise returns zero. 4967 4968@item @emph{Standard}: 4969Fortran 77 and later 4970 4971@item @emph{Class}: 4972Elemental function 4973 4974@item @emph{Syntax}: 4975@code{RESULT = DIM(X, Y)} 4976 4977@item @emph{Arguments}: 4978@multitable @columnfractions .15 .70 4979@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL} 4980@item @var{Y} @tab The type shall be the same type and kind as @var{X}. (As 4981a GNU extension, arguments of different kinds are permitted.) 4982@end multitable 4983 4984@item @emph{Return value}: 4985The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU 4986extension, kind is the largest kind of the actual arguments.) 4987 4988@item @emph{Example}: 4989@smallexample 4990program test_dim 4991 integer :: i 4992 real(8) :: x 4993 i = dim(4, 15) 4994 x = dim(4.345_8, 2.111_8) 4995 print *, i 4996 print *, x 4997end program test_dim 4998@end smallexample 4999 5000@item @emph{Specific names}: 5001@multitable @columnfractions .20 .26 .20 .30 5002@headitem Name @tab Argument @tab Return type @tab Standard 5003@item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 5004@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later 5005@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 5006@end multitable 5007@end table 5008 5009 5010 5011@node DOT_PRODUCT 5012@section @code{DOT_PRODUCT} --- Dot product function 5013@fnindex DOT_PRODUCT 5014@cindex dot product 5015@cindex vector product 5016@cindex product, vector 5017 5018@table @asis 5019@item @emph{Description}: 5020@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication 5021of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be 5022either numeric or logical and must be arrays of rank one and of equal size. If 5023the vectors are @code{INTEGER} or @code{REAL}, the result is 5024@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result 5025is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL}, 5026the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}. 5027 5028@item @emph{Standard}: 5029Fortran 90 and later 5030 5031@item @emph{Class}: 5032Transformational function 5033 5034@item @emph{Syntax}: 5035@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)} 5036 5037@item @emph{Arguments}: 5038@multitable @columnfractions .15 .70 5039@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1. 5040@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. 5041@end multitable 5042 5043@item @emph{Return value}: 5044If the arguments are numeric, the return value is a scalar of numeric type, 5045@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are 5046@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}. 5047 5048@item @emph{Example}: 5049@smallexample 5050program test_dot_prod 5051 integer, dimension(3) :: a, b 5052 a = (/ 1, 2, 3 /) 5053 b = (/ 4, 5, 6 /) 5054 print '(3i3)', a 5055 print * 5056 print '(3i3)', b 5057 print * 5058 print *, dot_product(a,b) 5059end program test_dot_prod 5060@end smallexample 5061@end table 5062 5063 5064 5065@node DPROD 5066@section @code{DPROD} --- Double product function 5067@fnindex DPROD 5068@cindex product, double-precision 5069 5070@table @asis 5071@item @emph{Description}: 5072@code{DPROD(X,Y)} returns the product @code{X*Y}. 5073 5074@item @emph{Standard}: 5075Fortran 77 and later 5076 5077@item @emph{Class}: 5078Elemental function 5079 5080@item @emph{Syntax}: 5081@code{RESULT = DPROD(X, Y)} 5082 5083@item @emph{Arguments}: 5084@multitable @columnfractions .15 .70 5085@item @var{X} @tab The type shall be @code{REAL}. 5086@item @var{Y} @tab The type shall be @code{REAL}. 5087@end multitable 5088 5089@item @emph{Return value}: 5090The return value is of type @code{REAL(8)}. 5091 5092@item @emph{Example}: 5093@smallexample 5094program test_dprod 5095 real :: x = 5.2 5096 real :: y = 2.3 5097 real(8) :: d 5098 d = dprod(x,y) 5099 print *, d 5100end program test_dprod 5101@end smallexample 5102 5103@item @emph{Specific names}: 5104@multitable @columnfractions .20 .23 .20 .33 5105@headitem Name @tab Argument @tab Return type @tab Standard 5106@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 5107@end multitable 5108 5109@end table 5110 5111 5112@node DREAL 5113@section @code{DREAL} --- Double real part function 5114@fnindex DREAL 5115@cindex complex numbers, real part 5116 5117@table @asis 5118@item @emph{Description}: 5119@code{DREAL(Z)} returns the real part of complex variable @var{Z}. 5120 5121@item @emph{Standard}: 5122GNU extension 5123 5124@item @emph{Class}: 5125Elemental function 5126 5127@item @emph{Syntax}: 5128@code{RESULT = DREAL(A)} 5129 5130@item @emph{Arguments}: 5131@multitable @columnfractions .15 .70 5132@item @var{A} @tab The type shall be @code{COMPLEX(8)}. 5133@end multitable 5134 5135@item @emph{Return value}: 5136The return value is of type @code{REAL(8)}. 5137 5138@item @emph{Example}: 5139@smallexample 5140program test_dreal 5141 complex(8) :: z = (1.3_8,7.2_8) 5142 print *, dreal(z) 5143end program test_dreal 5144@end smallexample 5145 5146@item @emph{See also}: 5147@ref{AIMAG} 5148 5149@end table 5150 5151 5152 5153@node DSHIFTL 5154@section @code{DSHIFTL} --- Combined left shift 5155@fnindex DSHIFTL 5156@cindex left shift, combined 5157@cindex shift, left 5158 5159@table @asis 5160@item @emph{Description}: 5161@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5162rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT} 5163bits of @var{J}, and the remaining bits are the rightmost bits of 5164@var{I}. 5165 5166@item @emph{Standard}: 5167Fortran 2008 and later 5168 5169@item @emph{Class}: 5170Elemental function 5171 5172@item @emph{Syntax}: 5173@code{RESULT = DSHIFTL(I, J, SHIFT)} 5174 5175@item @emph{Arguments}: 5176@multitable @columnfractions .15 .70 5177@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5178@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5179If both @var{I} and @var{J} have integer type, then they shall have 5180the same kind type parameter. @var{I} and @var{J} shall not both be 5181BOZ constants. 5182@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5183be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5184shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5185@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5186@end multitable 5187 5188@item @emph{Return value}: 5189If either @var{I} or @var{J} is a BOZ constant, it is first converted 5190as if by the intrinsic function @code{INT} to an integer type with the 5191kind type parameter of the other. 5192 5193@item @emph{See also}: 5194@ref{DSHIFTR} 5195@end table 5196 5197 5198@node DSHIFTR 5199@section @code{DSHIFTR} --- Combined right shift 5200@fnindex DSHIFTR 5201@cindex right shift, combined 5202@cindex shift, right 5203 5204@table @asis 5205@item @emph{Description}: 5206@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5207leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT} 5208bits of @var{I}, and the remaining bits are the leftmost bits of 5209@var{J}. 5210 5211@item @emph{Standard}: 5212Fortran 2008 and later 5213 5214@item @emph{Class}: 5215Elemental function 5216 5217@item @emph{Syntax}: 5218@code{RESULT = DSHIFTR(I, J, SHIFT)} 5219 5220@item @emph{Arguments}: 5221@multitable @columnfractions .15 .70 5222@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5223@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5224If both @var{I} and @var{J} have integer type, then they shall have 5225the same kind type parameter. @var{I} and @var{J} shall not both be 5226BOZ constants. 5227@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5228be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5229shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5230@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5231@end multitable 5232 5233@item @emph{Return value}: 5234If either @var{I} or @var{J} is a BOZ constant, it is first converted 5235as if by the intrinsic function @code{INT} to an integer type with the 5236kind type parameter of the other. 5237 5238@item @emph{See also}: 5239@ref{DSHIFTL} 5240@end table 5241 5242 5243@node DTIME 5244@section @code{DTIME} --- Execution time subroutine (or function) 5245@fnindex DTIME 5246@cindex time, elapsed 5247@cindex elapsed time 5248 5249@table @asis 5250@item @emph{Description}: 5251@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime 5252since the start of the process's execution in @var{TIME}. @var{VALUES} 5253returns the user and system components of this time in @code{VALUES(1)} and 5254@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + 5255VALUES(2)}. 5256 5257Subsequent invocations of @code{DTIME} return values accumulated since the 5258previous invocation. 5259 5260On some systems, the underlying timings are represented using types with 5261sufficiently small limits that overflows (wrap around) are possible, such as 526232-bit types. Therefore, the values returned by this intrinsic might be, or 5263become, negative, or numerically less than previous values, during a single 5264run of the compiled program. 5265 5266Please note, that this implementation is thread safe if used within OpenMP 5267directives, i.e., its state will be consistent while called from multiple 5268threads. However, if @code{DTIME} is called from multiple threads, the result 5269is still the time since the last invocation. This may not give the intended 5270results. If possible, use @code{CPU_TIME} instead. 5271 5272This intrinsic is provided in both subroutine and function forms; however, 5273only one form can be used in any given program unit. 5274 5275@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5276 5277@multitable @columnfractions .15 .70 5278@item @code{VALUES(1)}: @tab User time in seconds. 5279@item @code{VALUES(2)}: @tab System time in seconds. 5280@item @code{TIME}: @tab Run time since start in seconds. 5281@end multitable 5282 5283@item @emph{Standard}: 5284GNU extension 5285 5286@item @emph{Class}: 5287Subroutine, function 5288 5289@item @emph{Syntax}: 5290@multitable @columnfractions .80 5291@item @code{CALL DTIME(VALUES, TIME)}. 5292@item @code{TIME = DTIME(VALUES)}, (not recommended). 5293@end multitable 5294 5295@item @emph{Arguments}: 5296@multitable @columnfractions .15 .70 5297@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5298@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5299@end multitable 5300 5301@item @emph{Return value}: 5302Elapsed time in seconds since the last invocation or since the start of program 5303execution if not called before. 5304 5305@item @emph{Example}: 5306@smallexample 5307program test_dtime 5308 integer(8) :: i, j 5309 real, dimension(2) :: tarray 5310 real :: result 5311 call dtime(tarray, result) 5312 print *, result 5313 print *, tarray(1) 5314 print *, tarray(2) 5315 do i=1,100000000 ! Just a delay 5316 j = i * i - i 5317 end do 5318 call dtime(tarray, result) 5319 print *, result 5320 print *, tarray(1) 5321 print *, tarray(2) 5322end program test_dtime 5323@end smallexample 5324 5325@item @emph{See also}: 5326@ref{CPU_TIME} 5327 5328@end table 5329 5330 5331 5332@node EOSHIFT 5333@section @code{EOSHIFT} --- End-off shift elements of an array 5334@fnindex EOSHIFT 5335@cindex array, shift 5336 5337@table @asis 5338@item @emph{Description}: 5339@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on 5340elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is 5341omitted it is taken to be @code{1}. @var{DIM} is a scalar of type 5342@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the 5343rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of 5344@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, 5345then all complete rank one sections of @var{ARRAY} along the given dimension are 5346shifted. Elements shifted out one end of each rank one section are dropped. If 5347@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY} 5348is copied back in the other end. If @var{BOUNDARY} is not present then the 5349following are copied in depending on the type of @var{ARRAY}. 5350 5351@multitable @columnfractions .15 .80 5352@item @emph{Array Type} @tab @emph{Boundary Value} 5353@item Numeric @tab 0 of the type and kind of @var{ARRAY}. 5354@item Logical @tab @code{.FALSE.}. 5355@item Character(@var{len}) @tab @var{len} blanks. 5356@end multitable 5357 5358@item @emph{Standard}: 5359Fortran 90 and later 5360 5361@item @emph{Class}: 5362Transformational function 5363 5364@item @emph{Syntax}: 5365@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])} 5366 5367@item @emph{Arguments}: 5368@multitable @columnfractions .15 .70 5369@item @var{ARRAY} @tab May be any type, not scalar. 5370@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 5371@item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 5372@item @var{DIM} @tab The type shall be @code{INTEGER}. 5373@end multitable 5374 5375@item @emph{Return value}: 5376Returns an array of same type and rank as the @var{ARRAY} argument. 5377 5378@item @emph{Example}: 5379@smallexample 5380program test_eoshift 5381 integer, dimension(3,3) :: a 5382 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 5383 print '(3i3)', a(1,:) 5384 print '(3i3)', a(2,:) 5385 print '(3i3)', a(3,:) 5386 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) 5387 print * 5388 print '(3i3)', a(1,:) 5389 print '(3i3)', a(2,:) 5390 print '(3i3)', a(3,:) 5391end program test_eoshift 5392@end smallexample 5393@end table 5394 5395 5396 5397@node EPSILON 5398@section @code{EPSILON} --- Epsilon function 5399@fnindex EPSILON 5400@cindex model representation, epsilon 5401 5402@table @asis 5403@item @emph{Description}: 5404@code{EPSILON(X)} returns the smallest number @var{E} of the same kind 5405as @var{X} such that @math{1 + E > 1}. 5406 5407@item @emph{Standard}: 5408Fortran 90 and later 5409 5410@item @emph{Class}: 5411Inquiry function 5412 5413@item @emph{Syntax}: 5414@code{RESULT = EPSILON(X)} 5415 5416@item @emph{Arguments}: 5417@multitable @columnfractions .15 .70 5418@item @var{X} @tab The type shall be @code{REAL}. 5419@end multitable 5420 5421@item @emph{Return value}: 5422The return value is of same type as the argument. 5423 5424@item @emph{Example}: 5425@smallexample 5426program test_epsilon 5427 real :: x = 3.143 5428 real(8) :: y = 2.33 5429 print *, EPSILON(x) 5430 print *, EPSILON(y) 5431end program test_epsilon 5432@end smallexample 5433@end table 5434 5435 5436 5437@node ERF 5438@section @code{ERF} --- Error function 5439@fnindex ERF 5440@cindex error function 5441 5442@table @asis 5443@item @emph{Description}: 5444@code{ERF(X)} computes the error function of @var{X}. 5445 5446@item @emph{Standard}: 5447Fortran 2008 and later 5448 5449@item @emph{Class}: 5450Elemental function 5451 5452@item @emph{Syntax}: 5453@code{RESULT = ERF(X)} 5454 5455@item @emph{Arguments}: 5456@multitable @columnfractions .15 .70 5457@item @var{X} @tab The type shall be @code{REAL}. 5458@end multitable 5459 5460@item @emph{Return value}: 5461The return value is of type @code{REAL}, of the same kind as 5462@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }. 5463 5464@item @emph{Example}: 5465@smallexample 5466program test_erf 5467 real(8) :: x = 0.17_8 5468 x = erf(x) 5469end program test_erf 5470@end smallexample 5471 5472@item @emph{Specific names}: 5473@multitable @columnfractions .20 .23 .20 .33 5474@headitem Name @tab Argument @tab Return type @tab Standard 5475@item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5476@end multitable 5477@end table 5478 5479 5480 5481@node ERFC 5482@section @code{ERFC} --- Error function 5483@fnindex ERFC 5484@cindex error function, complementary 5485 5486@table @asis 5487@item @emph{Description}: 5488@code{ERFC(X)} computes the complementary error function of @var{X}. 5489 5490@item @emph{Standard}: 5491Fortran 2008 and later 5492 5493@item @emph{Class}: 5494Elemental function 5495 5496@item @emph{Syntax}: 5497@code{RESULT = ERFC(X)} 5498 5499@item @emph{Arguments}: 5500@multitable @columnfractions .15 .70 5501@item @var{X} @tab The type shall be @code{REAL}. 5502@end multitable 5503 5504@item @emph{Return value}: 5505The return value is of type @code{REAL} and of the same kind as @var{X}. 5506It lies in the range @math{ 0 \leq erfc (x) \leq 2 }. 5507 5508@item @emph{Example}: 5509@smallexample 5510program test_erfc 5511 real(8) :: x = 0.17_8 5512 x = erfc(x) 5513end program test_erfc 5514@end smallexample 5515 5516@item @emph{Specific names}: 5517@multitable @columnfractions .20 .23 .20 .33 5518@headitem Name @tab Argument @tab Return type @tab Standard 5519@item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5520@end multitable 5521@end table 5522 5523 5524 5525@node ERFC_SCALED 5526@section @code{ERFC_SCALED} --- Error function 5527@fnindex ERFC_SCALED 5528@cindex error function, complementary, exponentially-scaled 5529 5530@table @asis 5531@item @emph{Description}: 5532@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary 5533error function of @var{X}. 5534 5535@item @emph{Standard}: 5536Fortran 2008 and later 5537 5538@item @emph{Class}: 5539Elemental function 5540 5541@item @emph{Syntax}: 5542@code{RESULT = ERFC_SCALED(X)} 5543 5544@item @emph{Arguments}: 5545@multitable @columnfractions .15 .70 5546@item @var{X} @tab The type shall be @code{REAL}. 5547@end multitable 5548 5549@item @emph{Return value}: 5550The return value is of type @code{REAL} and of the same kind as @var{X}. 5551 5552@item @emph{Example}: 5553@smallexample 5554program test_erfc_scaled 5555 real(8) :: x = 0.17_8 5556 x = erfc_scaled(x) 5557end program test_erfc_scaled 5558@end smallexample 5559@end table 5560 5561 5562 5563@node ETIME 5564@section @code{ETIME} --- Execution time subroutine (or function) 5565@fnindex ETIME 5566@cindex time, elapsed 5567 5568@table @asis 5569@item @emph{Description}: 5570@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime 5571since the start of the process's execution in @var{TIME}. @var{VALUES} 5572returns the user and system components of this time in @code{VALUES(1)} and 5573@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. 5574 5575On some systems, the underlying timings are represented using types with 5576sufficiently small limits that overflows (wrap around) are possible, such as 557732-bit types. Therefore, the values returned by this intrinsic might be, or 5578become, negative, or numerically less than previous values, during a single 5579run of the compiled program. 5580 5581This intrinsic is provided in both subroutine and function forms; however, 5582only one form can be used in any given program unit. 5583 5584@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5585 5586@multitable @columnfractions .15 .70 5587@item @code{VALUES(1)}: @tab User time in seconds. 5588@item @code{VALUES(2)}: @tab System time in seconds. 5589@item @code{TIME}: @tab Run time since start in seconds. 5590@end multitable 5591 5592@item @emph{Standard}: 5593GNU extension 5594 5595@item @emph{Class}: 5596Subroutine, function 5597 5598@item @emph{Syntax}: 5599@multitable @columnfractions .80 5600@item @code{CALL ETIME(VALUES, TIME)}. 5601@item @code{TIME = ETIME(VALUES)}, (not recommended). 5602@end multitable 5603 5604@item @emph{Arguments}: 5605@multitable @columnfractions .15 .70 5606@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5607@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5608@end multitable 5609 5610@item @emph{Return value}: 5611Elapsed time in seconds since the start of program execution. 5612 5613@item @emph{Example}: 5614@smallexample 5615program test_etime 5616 integer(8) :: i, j 5617 real, dimension(2) :: tarray 5618 real :: result 5619 call ETIME(tarray, result) 5620 print *, result 5621 print *, tarray(1) 5622 print *, tarray(2) 5623 do i=1,100000000 ! Just a delay 5624 j = i * i - i 5625 end do 5626 call ETIME(tarray, result) 5627 print *, result 5628 print *, tarray(1) 5629 print *, tarray(2) 5630end program test_etime 5631@end smallexample 5632 5633@item @emph{See also}: 5634@ref{CPU_TIME} 5635 5636@end table 5637 5638 5639 5640@node EVENT_QUERY 5641@section @code{EVENT_QUERY} --- Query whether a coarray event has occurred 5642@fnindex EVENT_QUERY 5643@cindex Events, EVENT_QUERY 5644 5645@table @asis 5646@item @emph{Description}: 5647@code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been 5648posted to the @var{EVENT} variable and not yet been removed by calling 5649@code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful, 5650it is assigned the value 0. If it is present and the invocation has failed, 5651it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}. 5652 5653@item @emph{Standard}: 5654TS 18508 or later 5655 5656@item @emph{Class}: 5657 subroutine 5658 5659@item @emph{Syntax}: 5660@code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])} 5661 5662@item @emph{Arguments}: 5663@multitable @columnfractions .15 .70 5664@item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE}, 5665defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed. 5666@item @var{COUNT} @tab (intent(out))Scalar integer with at least the 5667precision of default integer. 5668@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 5669@end multitable 5670 5671@item @emph{Example}: 5672@smallexample 5673program atomic 5674 use iso_fortran_env 5675 implicit none 5676 type(event_type) :: event_value_has_been_set[*] 5677 integer :: cnt 5678 if (this_image() == 1) then 5679 call event_query (event_value_has_been_set, cnt) 5680 if (cnt > 0) write(*,*) "Value has been set" 5681 elseif (this_image() == 2) then 5682 event post (event_value_has_been_set[1]) 5683 end if 5684end program atomic 5685@end smallexample 5686 5687@end table 5688 5689 5690 5691@node EXECUTE_COMMAND_LINE 5692@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command 5693@fnindex EXECUTE_COMMAND_LINE 5694@cindex system, system call 5695@cindex command line 5696 5697@table @asis 5698@item @emph{Description}: 5699@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or 5700asynchronously. 5701 5702The @code{COMMAND} argument is passed to the shell and executed (The 5703shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.). 5704If @code{WAIT} is present and has the value false, the execution of 5705the command is asynchronous if the system supports it; otherwise, the 5706command is executed synchronously using the C library's @code{system} 5707call. 5708 5709The three last arguments allow the user to get status information. After 5710synchronous execution, @code{EXITSTAT} contains the integer exit code of 5711the command, as returned by @code{system}. @code{CMDSTAT} is set to zero 5712if the command line was executed (whatever its exit status was). 5713@code{CMDMSG} is assigned an error message if an error has occurred. 5714 5715Note that the @code{system} function need not be thread-safe. It is 5716the responsibility of the user to ensure that @code{system} is not 5717called concurrently. 5718 5719For asynchronous execution on supported targets, the POSIX 5720@code{posix_spawn} or @code{fork} functions are used. Also, a signal 5721handler for the @code{SIGCHLD} signal is installed. 5722 5723@item @emph{Standard}: 5724Fortran 2008 and later 5725 5726@item @emph{Class}: 5727Subroutine 5728 5729@item @emph{Syntax}: 5730@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])} 5731 5732@item @emph{Arguments}: 5733@multitable @columnfractions .15 .70 5734@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar. 5735@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar. 5736@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5737default kind. 5738@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5739default kind. 5740@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the 5741default kind. 5742@end multitable 5743 5744@item @emph{Example}: 5745@smallexample 5746program test_exec 5747 integer :: i 5748 5749 call execute_command_line ("external_prog.exe", exitstat=i) 5750 print *, "Exit status of external_prog.exe was ", i 5751 5752 call execute_command_line ("reindex_files.exe", wait=.false.) 5753 print *, "Now reindexing files in the background" 5754 5755end program test_exec 5756@end smallexample 5757 5758 5759@item @emph{Note}: 5760 5761Because this intrinsic is implemented in terms of the @code{system} 5762function call, its behavior with respect to signaling is processor 5763dependent. In particular, on POSIX-compliant systems, the SIGINT and 5764SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As 5765such, if the parent process is terminated, the child process might not be 5766terminated alongside. 5767 5768 5769@item @emph{See also}: 5770@ref{SYSTEM} 5771@end table 5772 5773 5774 5775@node EXIT 5776@section @code{EXIT} --- Exit the program with status. 5777@fnindex EXIT 5778@cindex program termination 5779@cindex terminate program 5780 5781@table @asis 5782@item @emph{Description}: 5783@code{EXIT} causes immediate termination of the program with status. If status 5784is omitted it returns the canonical @emph{success} for the system. All Fortran 5785I/O units are closed. 5786 5787@item @emph{Standard}: 5788GNU extension 5789 5790@item @emph{Class}: 5791Subroutine 5792 5793@item @emph{Syntax}: 5794@code{CALL EXIT([STATUS])} 5795 5796@item @emph{Arguments}: 5797@multitable @columnfractions .15 .70 5798@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind. 5799@end multitable 5800 5801@item @emph{Return value}: 5802@code{STATUS} is passed to the parent process on exit. 5803 5804@item @emph{Example}: 5805@smallexample 5806program test_exit 5807 integer :: STATUS = 0 5808 print *, 'This program is going to exit.' 5809 call EXIT(STATUS) 5810end program test_exit 5811@end smallexample 5812 5813@item @emph{See also}: 5814@ref{ABORT}, @gol 5815@ref{KILL} 5816@end table 5817 5818 5819 5820@node EXP 5821@section @code{EXP} --- Exponential function 5822@fnindex EXP 5823@fnindex DEXP 5824@fnindex CEXP 5825@fnindex ZEXP 5826@fnindex CDEXP 5827@cindex exponential function 5828@cindex logarithm function, inverse 5829 5830@table @asis 5831@item @emph{Description}: 5832@code{EXP(X)} computes the base @math{e} exponential of @var{X}. 5833 5834@item @emph{Standard}: 5835Fortran 77 and later, has overloads that are GNU extensions 5836 5837@item @emph{Class}: 5838Elemental function 5839 5840@item @emph{Syntax}: 5841@code{RESULT = EXP(X)} 5842 5843@item @emph{Arguments}: 5844@multitable @columnfractions .15 .70 5845@item @var{X} @tab The type shall be @code{REAL} or 5846@code{COMPLEX}. 5847@end multitable 5848 5849@item @emph{Return value}: 5850The return value has same type and kind as @var{X}. 5851 5852@item @emph{Example}: 5853@smallexample 5854program test_exp 5855 real :: x = 1.0 5856 x = exp(x) 5857end program test_exp 5858@end smallexample 5859 5860@item @emph{Specific names}: 5861@multitable @columnfractions .20 .23 .20 .33 5862@headitem Name @tab Argument @tab Return type @tab Standard 5863@item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 5864@item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 5865@item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 5866@item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5867@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5868@end multitable 5869@end table 5870 5871 5872 5873@node EXPONENT 5874@section @code{EXPONENT} --- Exponent function 5875@fnindex EXPONENT 5876@cindex real number, exponent 5877@cindex floating point, exponent 5878 5879@table @asis 5880@item @emph{Description}: 5881@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X} 5882is zero the value returned is zero. 5883 5884@item @emph{Standard}: 5885Fortran 90 and later 5886 5887@item @emph{Class}: 5888Elemental function 5889 5890@item @emph{Syntax}: 5891@code{RESULT = EXPONENT(X)} 5892 5893@item @emph{Arguments}: 5894@multitable @columnfractions .15 .70 5895@item @var{X} @tab The type shall be @code{REAL}. 5896@end multitable 5897 5898@item @emph{Return value}: 5899The return value is of type default @code{INTEGER}. 5900 5901@item @emph{Example}: 5902@smallexample 5903program test_exponent 5904 real :: x = 1.0 5905 integer :: i 5906 i = exponent(x) 5907 print *, i 5908 print *, exponent(0.0) 5909end program test_exponent 5910@end smallexample 5911@end table 5912 5913 5914 5915@node EXTENDS_TYPE_OF 5916@section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension 5917@fnindex EXTENDS_TYPE_OF 5918 5919@table @asis 5920@item @emph{Description}: 5921Query dynamic type for extension. 5922 5923@item @emph{Standard}: 5924Fortran 2003 and later 5925 5926@item @emph{Class}: 5927Inquiry function 5928 5929@item @emph{Syntax}: 5930@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)} 5931 5932@item @emph{Arguments}: 5933@multitable @columnfractions .15 .70 5934@item @var{A} @tab Shall be an object of extensible declared type or 5935unlimited polymorphic. 5936@item @var{MOLD} @tab Shall be an object of extensible declared type or 5937unlimited polymorphic. 5938@end multitable 5939 5940@item @emph{Return value}: 5941The return value is a scalar of type default logical. It is true if and only if 5942the dynamic type of A is an extension type of the dynamic type of MOLD. 5943 5944 5945@item @emph{See also}: 5946@ref{SAME_TYPE_AS} 5947@end table 5948 5949 5950 5951@node FDATE 5952@section @code{FDATE} --- Get the current time as a string 5953@fnindex FDATE 5954@cindex time, current 5955@cindex current time 5956@cindex date, current 5957@cindex current date 5958 5959@table @asis 5960@item @emph{Description}: 5961@code{FDATE(DATE)} returns the current date (using the same format as 5962@ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE, 5963TIME())}. 5964 5965This intrinsic is provided in both subroutine and function forms; however, 5966only one form can be used in any given program unit. 5967 5968@item @emph{Standard}: 5969GNU extension 5970 5971@item @emph{Class}: 5972Subroutine, function 5973 5974@item @emph{Syntax}: 5975@multitable @columnfractions .80 5976@item @code{CALL FDATE(DATE)}. 5977@item @code{DATE = FDATE()}. 5978@end multitable 5979 5980@item @emph{Arguments}: 5981@multitable @columnfractions .15 .70 5982@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the 5983default kind. It is an @code{INTENT(OUT)} argument. If the length of 5984this variable is too short for the date and time string to fit 5985completely, it will be blank on procedure return. 5986@end multitable 5987 5988@item @emph{Return value}: 5989The current date and time as a string. 5990 5991@item @emph{Example}: 5992@smallexample 5993program test_fdate 5994 integer(8) :: i, j 5995 character(len=30) :: date 5996 call fdate(date) 5997 print *, 'Program started on ', date 5998 do i = 1, 100000000 ! Just a delay 5999 j = i * i - i 6000 end do 6001 call fdate(date) 6002 print *, 'Program ended on ', date 6003end program test_fdate 6004@end smallexample 6005 6006@item @emph{See also}: 6007@ref{DATE_AND_TIME}, @gol 6008@ref{CTIME} 6009@end table 6010 6011 6012@node FGET 6013@section @code{FGET} --- Read a single character in stream mode from stdin 6014@fnindex FGET 6015@cindex read character, stream mode 6016@cindex stream mode, read character 6017@cindex file operation, read character 6018 6019@table @asis 6020@item @emph{Description}: 6021Read a single character in stream mode from stdin by bypassing normal 6022formatted output. Stream I/O should not be mixed with normal record-oriented 6023(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6024 6025This intrinsic is provided in both subroutine and function forms; however, 6026only one form can be used in any given program unit. 6027 6028Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6029@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6030Programmers should consider the use of new stream IO feature in new code 6031for future portability. See also @ref{Fortran 2003 status}. 6032 6033@item @emph{Standard}: 6034GNU extension 6035 6036@item @emph{Class}: 6037Subroutine, function 6038 6039@item @emph{Syntax}: 6040@multitable @columnfractions .80 6041@item @code{CALL FGET(C [, STATUS])} 6042@item @code{STATUS = FGET(C)} 6043@end multitable 6044 6045@item @emph{Arguments}: 6046@multitable @columnfractions .15 .70 6047@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6048kind. 6049@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6050Returns 0 on success, -1 on end-of-file, and a system specific positive 6051error code otherwise. 6052@end multitable 6053 6054@item @emph{Example}: 6055@smallexample 6056PROGRAM test_fget 6057 INTEGER, PARAMETER :: strlen = 100 6058 INTEGER :: status, i = 1 6059 CHARACTER(len=strlen) :: str = "" 6060 6061 WRITE (*,*) 'Enter text:' 6062 DO 6063 CALL fget(str(i:i), status) 6064 if (status /= 0 .OR. i > strlen) exit 6065 i = i + 1 6066 END DO 6067 WRITE (*,*) TRIM(str) 6068END PROGRAM 6069@end smallexample 6070 6071@item @emph{See also}: 6072@ref{FGETC}, @gol 6073@ref{FPUT}, @gol 6074@ref{FPUTC} 6075@end table 6076 6077 6078 6079@node FGETC 6080@section @code{FGETC} --- Read a single character in stream mode 6081@fnindex FGETC 6082@cindex read character, stream mode 6083@cindex stream mode, read character 6084@cindex file operation, read character 6085 6086@table @asis 6087@item @emph{Description}: 6088Read a single character in stream mode by bypassing normal formatted output. 6089Stream I/O should not be mixed with normal record-oriented (formatted or 6090unformatted) I/O on the same unit; the results are unpredictable. 6091 6092This intrinsic is provided in both subroutine and function forms; however, 6093only one form can be used in any given program unit. 6094 6095Note that the @code{FGET} intrinsic is provided for backwards compatibility 6096with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6097Programmers should consider the use of new stream IO feature in new code 6098for future portability. See also @ref{Fortran 2003 status}. 6099 6100@item @emph{Standard}: 6101GNU extension 6102 6103@item @emph{Class}: 6104Subroutine, function 6105 6106@item @emph{Syntax}: 6107@multitable @columnfractions .80 6108@item @code{CALL FGETC(UNIT, C [, STATUS])} 6109@item @code{STATUS = FGETC(UNIT, C)} 6110@end multitable 6111 6112@item @emph{Arguments}: 6113@multitable @columnfractions .15 .70 6114@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6115@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6116kind. 6117@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6118Returns 0 on success, -1 on end-of-file and a system specific positive 6119error code otherwise. 6120@end multitable 6121 6122@item @emph{Example}: 6123@smallexample 6124PROGRAM test_fgetc 6125 INTEGER :: fd = 42, status 6126 CHARACTER :: c 6127 6128 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD") 6129 DO 6130 CALL fgetc(fd, c, status) 6131 IF (status /= 0) EXIT 6132 call fput(c) 6133 END DO 6134 CLOSE(UNIT=fd) 6135END PROGRAM 6136@end smallexample 6137 6138@item @emph{See also}: 6139@ref{FGET}, @gol 6140@ref{FPUT}, @gol 6141@ref{FPUTC} 6142@end table 6143 6144@node FINDLOC 6145@section @code{FINDLOC} --- Search an array for a value 6146@fnindex FINDLOC 6147@cindex findloc 6148 6149@table @asis 6150@item @emph{Description}: 6151Determines the location of the element in the array with the value 6152given in the @var{VALUE} argument, or, if the @var{DIM} argument is 6153supplied, determines the locations of the elements equal to the 6154@var{VALUE} argument element along each 6155row of the array in the @var{DIM} direction. If @var{MASK} is 6156present, only the elements for which @var{MASK} is @code{.TRUE.} are 6157considered. If more than one element in the array has the value 6158@var{VALUE}, the location returned is that of the first such element 6159in array element order if the @var{BACK} is not present or if it is 6160@code{.FALSE.}. If @var{BACK} is true, the location returned is that 6161of the last such element. If the array has zero size, or all of the 6162elements of @var{MASK} are @code{.FALSE.}, then the result is an array 6163of zeroes. Similarly, if @var{DIM} is supplied and all of the 6164elements of @var{MASK} along a given row are zero, the result value 6165for that row is zero. 6166 6167@item @emph{Standard}: 6168Fortran 2008 and later. 6169 6170@item @emph{Class}: 6171Transformational function 6172 6173@item @emph{Syntax}: 6174@multitable @columnfractions .80 6175@item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])} 6176@item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])} 6177@end multitable 6178 6179@item @emph{Arguments}: 6180@multitable @columnfractions .15 .70 6181@item @var{ARRAY} @tab Shall be an array of intrinsic type. 6182@item @var{VALUE} @tab A scalar of intrinsic type which is in type 6183conformance with @var{ARRAY}. 6184@item @var{DIM} @tab (Optional) Shall be a scalar of type 6185@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 6186inclusive. It may not be an optional dummy argument. 6187@item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL}, 6188and conformable with @var{ARRAY}. 6189@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6190expression indicating the kind parameter of the result. 6191@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 6192@end multitable 6193 6194@item @emph{Return value}: 6195If @var{DIM} is absent, the result is a rank-one array with a length 6196equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 6197is an array with a rank one less than the rank of @var{ARRAY}, and a 6198size corresponding to the size of @var{ARRAY} with the @var{DIM} 6199dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 6200of one, the result is a scalar. If the optional argument @var{KIND} 6201is present, the result is an integer of kind @var{KIND}, otherwise it 6202is of default kind. 6203 6204@item @emph{See also}: 6205@ref{MAXLOC}, @gol 6206@ref{MINLOC} 6207 6208@end table 6209 6210@node FLOOR 6211@section @code{FLOOR} --- Integer floor function 6212@fnindex FLOOR 6213@cindex floor 6214@cindex rounding, floor 6215 6216@table @asis 6217@item @emph{Description}: 6218@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}. 6219 6220@item @emph{Standard}: 6221Fortran 95 and later 6222 6223@item @emph{Class}: 6224Elemental function 6225 6226@item @emph{Syntax}: 6227@code{RESULT = FLOOR(A [, KIND])} 6228 6229@item @emph{Arguments}: 6230@multitable @columnfractions .15 .70 6231@item @var{A} @tab The type shall be @code{REAL}. 6232@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6233expression indicating the kind parameter of the result. 6234@end multitable 6235 6236@item @emph{Return value}: 6237The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 6238and of default-kind @code{INTEGER} otherwise. 6239 6240@item @emph{Example}: 6241@smallexample 6242program test_floor 6243 real :: x = 63.29 6244 real :: y = -63.59 6245 print *, floor(x) ! returns 63 6246 print *, floor(y) ! returns -64 6247end program test_floor 6248@end smallexample 6249 6250@item @emph{See also}: 6251@ref{CEILING}, @gol 6252@ref{NINT} 6253@end table 6254 6255 6256 6257@node FLUSH 6258@section @code{FLUSH} --- Flush I/O unit(s) 6259@fnindex FLUSH 6260@cindex file operation, flush 6261 6262@table @asis 6263@item @emph{Description}: 6264Flushes Fortran unit(s) currently open for output. Without the optional 6265argument, all units are flushed, otherwise just the unit specified. 6266 6267@item @emph{Standard}: 6268GNU extension 6269 6270@item @emph{Class}: 6271Subroutine 6272 6273@item @emph{Syntax}: 6274@code{CALL FLUSH(UNIT)} 6275 6276@item @emph{Arguments}: 6277@multitable @columnfractions .15 .70 6278@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}. 6279@end multitable 6280 6281@item @emph{Note}: 6282Beginning with the Fortran 2003 standard, there is a @code{FLUSH} 6283statement that should be preferred over the @code{FLUSH} intrinsic. 6284 6285The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement 6286have identical effect: they flush the runtime library's I/O buffer so 6287that the data becomes visible to other processes. This does not guarantee 6288that the data is committed to disk. 6289 6290On POSIX systems, you can request that all data is transferred to the 6291storage device by calling the @code{fsync} function, with the POSIX file 6292descriptor of the I/O unit as argument (retrieved with GNU intrinsic 6293@code{FNUM}). The following example shows how: 6294 6295@smallexample 6296 ! Declare the interface for POSIX fsync function 6297 interface 6298 function fsync (fd) bind(c,name="fsync") 6299 use iso_c_binding, only: c_int 6300 integer(c_int), value :: fd 6301 integer(c_int) :: fsync 6302 end function fsync 6303 end interface 6304 6305 ! Variable declaration 6306 integer :: ret 6307 6308 ! Opening unit 10 6309 open (10,file="foo") 6310 6311 ! ... 6312 ! Perform I/O on unit 10 6313 ! ... 6314 6315 ! Flush and sync 6316 flush(10) 6317 ret = fsync(fnum(10)) 6318 6319 ! Handle possible error 6320 if (ret /= 0) stop "Error calling FSYNC" 6321@end smallexample 6322 6323@end table 6324 6325 6326 6327@node FNUM 6328@section @code{FNUM} --- File number function 6329@fnindex FNUM 6330@cindex file operation, file number 6331 6332@table @asis 6333@item @emph{Description}: 6334@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the 6335open Fortran I/O unit @code{UNIT}. 6336 6337@item @emph{Standard}: 6338GNU extension 6339 6340@item @emph{Class}: 6341Function 6342 6343@item @emph{Syntax}: 6344@code{RESULT = FNUM(UNIT)} 6345 6346@item @emph{Arguments}: 6347@multitable @columnfractions .15 .70 6348@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6349@end multitable 6350 6351@item @emph{Return value}: 6352The return value is of type @code{INTEGER} 6353 6354@item @emph{Example}: 6355@smallexample 6356program test_fnum 6357 integer :: i 6358 open (unit=10, status = "scratch") 6359 i = fnum(10) 6360 print *, i 6361 close (10) 6362end program test_fnum 6363@end smallexample 6364@end table 6365 6366 6367 6368@node FPUT 6369@section @code{FPUT} --- Write a single character in stream mode to stdout 6370@fnindex FPUT 6371@cindex write character, stream mode 6372@cindex stream mode, write character 6373@cindex file operation, write character 6374 6375@table @asis 6376@item @emph{Description}: 6377Write a single character in stream mode to stdout by bypassing normal 6378formatted output. Stream I/O should not be mixed with normal record-oriented 6379(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6380 6381This intrinsic is provided in both subroutine and function forms; however, 6382only one form can be used in any given program unit. 6383 6384Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6385@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6386Programmers should consider the use of new stream IO feature in new code 6387for future portability. See also @ref{Fortran 2003 status}. 6388 6389@item @emph{Standard}: 6390GNU extension 6391 6392@item @emph{Class}: 6393Subroutine, function 6394 6395@item @emph{Syntax}: 6396@multitable @columnfractions .80 6397@item @code{CALL FPUT(C [, STATUS])} 6398@item @code{STATUS = FPUT(C)} 6399@end multitable 6400 6401@item @emph{Arguments}: 6402@multitable @columnfractions .15 .70 6403@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6404kind. 6405@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6406Returns 0 on success, -1 on end-of-file and a system specific positive 6407error code otherwise. 6408@end multitable 6409 6410@item @emph{Example}: 6411@smallexample 6412PROGRAM test_fput 6413 CHARACTER(len=10) :: str = "gfortran" 6414 INTEGER :: i 6415 DO i = 1, len_trim(str) 6416 CALL fput(str(i:i)) 6417 END DO 6418END PROGRAM 6419@end smallexample 6420 6421@item @emph{See also}: 6422@ref{FPUTC}, @gol 6423@ref{FGET}, @gol 6424@ref{FGETC} 6425@end table 6426 6427 6428 6429@node FPUTC 6430@section @code{FPUTC} --- Write a single character in stream mode 6431@fnindex FPUTC 6432@cindex write character, stream mode 6433@cindex stream mode, write character 6434@cindex file operation, write character 6435 6436@table @asis 6437@item @emph{Description}: 6438Write a single character in stream mode by bypassing normal formatted 6439output. Stream I/O should not be mixed with normal record-oriented 6440(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6441 6442This intrinsic is provided in both subroutine and function forms; however, 6443only one form can be used in any given program unit. 6444 6445Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6446@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6447Programmers should consider the use of new stream IO feature in new code 6448for future portability. See also @ref{Fortran 2003 status}. 6449 6450@item @emph{Standard}: 6451GNU extension 6452 6453@item @emph{Class}: 6454Subroutine, function 6455 6456@item @emph{Syntax}: 6457@multitable @columnfractions .80 6458@item @code{CALL FPUTC(UNIT, C [, STATUS])} 6459@item @code{STATUS = FPUTC(UNIT, C)} 6460@end multitable 6461 6462@item @emph{Arguments}: 6463@multitable @columnfractions .15 .70 6464@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6465@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6466kind. 6467@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6468Returns 0 on success, -1 on end-of-file and a system specific positive 6469error code otherwise. 6470@end multitable 6471 6472@item @emph{Example}: 6473@smallexample 6474PROGRAM test_fputc 6475 CHARACTER(len=10) :: str = "gfortran" 6476 INTEGER :: fd = 42, i 6477 6478 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW") 6479 DO i = 1, len_trim(str) 6480 CALL fputc(fd, str(i:i)) 6481 END DO 6482 CLOSE(fd) 6483END PROGRAM 6484@end smallexample 6485 6486@item @emph{See also}: 6487@ref{FPUT}, @gol 6488@ref{FGET}, @gol 6489@ref{FGETC} 6490@end table 6491 6492 6493 6494@node FRACTION 6495@section @code{FRACTION} --- Fractional part of the model representation 6496@fnindex FRACTION 6497@cindex real number, fraction 6498@cindex floating point, fraction 6499 6500@table @asis 6501@item @emph{Description}: 6502@code{FRACTION(X)} returns the fractional part of the model 6503representation of @code{X}. 6504 6505@item @emph{Standard}: 6506Fortran 90 and later 6507 6508@item @emph{Class}: 6509Elemental function 6510 6511@item @emph{Syntax}: 6512@code{Y = FRACTION(X)} 6513 6514@item @emph{Arguments}: 6515@multitable @columnfractions .15 .70 6516@item @var{X} @tab The type of the argument shall be a @code{REAL}. 6517@end multitable 6518 6519@item @emph{Return value}: 6520The return value is of the same type and kind as the argument. 6521The fractional part of the model representation of @code{X} is returned; 6522it is @code{X * RADIX(X)**(-EXPONENT(X))}. 6523 6524@item @emph{Example}: 6525@smallexample 6526program test_fraction 6527 real :: x 6528 x = 178.1387e-4 6529 print *, fraction(x), x * radix(x)**(-exponent(x)) 6530end program test_fraction 6531@end smallexample 6532 6533@end table 6534 6535 6536 6537@node FREE 6538@section @code{FREE} --- Frees memory 6539@fnindex FREE 6540@cindex pointer, cray 6541 6542@table @asis 6543@item @emph{Description}: 6544Frees memory previously allocated by @code{MALLOC}. The @code{FREE} 6545intrinsic is an extension intended to be used with Cray pointers, and is 6546provided in GNU Fortran to allow user to compile legacy code. For 6547new code using Fortran 95 pointers, the memory de-allocation intrinsic is 6548@code{DEALLOCATE}. 6549 6550@item @emph{Standard}: 6551GNU extension 6552 6553@item @emph{Class}: 6554Subroutine 6555 6556@item @emph{Syntax}: 6557@code{CALL FREE(PTR)} 6558 6559@item @emph{Arguments}: 6560@multitable @columnfractions .15 .70 6561@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the 6562location of the memory that should be de-allocated. 6563@end multitable 6564 6565@item @emph{Return value}: 6566None 6567 6568@item @emph{Example}: 6569See @code{MALLOC} for an example. 6570 6571@item @emph{See also}: 6572@ref{MALLOC} 6573@end table 6574 6575 6576 6577@node FSEEK 6578@section @code{FSEEK} --- Low level file positioning subroutine 6579@fnindex FSEEK 6580@cindex file operation, seek 6581@cindex file operation, position 6582 6583@table @asis 6584@item @emph{Description}: 6585Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} 6586is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET}, 6587if set to 1, @var{OFFSET} is taken to be relative to the current position 6588@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}. 6589On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek 6590fails silently. 6591 6592This intrinsic routine is not fully backwards compatible with @command{g77}. 6593In @command{g77}, the @code{FSEEK} takes a statement label instead of a 6594@var{STATUS} variable. If FSEEK is used in old code, change 6595@smallexample 6596 CALL FSEEK(UNIT, OFFSET, WHENCE, *label) 6597@end smallexample 6598to 6599@smallexample 6600 INTEGER :: status 6601 CALL FSEEK(UNIT, OFFSET, WHENCE, status) 6602 IF (status /= 0) GOTO label 6603@end smallexample 6604 6605Please note that GNU Fortran provides the Fortran 2003 Stream facility. 6606Programmers should consider the use of new stream IO feature in new code 6607for future portability. See also @ref{Fortran 2003 status}. 6608 6609@item @emph{Standard}: 6610GNU extension 6611 6612@item @emph{Class}: 6613Subroutine 6614 6615@item @emph{Syntax}: 6616@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])} 6617 6618@item @emph{Arguments}: 6619@multitable @columnfractions .15 .70 6620@item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}. 6621@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}. 6622@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}. 6623Its value shall be either 0, 1 or 2. 6624@item @var{STATUS} @tab (Optional) shall be a scalar of type 6625@code{INTEGER(4)}. 6626@end multitable 6627 6628@item @emph{Example}: 6629@smallexample 6630PROGRAM test_fseek 6631 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2 6632 INTEGER :: fd, offset, ierr 6633 6634 ierr = 0 6635 offset = 5 6636 fd = 10 6637 6638 OPEN(UNIT=fd, FILE="fseek.test") 6639 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET 6640 print *, FTELL(fd), ierr 6641 6642 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end 6643 print *, FTELL(fd), ierr 6644 6645 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning 6646 print *, FTELL(fd), ierr 6647 6648 CLOSE(UNIT=fd) 6649END PROGRAM 6650@end smallexample 6651 6652@item @emph{See also}: 6653@ref{FTELL} 6654@end table 6655 6656 6657 6658@node FSTAT 6659@section @code{FSTAT} --- Get file status 6660@fnindex FSTAT 6661@cindex file system, file status 6662 6663@table @asis 6664@item @emph{Description}: 6665@code{FSTAT} is identical to @ref{STAT}, except that information about an 6666already opened file is obtained. 6667 6668The elements in @code{VALUES} are the same as described by @ref{STAT}. 6669 6670This intrinsic is provided in both subroutine and function forms; however, 6671only one form can be used in any given program unit. 6672 6673@item @emph{Standard}: 6674GNU extension 6675 6676@item @emph{Class}: 6677Subroutine, function 6678 6679@item @emph{Syntax}: 6680@multitable @columnfractions .80 6681@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])} 6682@item @code{STATUS = FSTAT(UNIT, VALUES)} 6683@end multitable 6684 6685@item @emph{Arguments}: 6686@multitable @columnfractions .15 .70 6687@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. 6688@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 6689@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 6690on success and a system specific error code otherwise. 6691@end multitable 6692 6693@item @emph{Example}: 6694See @ref{STAT} for an example. 6695 6696@item @emph{See also}: 6697To stat a link: @gol 6698@ref{LSTAT} @gol 6699To stat a file: @gol 6700@ref{STAT} 6701@end table 6702 6703 6704 6705@node FTELL 6706@section @code{FTELL} --- Current stream position 6707@fnindex FTELL 6708@cindex file operation, position 6709 6710@table @asis 6711@item @emph{Description}: 6712Retrieves the current position within an open file. 6713 6714This intrinsic is provided in both subroutine and function forms; however, 6715only one form can be used in any given program unit. 6716 6717@item @emph{Standard}: 6718GNU extension 6719 6720@item @emph{Class}: 6721Subroutine, function 6722 6723@item @emph{Syntax}: 6724@multitable @columnfractions .80 6725@item @code{CALL FTELL(UNIT, OFFSET)} 6726@item @code{OFFSET = FTELL(UNIT)} 6727@end multitable 6728 6729@item @emph{Arguments}: 6730@multitable @columnfractions .15 .70 6731@item @var{OFFSET} @tab Shall of type @code{INTEGER}. 6732@item @var{UNIT} @tab Shall of type @code{INTEGER}. 6733@end multitable 6734 6735@item @emph{Return value}: 6736In either syntax, @var{OFFSET} is set to the current offset of unit 6737number @var{UNIT}, or to @math{-1} if the unit is not currently open. 6738 6739@item @emph{Example}: 6740@smallexample 6741PROGRAM test_ftell 6742 INTEGER :: i 6743 OPEN(10, FILE="temp.dat") 6744 CALL ftell(10,i) 6745 WRITE(*,*) i 6746END PROGRAM 6747@end smallexample 6748 6749@item @emph{See also}: 6750@ref{FSEEK} 6751@end table 6752 6753 6754 6755@node GAMMA 6756@section @code{GAMMA} --- Gamma function 6757@fnindex GAMMA 6758@fnindex DGAMMA 6759@cindex Gamma function 6760@cindex Factorial function 6761 6762@table @asis 6763@item @emph{Description}: 6764@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive, 6765integer values of @var{X} the Gamma function simplifies to the factorial 6766function @math{\Gamma(x)=(x-1)!}. 6767 6768@tex 6769$$ 6770\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t 6771$$ 6772@end tex 6773 6774@item @emph{Standard}: 6775Fortran 2008 and later 6776 6777@item @emph{Class}: 6778Elemental function 6779 6780@item @emph{Syntax}: 6781@code{X = GAMMA(X)} 6782 6783@item @emph{Arguments}: 6784@multitable @columnfractions .15 .70 6785@item @var{X} @tab Shall be of type @code{REAL} and neither zero 6786nor a negative integer. 6787@end multitable 6788 6789@item @emph{Return value}: 6790The return value is of type @code{REAL} of the same kind as @var{X}. 6791 6792@item @emph{Example}: 6793@smallexample 6794program test_gamma 6795 real :: x = 1.0 6796 x = gamma(x) ! returns 1.0 6797end program test_gamma 6798@end smallexample 6799 6800@item @emph{Specific names}: 6801@multitable @columnfractions .20 .23 .20 .33 6802@headitem Name @tab Argument @tab Return type @tab Standard 6803@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 6804@end multitable 6805 6806@item @emph{See also}: 6807Logarithm of the Gamma function: @gol 6808@ref{LOG_GAMMA} 6809@end table 6810 6811 6812 6813@node GERROR 6814@section @code{GERROR} --- Get last system error message 6815@fnindex GERROR 6816@cindex system, error handling 6817 6818@table @asis 6819@item @emph{Description}: 6820Returns the system error message corresponding to the last system error. 6821This resembles the functionality of @code{strerror(3)} in C. 6822 6823@item @emph{Standard}: 6824GNU extension 6825 6826@item @emph{Class}: 6827Subroutine 6828 6829@item @emph{Syntax}: 6830@code{CALL GERROR(RESULT)} 6831 6832@item @emph{Arguments}: 6833@multitable @columnfractions .15 .70 6834@item @var{RESULT} @tab Shall be of type @code{CHARACTER} and of default kind. 6835@end multitable 6836 6837@item @emph{Example}: 6838@smallexample 6839PROGRAM test_gerror 6840 CHARACTER(len=100) :: msg 6841 CALL gerror(msg) 6842 WRITE(*,*) msg 6843END PROGRAM 6844@end smallexample 6845 6846@item @emph{See also}: 6847@ref{IERRNO}, @gol 6848@ref{PERROR} 6849@end table 6850 6851 6852 6853@node GETARG 6854@section @code{GETARG} --- Get command line arguments 6855@fnindex GETARG 6856@cindex command-line arguments 6857@cindex arguments, to program 6858 6859@table @asis 6860@item @emph{Description}: 6861Retrieve the @var{POS}-th argument that was passed on the 6862command line when the containing program was invoked. 6863 6864This intrinsic routine is provided for backwards compatibility with 6865GNU Fortran 77. In new code, programmers should consider the use of 6866the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 6867standard. 6868 6869@item @emph{Standard}: 6870GNU extension 6871 6872@item @emph{Class}: 6873Subroutine 6874 6875@item @emph{Syntax}: 6876@code{CALL GETARG(POS, VALUE)} 6877 6878@item @emph{Arguments}: 6879@multitable @columnfractions .15 .70 6880@item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than 6881the default integer kind; @math{@var{POS} \geq 0} 6882@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default 6883kind. 6884@end multitable 6885 6886@item @emph{Return value}: 6887After @code{GETARG} returns, the @var{VALUE} argument holds the 6888@var{POS}th command line argument. If @var{VALUE} cannot hold the 6889argument, it is truncated to fit the length of @var{VALUE}. If there are 6890less than @var{POS} arguments specified at the command line, @var{VALUE} 6891will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set 6892to the name of the program (on systems that support this feature). 6893 6894@item @emph{Example}: 6895@smallexample 6896PROGRAM test_getarg 6897 INTEGER :: i 6898 CHARACTER(len=32) :: arg 6899 6900 DO i = 1, iargc() 6901 CALL getarg(i, arg) 6902 WRITE (*,*) arg 6903 END DO 6904END PROGRAM 6905@end smallexample 6906 6907@item @emph{See also}: 6908GNU Fortran 77 compatibility function: @gol 6909@ref{IARGC} @gol 6910Fortran 2003 functions and subroutines: @gol 6911@ref{GET_COMMAND}, @gol 6912@ref{GET_COMMAND_ARGUMENT}, @gol 6913@ref{COMMAND_ARGUMENT_COUNT} 6914@end table 6915 6916 6917 6918@node GET_COMMAND 6919@section @code{GET_COMMAND} --- Get the entire command line 6920@fnindex GET_COMMAND 6921@cindex command-line arguments 6922@cindex arguments, to program 6923 6924@table @asis 6925@item @emph{Description}: 6926Retrieve the entire command line that was used to invoke the program. 6927 6928@item @emph{Standard}: 6929Fortran 2003 and later 6930 6931@item @emph{Class}: 6932Subroutine 6933 6934@item @emph{Syntax}: 6935@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])} 6936 6937@item @emph{Arguments}: 6938@multitable @columnfractions .15 .70 6939@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and 6940of default kind. 6941@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of 6942default kind. 6943@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of 6944default kind. 6945@end multitable 6946 6947@item @emph{Return value}: 6948If @var{COMMAND} is present, stores the entire command line that was used 6949to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is 6950assigned the length of the command line. If @var{STATUS} is present, it 6951is assigned 0 upon success of the command, -1 if @var{COMMAND} is too 6952short to store the command line, or a positive value in case of an error. 6953 6954@item @emph{Example}: 6955@smallexample 6956PROGRAM test_get_command 6957 CHARACTER(len=255) :: cmd 6958 CALL get_command(cmd) 6959 WRITE (*,*) TRIM(cmd) 6960END PROGRAM 6961@end smallexample 6962 6963@item @emph{See also}: 6964@ref{GET_COMMAND_ARGUMENT}, @gol 6965@ref{COMMAND_ARGUMENT_COUNT} 6966@end table 6967 6968 6969 6970@node GET_COMMAND_ARGUMENT 6971@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments 6972@fnindex GET_COMMAND_ARGUMENT 6973@cindex command-line arguments 6974@cindex arguments, to program 6975 6976@table @asis 6977@item @emph{Description}: 6978Retrieve the @var{NUMBER}-th argument that was passed on the 6979command line when the containing program was invoked. 6980 6981@item @emph{Standard}: 6982Fortran 2003 and later 6983 6984@item @emph{Class}: 6985Subroutine 6986 6987@item @emph{Syntax}: 6988@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])} 6989 6990@item @emph{Arguments}: 6991@multitable @columnfractions .15 .70 6992@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of 6993default kind, @math{@var{NUMBER} \geq 0} 6994@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 6995and of default kind. 6996@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6997and of default kind. 6998@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6999and of default kind. 7000@end multitable 7001 7002@item @emph{Return value}: 7003After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the 7004@var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is 7005truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER} 7006arguments specified at the command line, @var{VALUE} will be filled with blanks. 7007If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on 7008systems that support this feature). The @var{LENGTH} argument contains the 7009length of the @var{NUMBER}-th command line argument. If the argument retrieval 7010fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated 7011command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is 7012zero. 7013 7014@item @emph{Example}: 7015@smallexample 7016PROGRAM test_get_command_argument 7017 INTEGER :: i 7018 CHARACTER(len=32) :: arg 7019 7020 i = 0 7021 DO 7022 CALL get_command_argument(i, arg) 7023 IF (LEN_TRIM(arg) == 0) EXIT 7024 7025 WRITE (*,*) TRIM(arg) 7026 i = i+1 7027 END DO 7028END PROGRAM 7029@end smallexample 7030 7031@item @emph{See also}: 7032@ref{GET_COMMAND}, @gol 7033@ref{COMMAND_ARGUMENT_COUNT} 7034@end table 7035 7036 7037 7038@node GETCWD 7039@section @code{GETCWD} --- Get current working directory 7040@fnindex GETCWD 7041@cindex system, working directory 7042 7043@table @asis 7044@item @emph{Description}: 7045Get current working directory. 7046 7047This intrinsic is provided in both subroutine and function forms; however, 7048only one form can be used in any given program unit. 7049 7050@item @emph{Standard}: 7051GNU extension 7052 7053@item @emph{Class}: 7054Subroutine, function 7055 7056@item @emph{Syntax}: 7057@multitable @columnfractions .80 7058@item @code{CALL GETCWD(C [, STATUS])} 7059@item @code{STATUS = GETCWD(C)} 7060@end multitable 7061 7062@item @emph{Arguments}: 7063@multitable @columnfractions .15 .70 7064@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. 7065@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, 7066a system specific and nonzero error code otherwise. 7067@end multitable 7068 7069@item @emph{Example}: 7070@smallexample 7071PROGRAM test_getcwd 7072 CHARACTER(len=255) :: cwd 7073 CALL getcwd(cwd) 7074 WRITE(*,*) TRIM(cwd) 7075END PROGRAM 7076@end smallexample 7077 7078@item @emph{See also}: 7079@ref{CHDIR} 7080@end table 7081 7082 7083 7084@node GETENV 7085@section @code{GETENV} --- Get an environmental variable 7086@fnindex GETENV 7087@cindex environment variable 7088 7089@table @asis 7090@item @emph{Description}: 7091Get the @var{VALUE} of the environmental variable @var{NAME}. 7092 7093This intrinsic routine is provided for backwards compatibility with 7094GNU Fortran 77. In new code, programmers should consider the use of 7095the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran 70962003 standard. 7097 7098Note that @code{GETENV} need not be thread-safe. It is the 7099responsibility of the user to ensure that the environment is not being 7100updated concurrently with a call to the @code{GETENV} intrinsic. 7101 7102@item @emph{Standard}: 7103GNU extension 7104 7105@item @emph{Class}: 7106Subroutine 7107 7108@item @emph{Syntax}: 7109@code{CALL GETENV(NAME, VALUE)} 7110 7111@item @emph{Arguments}: 7112@multitable @columnfractions .15 .70 7113@item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind. 7114@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. 7115@end multitable 7116 7117@item @emph{Return value}: 7118Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 7119not large enough to hold the data, it is truncated. If @var{NAME} 7120is not set, @var{VALUE} will be filled with blanks. 7121 7122@item @emph{Example}: 7123@smallexample 7124PROGRAM test_getenv 7125 CHARACTER(len=255) :: homedir 7126 CALL getenv("HOME", homedir) 7127 WRITE (*,*) TRIM(homedir) 7128END PROGRAM 7129@end smallexample 7130 7131@item @emph{See also}: 7132@ref{GET_ENVIRONMENT_VARIABLE} 7133@end table 7134 7135 7136 7137@node GET_ENVIRONMENT_VARIABLE 7138@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable 7139@fnindex GET_ENVIRONMENT_VARIABLE 7140@cindex environment variable 7141 7142@table @asis 7143@item @emph{Description}: 7144Get the @var{VALUE} of the environmental variable @var{NAME}. 7145 7146Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It 7147is the responsibility of the user to ensure that the environment is 7148not being updated concurrently with a call to the 7149@code{GET_ENVIRONMENT_VARIABLE} intrinsic. 7150 7151@item @emph{Standard}: 7152Fortran 2003 and later 7153 7154@item @emph{Class}: 7155Subroutine 7156 7157@item @emph{Syntax}: 7158@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)} 7159 7160@item @emph{Arguments}: 7161@multitable @columnfractions .15 .70 7162@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER} 7163and of default kind. 7164@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 7165and of default kind. 7166@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7167and of default kind. 7168@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7169and of default kind. 7170@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL} 7171and of default kind. 7172@end multitable 7173 7174@item @emph{Return value}: 7175Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 7176not large enough to hold the data, it is truncated. If @var{NAME} 7177is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH} 7178contains the length needed for storing the environment variable @var{NAME} 7179or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present 7180but too short for the environment variable; it is 1 if the environment 7181variable does not exist and 2 if the processor does not support environment 7182variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is 7183present with the value @code{.FALSE.}, the trailing blanks in @var{NAME} 7184are significant; otherwise they are not part of the environment variable 7185name. 7186 7187@item @emph{Example}: 7188@smallexample 7189PROGRAM test_getenv 7190 CHARACTER(len=255) :: homedir 7191 CALL get_environment_variable("HOME", homedir) 7192 WRITE (*,*) TRIM(homedir) 7193END PROGRAM 7194@end smallexample 7195@end table 7196 7197 7198 7199@node GETGID 7200@section @code{GETGID} --- Group ID function 7201@fnindex GETGID 7202@cindex system, group ID 7203 7204@table @asis 7205@item @emph{Description}: 7206Returns the numerical group ID of the current process. 7207 7208@item @emph{Standard}: 7209GNU extension 7210 7211@item @emph{Class}: 7212Function 7213 7214@item @emph{Syntax}: 7215@code{RESULT = GETGID()} 7216 7217@item @emph{Return value}: 7218The return value of @code{GETGID} is an @code{INTEGER} of the default 7219kind. 7220 7221 7222@item @emph{Example}: 7223See @code{GETPID} for an example. 7224 7225@item @emph{See also}: 7226@ref{GETPID}, @gol 7227@ref{GETUID} 7228@end table 7229 7230 7231 7232@node GETLOG 7233@section @code{GETLOG} --- Get login name 7234@fnindex GETLOG 7235@cindex system, login name 7236@cindex login name 7237 7238@table @asis 7239@item @emph{Description}: 7240Gets the username under which the program is running. 7241 7242@item @emph{Standard}: 7243GNU extension 7244 7245@item @emph{Class}: 7246Subroutine 7247 7248@item @emph{Syntax}: 7249@code{CALL GETLOG(C)} 7250 7251@item @emph{Arguments}: 7252@multitable @columnfractions .15 .70 7253@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind. 7254@end multitable 7255 7256@item @emph{Return value}: 7257Stores the current user name in @var{C}. (On systems where POSIX 7258functions @code{geteuid} and @code{getpwuid} are not available, and 7259the @code{getlogin} function is not implemented either, this will 7260return a blank string.) 7261 7262@item @emph{Example}: 7263@smallexample 7264PROGRAM TEST_GETLOG 7265 CHARACTER(32) :: login 7266 CALL GETLOG(login) 7267 WRITE(*,*) login 7268END PROGRAM 7269@end smallexample 7270 7271@item @emph{See also}: 7272@ref{GETUID} 7273@end table 7274 7275 7276 7277@node GETPID 7278@section @code{GETPID} --- Process ID function 7279@fnindex GETPID 7280@cindex system, process ID 7281@cindex process ID 7282 7283@table @asis 7284@item @emph{Description}: 7285Returns the numerical process identifier of the current process. 7286 7287@item @emph{Standard}: 7288GNU extension 7289 7290@item @emph{Class}: 7291Function 7292 7293@item @emph{Syntax}: 7294@code{RESULT = GETPID()} 7295 7296@item @emph{Return value}: 7297The return value of @code{GETPID} is an @code{INTEGER} of the default 7298kind. 7299 7300 7301@item @emph{Example}: 7302@smallexample 7303program info 7304 print *, "The current process ID is ", getpid() 7305 print *, "Your numerical user ID is ", getuid() 7306 print *, "Your numerical group ID is ", getgid() 7307end program info 7308@end smallexample 7309 7310@item @emph{See also}: 7311@ref{GETGID}, @gol 7312@ref{GETUID} 7313@end table 7314 7315 7316 7317@node GETUID 7318@section @code{GETUID} --- User ID function 7319@fnindex GETUID 7320@cindex system, user ID 7321@cindex user id 7322 7323@table @asis 7324@item @emph{Description}: 7325Returns the numerical user ID of the current process. 7326 7327@item @emph{Standard}: 7328GNU extension 7329 7330@item @emph{Class}: 7331Function 7332 7333@item @emph{Syntax}: 7334@code{RESULT = GETUID()} 7335 7336@item @emph{Return value}: 7337The return value of @code{GETUID} is an @code{INTEGER} of the default 7338kind. 7339 7340 7341@item @emph{Example}: 7342See @code{GETPID} for an example. 7343 7344@item @emph{See also}: 7345@ref{GETPID}, @gol 7346@ref{GETLOG} 7347@end table 7348 7349 7350 7351@node GMTIME 7352@section @code{GMTIME} --- Convert time to GMT info 7353@fnindex GMTIME 7354@cindex time, conversion to GMT info 7355 7356@table @asis 7357@item @emph{Description}: 7358Given a system time value @var{TIME} (as provided by the @ref{TIME} 7359intrinsic), fills @var{VALUES} with values extracted from it appropriate 7360to the UTC time zone (Universal Coordinated Time, also known in some 7361countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}. 7362 7363This intrinsic routine is provided for backwards compatibility with 7364GNU Fortran 77. In new code, programmers should consider the use of 7365the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 7366standard. 7367 7368@item @emph{Standard}: 7369GNU extension 7370 7371@item @emph{Class}: 7372Subroutine 7373 7374@item @emph{Syntax}: 7375@code{CALL GMTIME(TIME, VALUES)} 7376 7377@item @emph{Arguments}: 7378@multitable @columnfractions .15 .70 7379@item @var{TIME} @tab An @code{INTEGER} scalar expression 7380corresponding to a system time, with @code{INTENT(IN)}. 7381@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 7382with @code{INTENT(OUT)}. 7383@end multitable 7384 7385@item @emph{Return value}: 7386The elements of @var{VALUES} are assigned as follows: 7387@enumerate 7388@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 7389seconds 7390@item Minutes after the hour, range 0--59 7391@item Hours past midnight, range 0--23 7392@item Day of month, range 1--31 7393@item Number of months since January, range 0--11 7394@item Years since 1900 7395@item Number of days since Sunday, range 0--6 7396@item Days since January 1, range 0--365 7397@item Daylight savings indicator: positive if daylight savings is in 7398effect, zero if not, and negative if the information is not available. 7399@end enumerate 7400 7401@item @emph{See also}: 7402@ref{DATE_AND_TIME}, @gol 7403@ref{CTIME}, @gol 7404@ref{LTIME}, @gol 7405@ref{TIME}, @gol 7406@ref{TIME8} 7407@end table 7408 7409 7410 7411@node HOSTNM 7412@section @code{HOSTNM} --- Get system host name 7413@fnindex HOSTNM 7414@cindex system, host name 7415 7416@table @asis 7417@item @emph{Description}: 7418Retrieves the host name of the system on which the program is running. 7419 7420This intrinsic is provided in both subroutine and function forms; however, 7421only one form can be used in any given program unit. 7422 7423@item @emph{Standard}: 7424GNU extension 7425 7426@item @emph{Class}: 7427Subroutine, function 7428 7429@item @emph{Syntax}: 7430@multitable @columnfractions .80 7431@item @code{CALL HOSTNM(C [, STATUS])} 7432@item @code{STATUS = HOSTNM(NAME)} 7433@end multitable 7434 7435@item @emph{Arguments}: 7436@multitable @columnfractions .15 .70 7437@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind. 7438@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 7439Returns 0 on success, or a system specific error code otherwise. 7440@end multitable 7441 7442@item @emph{Return value}: 7443In either syntax, @var{NAME} is set to the current hostname if it can 7444be obtained, or to a blank string otherwise. 7445 7446@end table 7447 7448 7449 7450@node HUGE 7451@section @code{HUGE} --- Largest number of a kind 7452@fnindex HUGE 7453@cindex limits, largest number 7454@cindex model representation, largest number 7455 7456@table @asis 7457@item @emph{Description}: 7458@code{HUGE(X)} returns the largest number that is not an infinity in 7459the model of the type of @code{X}. 7460 7461@item @emph{Standard}: 7462Fortran 90 and later 7463 7464@item @emph{Class}: 7465Inquiry function 7466 7467@item @emph{Syntax}: 7468@code{RESULT = HUGE(X)} 7469 7470@item @emph{Arguments}: 7471@multitable @columnfractions .15 .70 7472@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}. 7473@end multitable 7474 7475@item @emph{Return value}: 7476The return value is of the same type and kind as @var{X} 7477 7478@item @emph{Example}: 7479@smallexample 7480program test_huge_tiny 7481 print *, huge(0), huge(0.0), huge(0.0d0) 7482 print *, tiny(0.0), tiny(0.0d0) 7483end program test_huge_tiny 7484@end smallexample 7485@end table 7486 7487 7488 7489@node HYPOT 7490@section @code{HYPOT} --- Euclidean distance function 7491@fnindex HYPOT 7492@cindex Euclidean distance 7493 7494@table @asis 7495@item @emph{Description}: 7496@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to 7497@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow. 7498 7499@item @emph{Standard}: 7500Fortran 2008 and later 7501 7502@item @emph{Class}: 7503Elemental function 7504 7505@item @emph{Syntax}: 7506@code{RESULT = HYPOT(X, Y)} 7507 7508@item @emph{Arguments}: 7509@multitable @columnfractions .15 .70 7510@item @var{X} @tab The type shall be @code{REAL}. 7511@item @var{Y} @tab The type and kind type parameter shall be the same as 7512@var{X}. 7513@end multitable 7514 7515@item @emph{Return value}: 7516The return value has the same type and kind type parameter as @var{X}. 7517 7518@item @emph{Example}: 7519@smallexample 7520program test_hypot 7521 real(4) :: x = 1.e0_4, y = 0.5e0_4 7522 x = hypot(x,y) 7523end program test_hypot 7524@end smallexample 7525@end table 7526 7527 7528 7529@node IACHAR 7530@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence 7531@fnindex IACHAR 7532@cindex @acronym{ASCII} collating sequence 7533@cindex collating sequence, @acronym{ASCII} 7534@cindex conversion, to integer 7535 7536@table @asis 7537@item @emph{Description}: 7538@code{IACHAR(C)} returns the code for the @acronym{ASCII} character 7539in the first character position of @code{C}. 7540 7541@item @emph{Standard}: 7542Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 7543 7544@item @emph{Class}: 7545Elemental function 7546 7547@item @emph{Syntax}: 7548@code{RESULT = IACHAR(C [, KIND])} 7549 7550@item @emph{Arguments}: 7551@multitable @columnfractions .15 .70 7552@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 7553@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7554expression indicating the kind parameter of the result. 7555@end multitable 7556 7557@item @emph{Return value}: 7558The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7559@var{KIND} is absent, the return value is of default integer kind. 7560 7561@item @emph{Example}: 7562@smallexample 7563program test_iachar 7564 integer i 7565 i = iachar(' ') 7566end program test_iachar 7567@end smallexample 7568 7569@item @emph{Note}: 7570See @ref{ICHAR} for a discussion of converting between numerical values 7571and formatted string representations. 7572 7573@item @emph{See also}: 7574@ref{ACHAR}, @gol 7575@ref{CHAR}, @gol 7576@ref{ICHAR} 7577@end table 7578 7579 7580 7581@node IALL 7582@section @code{IALL} --- Bitwise AND of array elements 7583@fnindex IALL 7584@cindex array, AND 7585@cindex bits, AND of array elements 7586 7587@table @asis 7588@item @emph{Description}: 7589Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM} 7590if the corresponding element in @var{MASK} is @code{TRUE}. 7591 7592@item @emph{Standard}: 7593Fortran 2008 and later 7594 7595@item @emph{Class}: 7596Transformational function 7597 7598@item @emph{Syntax}: 7599@multitable @columnfractions .80 7600@item @code{RESULT = IALL(ARRAY[, MASK])} 7601@item @code{RESULT = IALL(ARRAY, DIM[, MASK])} 7602@end multitable 7603 7604@item @emph{Arguments}: 7605@multitable @columnfractions .15 .70 7606@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7607@item @var{DIM} @tab (Optional) shall be a scalar of type 7608@code{INTEGER} with a value in the range from 1 to n, where n 7609equals the rank of @var{ARRAY}. 7610@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7611and either be a scalar or an array of the same shape as @var{ARRAY}. 7612@end multitable 7613 7614@item @emph{Return value}: 7615The result is of the same type as @var{ARRAY}. 7616 7617If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in 7618@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7619the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7620dimension @var{DIM} dropped is returned. 7621 7622@item @emph{Example}: 7623@smallexample 7624PROGRAM test_iall 7625 INTEGER(1) :: a(2) 7626 7627 a(1) = b'00100100' 7628 a(2) = b'01101010' 7629 7630 ! prints 00100000 7631 PRINT '(b8.8)', IALL(a) 7632END PROGRAM 7633@end smallexample 7634 7635@item @emph{See also}: 7636@ref{IANY}, @gol 7637@ref{IPARITY}, @gol 7638@ref{IAND} 7639@end table 7640 7641 7642 7643@node IAND 7644@section @code{IAND} --- Bitwise logical and 7645@fnindex IAND 7646@fnindex BIAND 7647@fnindex IIAND 7648@fnindex JIAND 7649@fnindex KIAND 7650@cindex bitwise logical and 7651@cindex logical and, bitwise 7652 7653@table @asis 7654@item @emph{Description}: 7655Bitwise logical @code{AND}. 7656 7657@item @emph{Standard}: 7658Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 7659 7660@item @emph{Class}: 7661Elemental function 7662 7663@item @emph{Syntax}: 7664@code{RESULT = IAND(I, J)} 7665 7666@item @emph{Arguments}: 7667@multitable @columnfractions .15 .70 7668@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 7669@item @var{J} @tab The type shall be @code{INTEGER} with the same 7670kind type parameter as @var{I} or a boz-literal-constant. 7671@var{I} and @var{J} shall not both be boz-literal-constants. 7672@end multitable 7673 7674@item @emph{Return value}: 7675The return type is @code{INTEGER} with the kind type parameter of the 7676arguments. 7677A boz-literal-constant is converted to an @code{INTEGER} with the kind 7678type parameter of the other argument as-if a call to @ref{INT} occurred. 7679 7680@item @emph{Example}: 7681@smallexample 7682PROGRAM test_iand 7683 INTEGER :: a, b 7684 DATA a / Z'F' /, b / Z'3' / 7685 WRITE (*,*) IAND(a, b) 7686END PROGRAM 7687@end smallexample 7688 7689@item @emph{Specific names}: 7690@multitable @columnfractions .20 .23 .20 .33 7691@headitem Name @tab Argument @tab Return type @tab Standard 7692@item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7693@item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7694@item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7695@item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7696@item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7697@end multitable 7698 7699@item @emph{See also}: 7700@ref{IOR}, @gol 7701@ref{IEOR}, @gol 7702@ref{IBITS}, @gol 7703@ref{IBSET}, @gol 7704@ref{IBCLR}, @gol 7705@ref{NOT} 7706@end table 7707 7708 7709 7710@node IANY 7711@section @code{IANY} --- Bitwise OR of array elements 7712@fnindex IANY 7713@cindex array, OR 7714@cindex bits, OR of array elements 7715 7716@table @asis 7717@item @emph{Description}: 7718Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along 7719dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 7720 7721@item @emph{Standard}: 7722Fortran 2008 and later 7723 7724@item @emph{Class}: 7725Transformational function 7726 7727@item @emph{Syntax}: 7728@multitable @columnfractions .80 7729@item @code{RESULT = IANY(ARRAY[, MASK])} 7730@item @code{RESULT = IANY(ARRAY, DIM[, MASK])} 7731@end multitable 7732 7733@item @emph{Arguments}: 7734@multitable @columnfractions .15 .70 7735@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7736@item @var{DIM} @tab (Optional) shall be a scalar of type 7737@code{INTEGER} with a value in the range from 1 to n, where n 7738equals the rank of @var{ARRAY}. 7739@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7740and either be a scalar or an array of the same shape as @var{ARRAY}. 7741@end multitable 7742 7743@item @emph{Return value}: 7744The result is of the same type as @var{ARRAY}. 7745 7746If @var{DIM} is absent, a scalar with the bitwise OR of all elements in 7747@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7748the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7749dimension @var{DIM} dropped is returned. 7750 7751@item @emph{Example}: 7752@smallexample 7753PROGRAM test_iany 7754 INTEGER(1) :: a(2) 7755 7756 a(1) = b'00100100' 7757 a(2) = b'01101010' 7758 7759 ! prints 01101110 7760 PRINT '(b8.8)', IANY(a) 7761END PROGRAM 7762@end smallexample 7763 7764@item @emph{See also}: 7765@ref{IPARITY}, @gol 7766@ref{IALL}, @gol 7767@ref{IOR} 7768@end table 7769 7770 7771 7772@node IARGC 7773@section @code{IARGC} --- Get the number of command line arguments 7774@fnindex IARGC 7775@cindex command-line arguments 7776@cindex command-line arguments, number of 7777@cindex arguments, to program 7778 7779@table @asis 7780@item @emph{Description}: 7781@code{IARGC} returns the number of arguments passed on the 7782command line when the containing program was invoked. 7783 7784This intrinsic routine is provided for backwards compatibility with 7785GNU Fortran 77. In new code, programmers should consider the use of 7786the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 7787standard. 7788 7789@item @emph{Standard}: 7790GNU extension 7791 7792@item @emph{Class}: 7793Function 7794 7795@item @emph{Syntax}: 7796@code{RESULT = IARGC()} 7797 7798@item @emph{Arguments}: 7799None 7800 7801@item @emph{Return value}: 7802The number of command line arguments, type @code{INTEGER(4)}. 7803 7804@item @emph{Example}: 7805See @ref{GETARG} 7806 7807@item @emph{See also}: 7808GNU Fortran 77 compatibility subroutine: @gol 7809@ref{GETARG} @gol 7810Fortran 2003 functions and subroutines: @gol 7811@ref{GET_COMMAND}, @gol 7812@ref{GET_COMMAND_ARGUMENT}, @gol 7813@ref{COMMAND_ARGUMENT_COUNT} 7814@end table 7815 7816 7817 7818@node IBCLR 7819@section @code{IBCLR} --- Clear bit 7820@fnindex IBCLR 7821@fnindex BBCLR 7822@fnindex IIBCLR 7823@fnindex JIBCLR 7824@fnindex KIBCLR 7825@cindex bits, unset 7826@cindex bits, clear 7827 7828@table @asis 7829@item @emph{Description}: 7830@code{IBCLR} returns the value of @var{I} with the bit at position 7831@var{POS} set to zero. 7832 7833@item @emph{Standard}: 7834Fortran 90 and later, has overloads that are GNU extensions 7835 7836@item @emph{Class}: 7837Elemental function 7838 7839@item @emph{Syntax}: 7840@code{RESULT = IBCLR(I, POS)} 7841 7842@item @emph{Arguments}: 7843@multitable @columnfractions .15 .70 7844@item @var{I} @tab The type shall be @code{INTEGER}. 7845@item @var{POS} @tab The type shall be @code{INTEGER}. 7846@end multitable 7847 7848@item @emph{Return value}: 7849The return value is of type @code{INTEGER} and of the same kind as 7850@var{I}. 7851 7852@item @emph{Specific names}: 7853@multitable @columnfractions .20 .23 .20 .33 7854@headitem Name @tab Argument @tab Return type @tab Standard 7855@item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7856@item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7857@item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7858@item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7859@item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7860@end multitable 7861 7862@item @emph{See also}: 7863@ref{IBITS}, @gol 7864@ref{IBSET}, @gol 7865@ref{IAND}, @gol 7866@ref{IOR}, @gol 7867@ref{IEOR}, @gol 7868@ref{MVBITS} 7869@end table 7870 7871 7872 7873@node IBITS 7874@section @code{IBITS} --- Bit extraction 7875@fnindex IBITS 7876@fnindex BBITS 7877@fnindex IIBITS 7878@fnindex JIBITS 7879@fnindex KIBITS 7880@cindex bits, get 7881@cindex bits, extract 7882 7883@table @asis 7884@item @emph{Description}: 7885@code{IBITS} extracts a field of length @var{LEN} from @var{I}, 7886starting from bit position @var{POS} and extending left for @var{LEN} 7887bits. The result is right-justified and the remaining bits are 7888zeroed. The value of @code{POS+LEN} must be less than or equal to the 7889value @code{BIT_SIZE(I)}. 7890 7891@item @emph{Standard}: 7892Fortran 90 and later, has overloads that are GNU extensions 7893 7894@item @emph{Class}: 7895Elemental function 7896 7897@item @emph{Syntax}: 7898@code{RESULT = IBITS(I, POS, LEN)} 7899 7900@item @emph{Arguments}: 7901@multitable @columnfractions .15 .70 7902@item @var{I} @tab The type shall be @code{INTEGER}. 7903@item @var{POS} @tab The type shall be @code{INTEGER}. 7904@item @var{LEN} @tab The type shall be @code{INTEGER}. 7905@end multitable 7906 7907@item @emph{Return value}: 7908The return value is of type @code{INTEGER} and of the same kind as 7909@var{I}. 7910 7911@item @emph{Specific names}: 7912@multitable @columnfractions .20 .23 .20 .33 7913@headitem Name @tab Argument @tab Return type @tab Standard 7914@item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7915@item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7916@item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7917@item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7918@item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7919@end multitable 7920 7921@item @emph{See also}: 7922@ref{BIT_SIZE}, @gol 7923@ref{IBCLR}, @gol 7924@ref{IBSET}, @gol 7925@ref{IAND}, @gol 7926@ref{IOR}, @gol 7927@ref{IEOR} 7928@end table 7929 7930 7931 7932@node IBSET 7933@section @code{IBSET} --- Set bit 7934@fnindex IBSET 7935@fnindex BBSET 7936@fnindex IIBSET 7937@fnindex JIBSET 7938@fnindex KIBSET 7939@cindex bits, set 7940 7941@table @asis 7942@item @emph{Description}: 7943@code{IBSET} returns the value of @var{I} with the bit at position 7944@var{POS} set to one. 7945 7946@item @emph{Standard}: 7947Fortran 90 and later, has overloads that are GNU extensions 7948 7949@item @emph{Class}: 7950Elemental function 7951 7952@item @emph{Syntax}: 7953@code{RESULT = IBSET(I, POS)} 7954 7955@item @emph{Arguments}: 7956@multitable @columnfractions .15 .70 7957@item @var{I} @tab The type shall be @code{INTEGER}. 7958@item @var{POS} @tab The type shall be @code{INTEGER}. 7959@end multitable 7960 7961@item @emph{Return value}: 7962The return value is of type @code{INTEGER} and of the same kind as 7963@var{I}. 7964 7965@item @emph{Specific names}: 7966@multitable @columnfractions .20 .23 .20 .33 7967@headitem Name @tab Argument @tab Return type @tab Standard 7968@item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7969@item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7970@item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7971@item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7972@item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7973@end multitable 7974 7975@item @emph{See also}: 7976@ref{IBCLR}, @gol 7977@ref{IBITS}, @gol 7978@ref{IAND}, @gol 7979@ref{IOR}, @gol 7980@ref{IEOR}, @gol 7981@ref{MVBITS} 7982@end table 7983 7984 7985 7986@node ICHAR 7987@section @code{ICHAR} --- Character-to-integer conversion function 7988@fnindex ICHAR 7989@cindex conversion, to integer 7990 7991@table @asis 7992@item @emph{Description}: 7993@code{ICHAR(C)} returns the code for the character in the first character 7994position of @code{C} in the system's native character set. 7995The correspondence between characters and their codes is not necessarily 7996the same across different GNU Fortran implementations. 7997 7998@item @emph{Standard}: 7999Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8000 8001@item @emph{Class}: 8002Elemental function 8003 8004@item @emph{Syntax}: 8005@code{RESULT = ICHAR(C [, KIND])} 8006 8007@item @emph{Arguments}: 8008@multitable @columnfractions .15 .70 8009@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 8010@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8011expression indicating the kind parameter of the result. 8012@end multitable 8013 8014@item @emph{Return value}: 8015The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8016@var{KIND} is absent, the return value is of default integer kind. 8017 8018@item @emph{Example}: 8019@smallexample 8020program test_ichar 8021 integer i 8022 i = ichar(' ') 8023end program test_ichar 8024@end smallexample 8025 8026@item @emph{Specific names}: 8027@multitable @columnfractions .20 .23 .20 .33 8028@headitem Name @tab Argument @tab Return type @tab Standard 8029@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later 8030@end multitable 8031 8032@item @emph{Note}: 8033No intrinsic exists to convert between a numeric value and a formatted 8034character string representation -- for instance, given the 8035@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or 8036@code{REAL} value with the value 154, or vice versa. Instead, this 8037functionality is provided by internal-file I/O, as in the following 8038example: 8039@smallexample 8040program read_val 8041 integer value 8042 character(len=10) string, string2 8043 string = '154' 8044 8045 ! Convert a string to a numeric value 8046 read (string,'(I10)') value 8047 print *, value 8048 8049 ! Convert a value to a formatted string 8050 write (string2,'(I10)') value 8051 print *, string2 8052end program read_val 8053@end smallexample 8054 8055@item @emph{See also}: 8056@ref{ACHAR}, @gol 8057@ref{CHAR}, @gol 8058@ref{IACHAR} 8059@end table 8060 8061 8062 8063@node IDATE 8064@section @code{IDATE} --- Get current local time subroutine (day/month/year) 8065@fnindex IDATE 8066@cindex date, current 8067@cindex current date 8068 8069@table @asis 8070@item @emph{Description}: 8071@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the 8072current local time. The day (in the range 1-31), month (in the range 1-12), 8073and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively. 8074The year has four significant digits. 8075 8076This intrinsic routine is provided for backwards compatibility with 8077GNU Fortran 77. In new code, programmers should consider the use of 8078the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 8079standard. 8080 8081@item @emph{Standard}: 8082GNU extension 8083 8084@item @emph{Class}: 8085Subroutine 8086 8087@item @emph{Syntax}: 8088@code{CALL IDATE(VALUES)} 8089 8090@item @emph{Arguments}: 8091@multitable @columnfractions .15 .70 8092@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and 8093the kind shall be the default integer kind. 8094@end multitable 8095 8096@item @emph{Return value}: 8097Does not return anything. 8098 8099@item @emph{Example}: 8100@smallexample 8101program test_idate 8102 integer, dimension(3) :: tarray 8103 call idate(tarray) 8104 print *, tarray(1) 8105 print *, tarray(2) 8106 print *, tarray(3) 8107end program test_idate 8108@end smallexample 8109 8110@item @emph{See also}: 8111@ref{DATE_AND_TIME} 8112@end table 8113 8114 8115@node IEOR 8116@section @code{IEOR} --- Bitwise logical exclusive or 8117@fnindex IEOR 8118@fnindex BIEOR 8119@fnindex IIEOR 8120@fnindex JIEOR 8121@fnindex KIEOR 8122@cindex bitwise logical exclusive or 8123@cindex logical exclusive or, bitwise 8124 8125@table @asis 8126@item @emph{Description}: 8127@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and 8128@var{J}. 8129 8130@item @emph{Standard}: 8131Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 8132 8133@item @emph{Class}: 8134Elemental function 8135 8136@item @emph{Syntax}: 8137@code{RESULT = IEOR(I, J)} 8138 8139@item @emph{Arguments}: 8140@multitable @columnfractions .15 .70 8141@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 8142@item @var{J} @tab The type shall be @code{INTEGER} with the same 8143kind type parameter as @var{I} or a boz-literal-constant. 8144@var{I} and @var{J} shall not both be boz-literal-constants. 8145@end multitable 8146 8147@item @emph{Return value}: 8148The return type is @code{INTEGER} with the kind type parameter of the 8149arguments. 8150A boz-literal-constant is converted to an @code{INTEGER} with the kind 8151type parameter of the other argument as-if a call to @ref{INT} occurred. 8152 8153@item @emph{Specific names}: 8154@multitable @columnfractions .20 .23 .20 .33 8155@headitem Name @tab Argument @tab Return type @tab Standard 8156@item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8157@item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8158@item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8159@item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8160@item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8161@end multitable 8162 8163@item @emph{See also}: 8164@ref{IOR}, @gol 8165@ref{IAND}, @gol 8166@ref{IBITS}, @gol 8167@ref{IBSET}, @gol 8168@ref{IBCLR}, @gol 8169@ref{NOT} 8170@end table 8171 8172 8173 8174@node IERRNO 8175@section @code{IERRNO} --- Get the last system error number 8176@fnindex IERRNO 8177@cindex system, error handling 8178 8179@table @asis 8180@item @emph{Description}: 8181Returns the last system error number, as given by the C @code{errno} 8182variable. 8183 8184@item @emph{Standard}: 8185GNU extension 8186 8187@item @emph{Class}: 8188Function 8189 8190@item @emph{Syntax}: 8191@code{RESULT = IERRNO()} 8192 8193@item @emph{Arguments}: 8194None 8195 8196@item @emph{Return value}: 8197The return value is of type @code{INTEGER} and of the default integer 8198kind. 8199 8200@item @emph{See also}: 8201@ref{PERROR} 8202@end table 8203 8204 8205 8206@node IMAGE_INDEX 8207@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index 8208@fnindex IMAGE_INDEX 8209@cindex coarray, @code{IMAGE_INDEX} 8210@cindex images, cosubscript to image index conversion 8211 8212@table @asis 8213@item @emph{Description}: 8214Returns the image index belonging to a cosubscript. 8215 8216@item @emph{Standard}: 8217Fortran 2008 and later 8218 8219@item @emph{Class}: 8220Inquiry function. 8221 8222@item @emph{Syntax}: 8223@code{RESULT = IMAGE_INDEX(COARRAY, SUB)} 8224 8225@item @emph{Arguments}: 8226@multitable @columnfractions .15 .70 8227@item @var{COARRAY} @tab Coarray of any type. 8228@item @var{SUB} @tab default integer rank-1 array of a size equal to 8229the corank of @var{COARRAY}. 8230@end multitable 8231 8232 8233@item @emph{Return value}: 8234Scalar default integer with the value of the image index which corresponds 8235to the cosubscripts. For invalid cosubscripts the result is zero. 8236 8237@item @emph{Example}: 8238@smallexample 8239INTEGER :: array[2,-1:4,8,*] 8240! Writes 28 (or 0 if there are fewer than 28 images) 8241WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1]) 8242@end smallexample 8243 8244@item @emph{See also}: 8245@ref{THIS_IMAGE}, @gol 8246@ref{NUM_IMAGES} 8247@end table 8248 8249 8250 8251@node INDEX intrinsic 8252@section @code{INDEX} --- Position of a substring within a string 8253@fnindex INDEX 8254@cindex substring position 8255@cindex string, find substring 8256 8257@table @asis 8258@item @emph{Description}: 8259Returns the position of the start of the first occurrence of string 8260@var{SUBSTRING} as a substring in @var{STRING}, counting from one. If 8261@var{SUBSTRING} is not present in @var{STRING}, zero is returned. If 8262the @var{BACK} argument is present and true, the return value is the 8263start of the last occurrence rather than the first. 8264 8265@item @emph{Standard}: 8266Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8267 8268@item @emph{Class}: 8269Elemental function 8270 8271@item @emph{Syntax}: 8272@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])} 8273 8274@item @emph{Arguments}: 8275@multitable @columnfractions .15 .70 8276@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with 8277@code{INTENT(IN)} 8278@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with 8279@code{INTENT(IN)} 8280@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with 8281@code{INTENT(IN)} 8282@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8283expression indicating the kind parameter of the result. 8284@end multitable 8285 8286@item @emph{Return value}: 8287The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8288@var{KIND} is absent, the return value is of default integer kind. 8289 8290@item @emph{Specific names}: 8291@multitable @columnfractions .35 .15 .17 .30 8292@headitem Name @tab Argument @tab Return type @tab Standard 8293@item @code{INDEX(STRING,SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later 8294@end multitable 8295 8296@item @emph{See also}: 8297@ref{SCAN}, @gol 8298@ref{VERIFY} 8299@end table 8300 8301 8302 8303@node INT 8304@section @code{INT} --- Convert to integer type 8305@fnindex INT 8306@fnindex IFIX 8307@fnindex IDINT 8308@cindex conversion, to integer 8309 8310@table @asis 8311@item @emph{Description}: 8312Convert to integer type 8313 8314@item @emph{Standard}: 8315Fortran 77 and later, with boz-literal-constant Fortran 2008 and later. 8316 8317@item @emph{Class}: 8318Elemental function 8319 8320@item @emph{Syntax}: 8321@code{RESULT = INT(A [, KIND))} 8322 8323@item @emph{Arguments}: 8324@multitable @columnfractions .15 .70 8325@item @var{A} @tab Shall be of type @code{INTEGER}, 8326@code{REAL}, or @code{COMPLEX} or a boz-literal-constant. 8327@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8328expression indicating the kind parameter of the result. 8329@end multitable 8330 8331@item @emph{Return value}: 8332These functions return a @code{INTEGER} variable or array under 8333the following rules: 8334 8335@table @asis 8336@item (A) 8337If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 8338@item (B) 8339If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} 8340equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer 8341whose magnitude is the largest integer that does not exceed the magnitude 8342of @var{A} and whose sign is the same as the sign of @var{A}. 8343@item (C) 8344If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}. 8345@end table 8346 8347@item @emph{Example}: 8348@smallexample 8349program test_int 8350 integer :: i = 42 8351 complex :: z = (-3.7, 1.0) 8352 print *, int(i) 8353 print *, int(z), int(z,8) 8354end program 8355@end smallexample 8356 8357@item @emph{Specific names}: 8358@multitable @columnfractions .20 .23 .20 .33 8359@headitem Name @tab Argument @tab Return type @tab Standard 8360@item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8361@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8362@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 8363@end multitable 8364 8365@end table 8366 8367 8368@node INT2 8369@section @code{INT2} --- Convert to 16-bit integer type 8370@fnindex INT2 8371@cindex conversion, to integer 8372 8373@table @asis 8374@item @emph{Description}: 8375Convert to a @code{KIND=2} integer type. This is equivalent to the 8376standard @code{INT} intrinsic with an optional argument of 8377@code{KIND=2}, and is only included for backwards compatibility. 8378 8379@item @emph{Standard}: 8380GNU extension 8381 8382@item @emph{Class}: 8383Elemental function 8384 8385@item @emph{Syntax}: 8386@code{RESULT = INT2(A)} 8387 8388@item @emph{Arguments}: 8389@multitable @columnfractions .15 .70 8390@item @var{A} @tab Shall be of type @code{INTEGER}, 8391@code{REAL}, or @code{COMPLEX}. 8392@end multitable 8393 8394@item @emph{Return value}: 8395The return value is a @code{INTEGER(2)} variable. 8396 8397@item @emph{See also}: 8398@ref{INT}, @gol 8399@ref{INT8} 8400@end table 8401 8402 8403 8404@node INT8 8405@section @code{INT8} --- Convert to 64-bit integer type 8406@fnindex INT8 8407@cindex conversion, to integer 8408 8409@table @asis 8410@item @emph{Description}: 8411Convert to a @code{KIND=8} integer type. This is equivalent to the 8412standard @code{INT} intrinsic with an optional argument of 8413@code{KIND=8}, and is only included for backwards compatibility. 8414 8415@item @emph{Standard}: 8416GNU extension 8417 8418@item @emph{Class}: 8419Elemental function 8420 8421@item @emph{Syntax}: 8422@code{RESULT = INT8(A)} 8423 8424@item @emph{Arguments}: 8425@multitable @columnfractions .15 .70 8426@item @var{A} @tab Shall be of type @code{INTEGER}, 8427@code{REAL}, or @code{COMPLEX}. 8428@end multitable 8429 8430@item @emph{Return value}: 8431The return value is a @code{INTEGER(8)} variable. 8432 8433@item @emph{See also}: 8434@ref{INT}, @gol 8435@ref{INT2} 8436@end table 8437 8438 8439 8440@node IOR 8441@section @code{IOR} --- Bitwise logical or 8442@fnindex IOR 8443@fnindex BIOR 8444@fnindex IIOR 8445@fnindex JIOR 8446@fnindex KIOR 8447@cindex bitwise logical or 8448@cindex logical or, bitwise 8449 8450@table @asis 8451@item @emph{Description}: 8452@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and 8453@var{J}. 8454 8455@item @emph{Standard}: 8456Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 8457 8458@item @emph{Class}: 8459Elemental function 8460 8461@item @emph{Syntax}: 8462@code{RESULT = IOR(I, J)} 8463 8464@item @emph{Arguments}: 8465@multitable @columnfractions .15 .70 8466@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 8467@item @var{J} @tab The type shall be @code{INTEGER} with the same 8468kind type parameter as @var{I} or a boz-literal-constant. 8469@var{I} and @var{J} shall not both be boz-literal-constants. 8470@end multitable 8471 8472@item @emph{Return value}: 8473The return type is @code{INTEGER} with the kind type parameter of the 8474arguments. 8475A boz-literal-constant is converted to an @code{INTEGER} with the kind 8476type parameter of the other argument as-if a call to @ref{INT} occurred. 8477 8478@item @emph{Specific names}: 8479@multitable @columnfractions .20 .23 .20 .33 8480@headitem Name @tab Argument @tab Return type @tab Standard 8481@item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8482@item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8483@item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8484@item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8485@item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8486@end multitable 8487 8488@item @emph{See also}: 8489@ref{IEOR}, @gol 8490@ref{IAND}, @gol 8491@ref{IBITS}, @gol 8492@ref{IBSET}, @gol 8493@ref{IBCLR}, @gol 8494@ref{NOT} 8495@end table 8496 8497 8498 8499@node IPARITY 8500@section @code{IPARITY} --- Bitwise XOR of array elements 8501@fnindex IPARITY 8502@cindex array, parity 8503@cindex array, XOR 8504@cindex bits, XOR of array elements 8505 8506@table @asis 8507@item @emph{Description}: 8508Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along 8509dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 8510 8511@item @emph{Standard}: 8512Fortran 2008 and later 8513 8514@item @emph{Class}: 8515Transformational function 8516 8517@item @emph{Syntax}: 8518@multitable @columnfractions .80 8519@item @code{RESULT = IPARITY(ARRAY[, MASK])} 8520@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])} 8521@end multitable 8522 8523@item @emph{Arguments}: 8524@multitable @columnfractions .15 .70 8525@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 8526@item @var{DIM} @tab (Optional) shall be a scalar of type 8527@code{INTEGER} with a value in the range from 1 to n, where n 8528equals the rank of @var{ARRAY}. 8529@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 8530and either be a scalar or an array of the same shape as @var{ARRAY}. 8531@end multitable 8532 8533@item @emph{Return value}: 8534The result is of the same type as @var{ARRAY}. 8535 8536If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in 8537@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 8538the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 8539dimension @var{DIM} dropped is returned. 8540 8541@item @emph{Example}: 8542@smallexample 8543PROGRAM test_iparity 8544 INTEGER(1) :: a(2) 8545 8546 a(1) = int(b'00100100', 1) 8547 a(2) = int(b'01101010', 1) 8548 8549 ! prints 01001110 8550 PRINT '(b8.8)', IPARITY(a) 8551END PROGRAM 8552@end smallexample 8553 8554@item @emph{See also}: 8555@ref{IANY}, @gol 8556@ref{IALL}, @gol 8557@ref{IEOR}, @gol 8558@ref{PARITY} 8559@end table 8560 8561 8562 8563@node IRAND 8564@section @code{IRAND} --- Integer pseudo-random number 8565@fnindex IRAND 8566@cindex random number generation 8567 8568@table @asis 8569@item @emph{Description}: 8570@code{IRAND(FLAG)} returns a pseudo-random number from a uniform 8571distribution between 0 and a system-dependent limit (which is in most 8572cases 2147483647). If @var{FLAG} is 0, the next number 8573in the current sequence is returned; if @var{FLAG} is 1, the generator 8574is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 8575it is used as a new seed with @code{SRAND}. 8576 8577This intrinsic routine is provided for backwards compatibility with 8578GNU Fortran 77. It implements a simple modulo generator as provided 8579by @command{g77}. For new code, one should consider the use of 8580@ref{RANDOM_NUMBER} as it implements a superior algorithm. 8581 8582@item @emph{Standard}: 8583GNU extension 8584 8585@item @emph{Class}: 8586Function 8587 8588@item @emph{Syntax}: 8589@code{RESULT = IRAND(I)} 8590 8591@item @emph{Arguments}: 8592@multitable @columnfractions .15 .70 8593@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 8594@end multitable 8595 8596@item @emph{Return value}: 8597The return value is of @code{INTEGER(kind=4)} type. 8598 8599@item @emph{Example}: 8600@smallexample 8601program test_irand 8602 integer,parameter :: seed = 86456 8603 8604 call srand(seed) 8605 print *, irand(), irand(), irand(), irand() 8606 print *, irand(seed), irand(), irand(), irand() 8607end program test_irand 8608@end smallexample 8609 8610@end table 8611 8612 8613 8614@node IS_CONTIGUOUS 8615@section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous 8616@fnindex IS_IOSTAT_EOR 8617@cindex array, contiguity 8618 8619@table @asis 8620@item @emph{Description}: 8621@code{IS_CONTIGUOUS} tests whether an array is contiguous. 8622 8623@item @emph{Standard}: 8624Fortran 2008 and later 8625 8626@item @emph{Class}: 8627Inquiry function 8628 8629@item @emph{Syntax}: 8630@code{RESULT = IS_CONTIGUOUS(ARRAY)} 8631 8632@item @emph{Arguments}: 8633@multitable @columnfractions .15 .70 8634@item @var{ARRAY} @tab Shall be an array of any type. 8635@end multitable 8636 8637@item @emph{Return value}: 8638Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8639@var{ARRAY} is contiguous and false otherwise. 8640 8641@item @emph{Example}: 8642@smallexample 8643program test 8644 integer :: a(10) 8645 a = [1,2,3,4,5,6,7,8,9,10] 8646 call sub (a) ! every element, is contiguous 8647 call sub (a(::2)) ! every other element, is noncontiguous 8648contains 8649 subroutine sub (x) 8650 integer :: x(:) 8651 if (is_contiguous (x)) then 8652 write (*,*) 'X is contiguous' 8653 else 8654 write (*,*) 'X is not contiguous' 8655 end if 8656 end subroutine sub 8657end program test 8658@end smallexample 8659@end table 8660 8661 8662 8663@node IS_IOSTAT_END 8664@section @code{IS_IOSTAT_END} --- Test for end-of-file value 8665@fnindex IS_IOSTAT_END 8666@cindex @code{IOSTAT}, end of file 8667 8668@table @asis 8669@item @emph{Description}: 8670@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O 8671status ``end of file''. The function is equivalent to comparing the variable 8672with the @code{IOSTAT_END} parameter of the intrinsic module 8673@code{ISO_FORTRAN_ENV}. 8674 8675@item @emph{Standard}: 8676Fortran 2003 and later 8677 8678@item @emph{Class}: 8679Elemental function 8680 8681@item @emph{Syntax}: 8682@code{RESULT = IS_IOSTAT_END(I)} 8683 8684@item @emph{Arguments}: 8685@multitable @columnfractions .15 .70 8686@item @var{I} @tab Shall be of the type @code{INTEGER}. 8687@end multitable 8688 8689@item @emph{Return value}: 8690Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8691@var{I} has the value which indicates an end of file condition for 8692@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8693 8694@item @emph{Example}: 8695@smallexample 8696PROGRAM iostat 8697 IMPLICIT NONE 8698 INTEGER :: stat, i 8699 OPEN(88, FILE='test.dat') 8700 READ(88, *, IOSTAT=stat) i 8701 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE' 8702END PROGRAM 8703@end smallexample 8704@end table 8705 8706 8707 8708@node IS_IOSTAT_EOR 8709@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value 8710@fnindex IS_IOSTAT_EOR 8711@cindex @code{IOSTAT}, end of record 8712 8713@table @asis 8714@item @emph{Description}: 8715@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O 8716status ``end of record''. The function is equivalent to comparing the 8717variable with the @code{IOSTAT_EOR} parameter of the intrinsic module 8718@code{ISO_FORTRAN_ENV}. 8719 8720@item @emph{Standard}: 8721Fortran 2003 and later 8722 8723@item @emph{Class}: 8724Elemental function 8725 8726@item @emph{Syntax}: 8727@code{RESULT = IS_IOSTAT_EOR(I)} 8728 8729@item @emph{Arguments}: 8730@multitable @columnfractions .15 .70 8731@item @var{I} @tab Shall be of the type @code{INTEGER}. 8732@end multitable 8733 8734@item @emph{Return value}: 8735Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8736@var{I} has the value which indicates an end of file condition for 8737@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8738 8739@item @emph{Example}: 8740@smallexample 8741PROGRAM iostat 8742 IMPLICIT NONE 8743 INTEGER :: stat, i(50) 8744 OPEN(88, FILE='test.dat', FORM='UNFORMATTED') 8745 READ(88, IOSTAT=stat) i 8746 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD' 8747END PROGRAM 8748@end smallexample 8749@end table 8750 8751 8752@node ISATTY 8753@section @code{ISATTY} --- Whether a unit is a terminal device. 8754@fnindex ISATTY 8755@cindex system, terminal 8756 8757@table @asis 8758@item @emph{Description}: 8759Determine whether a unit is connected to a terminal device. 8760 8761@item @emph{Standard}: 8762GNU extension 8763 8764@item @emph{Class}: 8765Function 8766 8767@item @emph{Syntax}: 8768@code{RESULT = ISATTY(UNIT)} 8769 8770@item @emph{Arguments}: 8771@multitable @columnfractions .15 .70 8772@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 8773@end multitable 8774 8775@item @emph{Return value}: 8776Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal 8777device, @code{.FALSE.} otherwise. 8778 8779@item @emph{Example}: 8780@smallexample 8781PROGRAM test_isatty 8782 INTEGER(kind=1) :: unit 8783 DO unit = 1, 10 8784 write(*,*) isatty(unit=unit) 8785 END DO 8786END PROGRAM 8787@end smallexample 8788@item @emph{See also}: 8789@ref{TTYNAM} 8790@end table 8791 8792 8793 8794@node ISHFT 8795@section @code{ISHFT} --- Shift bits 8796@fnindex ISHFT 8797@fnindex BSHFT 8798@fnindex IISHFT 8799@fnindex JISHFT 8800@fnindex KISHFT 8801@cindex bits, shift 8802 8803@table @asis 8804@item @emph{Description}: 8805@code{ISHFT} returns a value corresponding to @var{I} with all of the 8806bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than 8807zero corresponds to a left shift, a value of zero corresponds to no 8808shift, and a value less than zero corresponds to a right shift. If the 8809absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the 8810value is undefined. Bits shifted out from the left end or right end are 8811lost; zeros are shifted in from the opposite end. 8812 8813@item @emph{Standard}: 8814Fortran 90 and later, has overloads that are GNU extensions 8815 8816@item @emph{Class}: 8817Elemental function 8818 8819@item @emph{Syntax}: 8820@code{RESULT = ISHFT(I, SHIFT)} 8821 8822@item @emph{Arguments}: 8823@multitable @columnfractions .15 .70 8824@item @var{I} @tab The type shall be @code{INTEGER}. 8825@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8826@end multitable 8827 8828@item @emph{Return value}: 8829The return value is of type @code{INTEGER} and of the same kind as 8830@var{I}. 8831 8832@item @emph{Specific names}: 8833@multitable @columnfractions .20 .23 .20 .33 8834@headitem Name @tab Argument @tab Return type @tab Standard 8835@item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8836@item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8837@item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8838@item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8839@item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8840@end multitable 8841 8842@item @emph{See also}: 8843@ref{ISHFTC} 8844@end table 8845 8846 8847 8848@node ISHFTC 8849@section @code{ISHFTC} --- Shift bits circularly 8850@fnindex ISHFTC 8851@fnindex BSHFTC 8852@fnindex IISHFTC 8853@fnindex JISHFTC 8854@fnindex KISHFTC 8855@cindex bits, shift circular 8856 8857@table @asis 8858@item @emph{Description}: 8859@code{ISHFTC} returns a value corresponding to @var{I} with the 8860rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that 8861is, bits shifted out one end are shifted into the opposite end. A value 8862of @var{SHIFT} greater than zero corresponds to a left shift, a value of 8863zero corresponds to no shift, and a value less than zero corresponds to 8864a right shift. The absolute value of @var{SHIFT} must be less than 8865@var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be 8866equivalent to @code{BIT_SIZE(I)}. 8867 8868@item @emph{Standard}: 8869Fortran 90 and later, has overloads that are GNU extensions 8870 8871@item @emph{Class}: 8872Elemental function 8873 8874@item @emph{Syntax}: 8875@code{RESULT = ISHFTC(I, SHIFT [, SIZE])} 8876 8877@item @emph{Arguments}: 8878@multitable @columnfractions .15 .70 8879@item @var{I} @tab The type shall be @code{INTEGER}. 8880@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8881@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER}; 8882the value must be greater than zero and less than or equal to 8883@code{BIT_SIZE(I)}. 8884@end multitable 8885 8886@item @emph{Return value}: 8887The return value is of type @code{INTEGER} and of the same kind as 8888@var{I}. 8889 8890@item @emph{Specific names}: 8891@multitable @columnfractions .20 .23 .20 .33 8892@headitem Name @tab Argument @tab Return type @tab Standard 8893@item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8894@item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8895@item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8896@item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8897@item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8898@end multitable 8899 8900@item @emph{See also}: 8901@ref{ISHFT} 8902@end table 8903 8904 8905 8906@node ISNAN 8907@section @code{ISNAN} --- Test for a NaN 8908@fnindex ISNAN 8909@cindex IEEE, ISNAN 8910 8911@table @asis 8912@item @emph{Description}: 8913@code{ISNAN} tests whether a floating-point value is an IEEE 8914Not-a-Number (NaN). 8915@item @emph{Standard}: 8916GNU extension 8917 8918@item @emph{Class}: 8919Elemental function 8920 8921@item @emph{Syntax}: 8922@code{ISNAN(X)} 8923 8924@item @emph{Arguments}: 8925@multitable @columnfractions .15 .70 8926@item @var{X} @tab Variable of the type @code{REAL}. 8927 8928@end multitable 8929 8930@item @emph{Return value}: 8931Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE} 8932if @var{X} is a NaN and @code{FALSE} otherwise. 8933 8934@item @emph{Example}: 8935@smallexample 8936program test_nan 8937 implicit none 8938 real :: x 8939 x = -1.0 8940 x = sqrt(x) 8941 if (isnan(x)) stop '"x" is a NaN' 8942end program test_nan 8943@end smallexample 8944@end table 8945 8946 8947 8948@node ITIME 8949@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) 8950@fnindex ITIME 8951@cindex time, current 8952@cindex current time 8953 8954@table @asis 8955@item @emph{Description}: 8956@code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the 8957current local time. The hour (in the range 1-24), minute (in the range 1-60), 8958and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES}, 8959respectively. 8960 8961This intrinsic routine is provided for backwards compatibility with 8962GNU Fortran 77. In new code, programmers should consider the use of 8963the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 8964standard. 8965 8966@item @emph{Standard}: 8967GNU extension 8968 8969@item @emph{Class}: 8970Subroutine 8971 8972@item @emph{Syntax}: 8973@code{CALL ITIME(VALUES)} 8974 8975@item @emph{Arguments}: 8976@multitable @columnfractions .15 .70 8977@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} 8978and the kind shall be the default integer kind. 8979@end multitable 8980 8981@item @emph{Return value}: 8982Does not return anything. 8983 8984 8985@item @emph{Example}: 8986@smallexample 8987program test_itime 8988 integer, dimension(3) :: tarray 8989 call itime(tarray) 8990 print *, tarray(1) 8991 print *, tarray(2) 8992 print *, tarray(3) 8993end program test_itime 8994@end smallexample 8995 8996@item @emph{See also}: 8997@ref{DATE_AND_TIME} 8998@end table 8999 9000 9001 9002@node KILL 9003@section @code{KILL} --- Send a signal to a process 9004@fnindex KILL 9005 9006@table @asis 9007@item @emph{Description}: 9008Sends the signal specified by @var{SIG} to the process @var{PID}. 9009See @code{kill(2)}. 9010 9011This intrinsic is provided in both subroutine and function forms; 9012however, only one form can be used in any given program unit. 9013@item @emph{Standard}: 9014GNU extension 9015 9016@item @emph{Standard}: 9017GNU extension 9018 9019@item @emph{Class}: 9020Subroutine, function 9021 9022@item @emph{Syntax}: 9023@multitable @columnfractions .80 9024@item @code{CALL KILL(PID, SIG [, STATUS])} 9025@item @code{STATUS = KILL(PID, SIG)} 9026@end multitable 9027 9028@item @emph{Arguments}: 9029@multitable @columnfractions .15 .70 9030@item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 9031@item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 9032@item @var{STATUS} @tab [Subroutine](Optional) 9033Shall be a scalar @code{INTEGER}. 9034Returns 0 on success; otherwise a system-specific error code is returned. 9035@item @var{STATUS} @tab [Function] The kind type parameter is that of 9036@code{pid}. 9037Returns 0 on success; otherwise a system-specific error code is returned. 9038@end multitable 9039 9040@item @emph{See also}: 9041@ref{ABORT}, @gol 9042@ref{EXIT} 9043@end table 9044 9045 9046@node KIND 9047@section @code{KIND} --- Kind of an entity 9048@fnindex KIND 9049@cindex kind 9050 9051@table @asis 9052@item @emph{Description}: 9053@code{KIND(X)} returns the kind value of the entity @var{X}. 9054 9055@item @emph{Standard}: 9056Fortran 95 and later 9057 9058@item @emph{Class}: 9059Inquiry function 9060 9061@item @emph{Syntax}: 9062@code{K = KIND(X)} 9063 9064@item @emph{Arguments}: 9065@multitable @columnfractions .15 .70 9066@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER}, 9067@code{REAL}, @code{COMPLEX} or @code{CHARACTER}. It may be scalar or 9068array valued. 9069@end multitable 9070 9071@item @emph{Return value}: 9072The return value is a scalar of type @code{INTEGER} and of the default 9073integer kind. 9074 9075@item @emph{Example}: 9076@smallexample 9077program test_kind 9078 integer,parameter :: kc = kind(' ') 9079 integer,parameter :: kl = kind(.true.) 9080 9081 print *, "The default character kind is ", kc 9082 print *, "The default logical kind is ", kl 9083end program test_kind 9084@end smallexample 9085 9086@end table 9087 9088 9089 9090@node LBOUND 9091@section @code{LBOUND} --- Lower dimension bounds of an array 9092@fnindex LBOUND 9093@cindex array, lower bound 9094 9095@table @asis 9096@item @emph{Description}: 9097Returns the lower bounds of an array, or a single lower bound 9098along the @var{DIM} dimension. 9099@item @emph{Standard}: 9100Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 9101 9102@item @emph{Class}: 9103Inquiry function 9104 9105@item @emph{Syntax}: 9106@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])} 9107 9108@item @emph{Arguments}: 9109@multitable @columnfractions .15 .70 9110@item @var{ARRAY} @tab Shall be an array, of any type. 9111@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 9112@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9113expression indicating the kind parameter of the result. 9114@end multitable 9115 9116@item @emph{Return value}: 9117The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9118@var{KIND} is absent, the return value is of default integer kind. 9119If @var{DIM} is absent, the result is an array of the lower bounds of 9120@var{ARRAY}. If @var{DIM} is present, the result is a scalar 9121corresponding to the lower bound of the array along that dimension. If 9122@var{ARRAY} is an expression rather than a whole array or array 9123structure component, or if it has a zero extent along the relevant 9124dimension, the lower bound is taken to be 1. 9125 9126@item @emph{See also}: 9127@ref{UBOUND}, @gol 9128@ref{LCOBOUND} 9129@end table 9130 9131 9132 9133@node LCOBOUND 9134@section @code{LCOBOUND} --- Lower codimension bounds of an array 9135@fnindex LCOBOUND 9136@cindex coarray, lower bound 9137 9138@table @asis 9139@item @emph{Description}: 9140Returns the lower bounds of a coarray, or a single lower cobound 9141along the @var{DIM} codimension. 9142@item @emph{Standard}: 9143Fortran 2008 and later 9144 9145@item @emph{Class}: 9146Inquiry function 9147 9148@item @emph{Syntax}: 9149@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])} 9150 9151@item @emph{Arguments}: 9152@multitable @columnfractions .15 .70 9153@item @var{ARRAY} @tab Shall be an coarray, of any type. 9154@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 9155@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9156expression indicating the kind parameter of the result. 9157@end multitable 9158 9159@item @emph{Return value}: 9160The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9161@var{KIND} is absent, the return value is of default integer kind. 9162If @var{DIM} is absent, the result is an array of the lower cobounds of 9163@var{COARRAY}. If @var{DIM} is present, the result is a scalar 9164corresponding to the lower cobound of the array along that codimension. 9165 9166@item @emph{See also}: 9167@ref{UCOBOUND}, @gol 9168@ref{LBOUND} 9169@end table 9170 9171 9172 9173@node LEADZ 9174@section @code{LEADZ} --- Number of leading zero bits of an integer 9175@fnindex LEADZ 9176@cindex zero bits 9177 9178@table @asis 9179@item @emph{Description}: 9180@code{LEADZ} returns the number of leading zero bits of an integer. 9181 9182@item @emph{Standard}: 9183Fortran 2008 and later 9184 9185@item @emph{Class}: 9186Elemental function 9187 9188@item @emph{Syntax}: 9189@code{RESULT = LEADZ(I)} 9190 9191@item @emph{Arguments}: 9192@multitable @columnfractions .15 .70 9193@item @var{I} @tab Shall be of type @code{INTEGER}. 9194@end multitable 9195 9196@item @emph{Return value}: 9197The type of the return value is the default @code{INTEGER}. 9198If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 9199 9200@item @emph{Example}: 9201@smallexample 9202PROGRAM test_leadz 9203 WRITE (*,*) BIT_SIZE(1) ! prints 32 9204 WRITE (*,*) LEADZ(1) ! prints 31 9205END PROGRAM 9206@end smallexample 9207 9208@item @emph{See also}: 9209@ref{BIT_SIZE}, @gol 9210@ref{TRAILZ}, @gol 9211@ref{POPCNT}, @gol 9212@ref{POPPAR} 9213@end table 9214 9215 9216 9217@node LEN 9218@section @code{LEN} --- Length of a character entity 9219@fnindex LEN 9220@cindex string, length 9221 9222@table @asis 9223@item @emph{Description}: 9224Returns the length of a character string. If @var{STRING} is an array, 9225the length of an element of @var{STRING} is returned. Note that 9226@var{STRING} need not be defined when this intrinsic is invoked, since 9227only the length, not the content, of @var{STRING} is needed. 9228 9229@item @emph{Standard}: 9230Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 9231 9232@item @emph{Class}: 9233Inquiry function 9234 9235@item @emph{Syntax}: 9236@code{L = LEN(STRING [, KIND])} 9237 9238@item @emph{Arguments}: 9239@multitable @columnfractions .15 .70 9240@item @var{STRING} @tab Shall be a scalar or array of type 9241@code{CHARACTER}, with @code{INTENT(IN)} 9242@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9243expression indicating the kind parameter of the result. 9244@end multitable 9245 9246@item @emph{Return value}: 9247The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9248@var{KIND} is absent, the return value is of default integer kind. 9249 9250 9251@item @emph{Specific names}: 9252@multitable @columnfractions .20 .23 .20 .33 9253@headitem Name @tab Argument @tab Return type @tab Standard 9254@item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later 9255@end multitable 9256 9257 9258@item @emph{See also}: 9259@ref{LEN_TRIM}, @gol 9260@ref{ADJUSTL}, @gol 9261@ref{ADJUSTR} 9262@end table 9263 9264 9265 9266@node LEN_TRIM 9267@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters 9268@fnindex LEN_TRIM 9269@cindex string, length, without trailing whitespace 9270 9271@table @asis 9272@item @emph{Description}: 9273Returns the length of a character string, ignoring any trailing blanks. 9274 9275@item @emph{Standard}: 9276Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 9277 9278@item @emph{Class}: 9279Elemental function 9280 9281@item @emph{Syntax}: 9282@code{RESULT = LEN_TRIM(STRING [, KIND])} 9283 9284@item @emph{Arguments}: 9285@multitable @columnfractions .15 .70 9286@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9287with @code{INTENT(IN)} 9288@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9289expression indicating the kind parameter of the result. 9290@end multitable 9291 9292@item @emph{Return value}: 9293The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9294@var{KIND} is absent, the return value is of default integer kind. 9295 9296@item @emph{See also}: 9297@ref{LEN}, @gol 9298@ref{ADJUSTL}, @gol 9299@ref{ADJUSTR} 9300@end table 9301 9302 9303 9304@node LGE 9305@section @code{LGE} --- Lexical greater than or equal 9306@fnindex LGE 9307@cindex lexical comparison of strings 9308@cindex string, comparison 9309 9310@table @asis 9311@item @emph{Description}: 9312Determines whether one string is lexically greater than or equal to 9313another string, where the two strings are interpreted as containing 9314ASCII character codes. If the String A and String B are not the same 9315length, the shorter is compared as if spaces were appended to it to form 9316a value that has the same length as the longer. 9317 9318In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9319@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9320operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9321that the latter use the processor's character ordering (which is not 9322ASCII on some targets), whereas the former always use the ASCII 9323ordering. 9324 9325@item @emph{Standard}: 9326Fortran 77 and later 9327 9328@item @emph{Class}: 9329Elemental function 9330 9331@item @emph{Syntax}: 9332@code{RESULT = LGE(STRING_A, STRING_B)} 9333 9334@item @emph{Arguments}: 9335@multitable @columnfractions .15 .70 9336@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9337@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9338@end multitable 9339 9340@item @emph{Return value}: 9341Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.} 9342otherwise, based on the ASCII ordering. 9343 9344@item @emph{Specific names}: 9345@multitable @columnfractions .34 .16 .17 .30 9346@headitem Name @tab Argument @tab Return type @tab Standard 9347@item @code{LGE(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9348@end multitable 9349 9350@item @emph{See also}: 9351@ref{LGT}, @gol 9352@ref{LLE}, @gol 9353@ref{LLT} 9354@end table 9355 9356 9357 9358@node LGT 9359@section @code{LGT} --- Lexical greater than 9360@fnindex LGT 9361@cindex lexical comparison of strings 9362@cindex string, comparison 9363 9364@table @asis 9365@item @emph{Description}: 9366Determines whether one string is lexically greater than another string, 9367where the two strings are interpreted as containing ASCII character 9368codes. If the String A and String B are not the same length, the 9369shorter is compared as if spaces were appended to it to form a value 9370that has the same length as the longer. 9371 9372In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9373@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9374operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9375that the latter use the processor's character ordering (which is not 9376ASCII on some targets), whereas the former always use the ASCII 9377ordering. 9378 9379@item @emph{Standard}: 9380Fortran 77 and later 9381 9382@item @emph{Class}: 9383Elemental function 9384 9385@item @emph{Syntax}: 9386@code{RESULT = LGT(STRING_A, STRING_B)} 9387 9388@item @emph{Arguments}: 9389@multitable @columnfractions .15 .70 9390@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9391@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9392@end multitable 9393 9394@item @emph{Return value}: 9395Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.} 9396otherwise, based on the ASCII ordering. 9397 9398@item @emph{Specific names}: 9399@multitable @columnfractions .34 .16 .17 .30 9400@headitem Name @tab Argument @tab Return type @tab Standard 9401@item @code{LGT(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9402@end multitable 9403 9404@item @emph{See also}: 9405@ref{LGE}, @gol 9406@ref{LLE}, @gol 9407@ref{LLT} 9408@end table 9409 9410 9411 9412@node LINK 9413@section @code{LINK} --- Create a hard link 9414@fnindex LINK 9415@cindex file system, create link 9416@cindex file system, hard link 9417 9418@table @asis 9419@item @emph{Description}: 9420Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null 9421character (@code{CHAR(0)}) can be used to mark the end of the names in 9422@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 9423names are ignored. If the @var{STATUS} argument is supplied, it 9424contains 0 on success or a nonzero error code upon return; see 9425@code{link(2)}. 9426 9427This intrinsic is provided in both subroutine and function forms; 9428however, only one form can be used in any given program unit. 9429 9430@item @emph{Standard}: 9431GNU extension 9432 9433@item @emph{Class}: 9434Subroutine, function 9435 9436@item @emph{Syntax}: 9437@multitable @columnfractions .80 9438@item @code{CALL LINK(PATH1, PATH2 [, STATUS])} 9439@item @code{STATUS = LINK(PATH1, PATH2)} 9440@end multitable 9441 9442@item @emph{Arguments}: 9443@multitable @columnfractions .15 .70 9444@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 9445@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 9446@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 9447@end multitable 9448 9449@item @emph{See also}: 9450@ref{SYMLNK}, @gol 9451@ref{UNLINK} 9452@end table 9453 9454 9455 9456@node LLE 9457@section @code{LLE} --- Lexical less than or equal 9458@fnindex LLE 9459@cindex lexical comparison of strings 9460@cindex string, comparison 9461 9462@table @asis 9463@item @emph{Description}: 9464Determines whether one string is lexically less than or equal to another 9465string, where the two strings are interpreted as containing ASCII 9466character codes. If the String A and String B are not the same length, 9467the shorter is compared as if spaces were appended to it to form a value 9468that has the same length as the longer. 9469 9470In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9471@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9472operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9473that the latter use the processor's character ordering (which is not 9474ASCII on some targets), whereas the former always use the ASCII 9475ordering. 9476 9477@item @emph{Standard}: 9478Fortran 77 and later 9479 9480@item @emph{Class}: 9481Elemental function 9482 9483@item @emph{Syntax}: 9484@code{RESULT = LLE(STRING_A, STRING_B)} 9485 9486@item @emph{Arguments}: 9487@multitable @columnfractions .15 .70 9488@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9489@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9490@end multitable 9491 9492@item @emph{Return value}: 9493Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.} 9494otherwise, based on the ASCII ordering. 9495 9496@item @emph{Specific names}: 9497@multitable @columnfractions .34 .16 .17 .30 9498@headitem Name @tab Argument @tab Return type @tab Standard 9499@item @code{LLE(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9500@end multitable 9501 9502@item @emph{See also}: 9503@ref{LGE}, @gol 9504@ref{LGT}, @gol 9505@ref{LLT} 9506@end table 9507 9508 9509 9510@node LLT 9511@section @code{LLT} --- Lexical less than 9512@fnindex LLT 9513@cindex lexical comparison of strings 9514@cindex string, comparison 9515 9516@table @asis 9517@item @emph{Description}: 9518Determines whether one string is lexically less than another string, 9519where the two strings are interpreted as containing ASCII character 9520codes. If the String A and String B are not the same length, the 9521shorter is compared as if spaces were appended to it to form a value 9522that has the same length as the longer. 9523 9524In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9525@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9526operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9527that the latter use the processor's character ordering (which is not 9528ASCII on some targets), whereas the former always use the ASCII 9529ordering. 9530 9531@item @emph{Standard}: 9532Fortran 77 and later 9533 9534@item @emph{Class}: 9535Elemental function 9536 9537@item @emph{Syntax}: 9538@code{RESULT = LLT(STRING_A, STRING_B)} 9539 9540@item @emph{Arguments}: 9541@multitable @columnfractions .15 .70 9542@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9543@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9544@end multitable 9545 9546@item @emph{Return value}: 9547Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.} 9548otherwise, based on the ASCII ordering. 9549 9550@item @emph{Specific names}: 9551@multitable @columnfractions .34 .16 .17 .30 9552@headitem Name @tab Argument @tab Return type @tab Standard 9553@item @code{LLT(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9554@end multitable 9555 9556@item @emph{See also}: 9557@ref{LGE}, @gol 9558@ref{LGT}, @gol 9559@ref{LLE} 9560@end table 9561 9562 9563 9564@node LNBLNK 9565@section @code{LNBLNK} --- Index of the last non-blank character in a string 9566@fnindex LNBLNK 9567@cindex string, find non-blank character 9568 9569@table @asis 9570@item @emph{Description}: 9571Returns the length of a character string, ignoring any trailing blanks. 9572This is identical to the standard @code{LEN_TRIM} intrinsic, and is only 9573included for backwards compatibility. 9574 9575@item @emph{Standard}: 9576GNU extension 9577 9578@item @emph{Class}: 9579Elemental function 9580 9581@item @emph{Syntax}: 9582@code{RESULT = LNBLNK(STRING)} 9583 9584@item @emph{Arguments}: 9585@multitable @columnfractions .15 .70 9586@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9587with @code{INTENT(IN)} 9588@end multitable 9589 9590@item @emph{Return value}: 9591The return value is of @code{INTEGER(kind=4)} type. 9592 9593@item @emph{See also}: 9594@ref{INDEX intrinsic}, @gol 9595@ref{LEN_TRIM} 9596@end table 9597 9598 9599 9600@node LOC 9601@section @code{LOC} --- Returns the address of a variable 9602@fnindex LOC 9603@cindex location of a variable in memory 9604 9605@table @asis 9606@item @emph{Description}: 9607@code{LOC(X)} returns the address of @var{X} as an integer. 9608 9609@item @emph{Standard}: 9610GNU extension 9611 9612@item @emph{Class}: 9613Inquiry function 9614 9615@item @emph{Syntax}: 9616@code{RESULT = LOC(X)} 9617 9618@item @emph{Arguments}: 9619@multitable @columnfractions .15 .70 9620@item @var{X} @tab Variable of any type. 9621@end multitable 9622 9623@item @emph{Return value}: 9624The return value is of type @code{INTEGER}, with a @code{KIND} 9625corresponding to the size (in bytes) of a memory address on the target 9626machine. 9627 9628@item @emph{Example}: 9629@smallexample 9630program test_loc 9631 integer :: i 9632 real :: r 9633 i = loc(r) 9634 print *, i 9635end program test_loc 9636@end smallexample 9637@end table 9638 9639 9640 9641@node LOG 9642@section @code{LOG} --- Natural logarithm function 9643@fnindex LOG 9644@fnindex ALOG 9645@fnindex DLOG 9646@fnindex CLOG 9647@fnindex ZLOG 9648@fnindex CDLOG 9649@cindex exponential function, inverse 9650@cindex logarithm function 9651@cindex natural logarithm function 9652 9653@table @asis 9654@item @emph{Description}: 9655@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the 9656logarithm to the base @math{e}. 9657 9658@item @emph{Standard}: 9659Fortran 77 and later, has GNU extensions 9660 9661@item @emph{Class}: 9662Elemental function 9663 9664@item @emph{Syntax}: 9665@code{RESULT = LOG(X)} 9666 9667@item @emph{Arguments}: 9668@multitable @columnfractions .15 .70 9669@item @var{X} @tab The type shall be @code{REAL} or 9670@code{COMPLEX}. 9671@end multitable 9672 9673@item @emph{Return value}: 9674The return value is of type @code{REAL} or @code{COMPLEX}. 9675The kind type parameter is the same as @var{X}. 9676If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range 9677@math{-\pi < \omega \leq \pi}. 9678 9679@item @emph{Example}: 9680@smallexample 9681program test_log 9682 real(8) :: x = 2.7182818284590451_8 9683 complex :: z = (1.0, 2.0) 9684 x = log(x) ! will yield (approximately) 1 9685 z = log(z) 9686end program test_log 9687@end smallexample 9688 9689@item @emph{Specific names}: 9690@multitable @columnfractions .20 .23 .20 .33 9691@headitem Name @tab Argument @tab Return type @tab Standard 9692@item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later 9693@item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later 9694@item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later 9695@item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 9696@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 9697@end multitable 9698@end table 9699 9700 9701 9702@node LOG10 9703@section @code{LOG10} --- Base 10 logarithm function 9704@fnindex LOG10 9705@fnindex ALOG10 9706@fnindex DLOG10 9707@cindex exponential function, inverse 9708@cindex logarithm function with base 10 9709@cindex base 10 logarithm function 9710 9711@table @asis 9712@item @emph{Description}: 9713@code{LOG10(X)} computes the base 10 logarithm of @var{X}. 9714 9715@item @emph{Standard}: 9716Fortran 77 and later 9717 9718@item @emph{Class}: 9719Elemental function 9720 9721@item @emph{Syntax}: 9722@code{RESULT = LOG10(X)} 9723 9724@item @emph{Arguments}: 9725@multitable @columnfractions .15 .70 9726@item @var{X} @tab The type shall be @code{REAL}. 9727@end multitable 9728 9729@item @emph{Return value}: 9730The return value is of type @code{REAL} or @code{COMPLEX}. 9731The kind type parameter is the same as @var{X}. 9732 9733@item @emph{Example}: 9734@smallexample 9735program test_log10 9736 real(8) :: x = 10.0_8 9737 x = log10(x) 9738end program test_log10 9739@end smallexample 9740 9741@item @emph{Specific names}: 9742@multitable @columnfractions .20 .23 .20 .33 9743@headitem Name @tab Argument @tab Return type @tab Standard 9744@item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 9745@item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 9746@end multitable 9747@end table 9748 9749 9750 9751@node LOG_GAMMA 9752@section @code{LOG_GAMMA} --- Logarithm of the Gamma function 9753@fnindex LOG_GAMMA 9754@fnindex LGAMMA 9755@fnindex ALGAMA 9756@fnindex DLGAMA 9757@cindex Gamma function, logarithm of 9758 9759@table @asis 9760@item @emph{Description}: 9761@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value 9762of the Gamma (@math{\Gamma}) function. 9763 9764@item @emph{Standard}: 9765Fortran 2008 and later 9766 9767@item @emph{Class}: 9768Elemental function 9769 9770@item @emph{Syntax}: 9771@code{X = LOG_GAMMA(X)} 9772 9773@item @emph{Arguments}: 9774@multitable @columnfractions .15 .70 9775@item @var{X} @tab Shall be of type @code{REAL} and neither zero 9776nor a negative integer. 9777@end multitable 9778 9779@item @emph{Return value}: 9780The return value is of type @code{REAL} of the same kind as @var{X}. 9781 9782@item @emph{Example}: 9783@smallexample 9784program test_log_gamma 9785 real :: x = 1.0 9786 x = lgamma(x) ! returns 0.0 9787end program test_log_gamma 9788@end smallexample 9789 9790@item @emph{Specific names}: 9791@multitable @columnfractions .20 .23 .20 .33 9792@headitem Name @tab Argument @tab Return type @tab Standard 9793@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 9794@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 9795@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 9796@end multitable 9797 9798@item @emph{See also}: 9799Gamma function: @gol 9800@ref{GAMMA} 9801@end table 9802 9803 9804 9805@node LOGICAL 9806@section @code{LOGICAL} --- Convert to logical type 9807@fnindex LOGICAL 9808@cindex conversion, to logical 9809 9810@table @asis 9811@item @emph{Description}: 9812Converts one kind of @code{LOGICAL} variable to another. 9813 9814@item @emph{Standard}: 9815Fortran 90 and later 9816 9817@item @emph{Class}: 9818Elemental function 9819 9820@item @emph{Syntax}: 9821@code{RESULT = LOGICAL(L [, KIND])} 9822 9823@item @emph{Arguments}: 9824@multitable @columnfractions .15 .70 9825@item @var{L} @tab The type shall be @code{LOGICAL}. 9826@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9827expression indicating the kind parameter of the result. 9828@end multitable 9829 9830@item @emph{Return value}: 9831The return value is a @code{LOGICAL} value equal to @var{L}, with a 9832kind corresponding to @var{KIND}, or of the default logical kind if 9833@var{KIND} is not given. 9834 9835@item @emph{See also}: 9836@ref{INT}, @gol 9837@ref{REAL}, @gol 9838@ref{CMPLX} 9839@end table 9840 9841 9842 9843@node LSHIFT 9844@section @code{LSHIFT} --- Left shift bits 9845@fnindex LSHIFT 9846@cindex bits, shift left 9847 9848@table @asis 9849@item @emph{Description}: 9850@code{LSHIFT} returns a value corresponding to @var{I} with all of the 9851bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be 9852nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 9853the result value is undefined. Bits shifted out from the left end are 9854lost; zeros are shifted in from the opposite end. 9855 9856This function has been superseded by the @code{ISHFT} intrinsic, which 9857is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic, 9858which is standard in Fortran 2008 and later. 9859 9860@item @emph{Standard}: 9861GNU extension 9862 9863@item @emph{Class}: 9864Elemental function 9865 9866@item @emph{Syntax}: 9867@code{RESULT = LSHIFT(I, SHIFT)} 9868 9869@item @emph{Arguments}: 9870@multitable @columnfractions .15 .70 9871@item @var{I} @tab The type shall be @code{INTEGER}. 9872@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 9873@end multitable 9874 9875@item @emph{Return value}: 9876The return value is of type @code{INTEGER} and of the same kind as 9877@var{I}. 9878 9879@item @emph{See also}: 9880@ref{ISHFT}, @gol 9881@ref{ISHFTC}, @gol 9882@ref{RSHIFT}, @gol 9883@ref{SHIFTA}, @gol 9884@ref{SHIFTL}, @gol 9885@ref{SHIFTR} 9886@end table 9887 9888 9889 9890@node LSTAT 9891@section @code{LSTAT} --- Get file status 9892@fnindex LSTAT 9893@cindex file system, file status 9894 9895@table @asis 9896@item @emph{Description}: 9897@code{LSTAT} is identical to @ref{STAT}, except that if path is a 9898symbolic link, then the link itself is statted, not the file that it 9899refers to. 9900 9901The elements in @code{VALUES} are the same as described by @ref{STAT}. 9902 9903This intrinsic is provided in both subroutine and function forms; 9904however, only one form can be used in any given program unit. 9905 9906@item @emph{Standard}: 9907GNU extension 9908 9909@item @emph{Class}: 9910Subroutine, function 9911 9912@item @emph{Syntax}: 9913@multitable @columnfractions .80 9914@item @code{CALL LSTAT(NAME, VALUES [, STATUS])} 9915@item @code{STATUS = LSTAT(NAME, VALUES)} 9916@end multitable 9917 9918@item @emph{Arguments}: 9919@multitable @columnfractions .15 .70 9920@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default 9921kind, a valid path within the file system. 9922@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 9923@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. 9924Returns 0 on success and a system specific error code otherwise. 9925@end multitable 9926 9927@item @emph{Example}: 9928See @ref{STAT} for an example. 9929 9930@item @emph{See also}: 9931To stat an open file: @gol 9932@ref{FSTAT} @gol 9933To stat a file: @gol 9934@ref{STAT} 9935@end table 9936 9937 9938 9939@node LTIME 9940@section @code{LTIME} --- Convert time to local time info 9941@fnindex LTIME 9942@cindex time, conversion to local time info 9943 9944@table @asis 9945@item @emph{Description}: 9946Given a system time value @var{TIME} (as provided by the @ref{TIME} 9947intrinsic), fills @var{VALUES} with values extracted from it appropriate 9948to the local time zone using @code{localtime(3)}. 9949 9950This intrinsic routine is provided for backwards compatibility with 9951GNU Fortran 77. In new code, programmers should consider the use of 9952the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 9953standard. 9954 9955@item @emph{Standard}: 9956GNU extension 9957 9958@item @emph{Class}: 9959Subroutine 9960 9961@item @emph{Syntax}: 9962@code{CALL LTIME(TIME, VALUES)} 9963 9964@item @emph{Arguments}: 9965@multitable @columnfractions .15 .70 9966@item @var{TIME} @tab An @code{INTEGER} scalar expression 9967corresponding to a system time, with @code{INTENT(IN)}. 9968@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 9969with @code{INTENT(OUT)}. 9970@end multitable 9971 9972@item @emph{Return value}: 9973The elements of @var{VALUES} are assigned as follows: 9974@enumerate 9975@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 9976seconds 9977@item Minutes after the hour, range 0--59 9978@item Hours past midnight, range 0--23 9979@item Day of month, range 1--31 9980@item Number of months since January, range 0--11 9981@item Years since 1900 9982@item Number of days since Sunday, range 0--6 9983@item Days since January 1, range 0--365 9984@item Daylight savings indicator: positive if daylight savings is in 9985effect, zero if not, and negative if the information is not available. 9986@end enumerate 9987 9988@item @emph{See also}: 9989@ref{DATE_AND_TIME}, @gol 9990@ref{CTIME}, @gol 9991@ref{GMTIME}, @gol 9992@ref{TIME}, @gol 9993@ref{TIME8} 9994@end table 9995 9996 9997 9998@node MALLOC 9999@section @code{MALLOC} --- Allocate dynamic memory 10000@fnindex MALLOC 10001@cindex pointer, cray 10002 10003@table @asis 10004@item @emph{Description}: 10005@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and 10006returns the address of the allocated memory. The @code{MALLOC} intrinsic 10007is an extension intended to be used with Cray pointers, and is provided 10008in GNU Fortran to allow the user to compile legacy code. For new code 10009using Fortran 95 pointers, the memory allocation intrinsic is 10010@code{ALLOCATE}. 10011 10012@item @emph{Standard}: 10013GNU extension 10014 10015@item @emph{Class}: 10016Function 10017 10018@item @emph{Syntax}: 10019@code{PTR = MALLOC(SIZE)} 10020 10021@item @emph{Arguments}: 10022@multitable @columnfractions .15 .70 10023@item @var{SIZE} @tab The type shall be @code{INTEGER}. 10024@end multitable 10025 10026@item @emph{Return value}: 10027The return value is of type @code{INTEGER(K)}, with @var{K} such that 10028variables of type @code{INTEGER(K)} have the same size as 10029C pointers (@code{sizeof(void *)}). 10030 10031@item @emph{Example}: 10032The following example demonstrates the use of @code{MALLOC} and 10033@code{FREE} with Cray pointers. 10034 10035@smallexample 10036program test_malloc 10037 implicit none 10038 integer i 10039 real*8 x(*), z 10040 pointer(ptr_x,x) 10041 10042 ptr_x = malloc(20*8) 10043 do i = 1, 20 10044 x(i) = sqrt(1.0d0 / i) 10045 end do 10046 z = 0 10047 do i = 1, 20 10048 z = z + x(i) 10049 print *, z 10050 end do 10051 call free(ptr_x) 10052end program test_malloc 10053@end smallexample 10054 10055@item @emph{See also}: 10056@ref{FREE} 10057@end table 10058 10059 10060 10061@node MASKL 10062@section @code{MASKL} --- Left justified mask 10063@fnindex MASKL 10064@cindex mask, left justified 10065 10066@table @asis 10067@item @emph{Description}: 10068@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the 10069remaining bits set to 0. 10070 10071@item @emph{Standard}: 10072Fortran 2008 and later 10073 10074@item @emph{Class}: 10075Elemental function 10076 10077@item @emph{Syntax}: 10078@code{RESULT = MASKL(I[, KIND])} 10079 10080@item @emph{Arguments}: 10081@multitable @columnfractions .15 .70 10082@item @var{I} @tab Shall be of type @code{INTEGER}. 10083@item @var{KIND} @tab Shall be a scalar constant expression of type 10084@code{INTEGER}. 10085@end multitable 10086 10087@item @emph{Return value}: 10088The return value is of type @code{INTEGER}. If @var{KIND} is present, it 10089specifies the kind value of the return type; otherwise, it is of the 10090default integer kind. 10091 10092@item @emph{See also}: 10093@ref{MASKR} 10094@end table 10095 10096 10097 10098@node MASKR 10099@section @code{MASKR} --- Right justified mask 10100@fnindex MASKR 10101@cindex mask, right justified 10102 10103@table @asis 10104@item @emph{Description}: 10105@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the 10106remaining bits set to 0. 10107 10108@item @emph{Standard}: 10109Fortran 2008 and later 10110 10111@item @emph{Class}: 10112Elemental function 10113 10114@item @emph{Syntax}: 10115@code{RESULT = MASKR(I[, KIND])} 10116 10117@item @emph{Arguments}: 10118@multitable @columnfractions .15 .70 10119@item @var{I} @tab Shall be of type @code{INTEGER}. 10120@item @var{KIND} @tab Shall be a scalar constant expression of type 10121@code{INTEGER}. 10122@end multitable 10123 10124@item @emph{Return value}: 10125The return value is of type @code{INTEGER}. If @var{KIND} is present, it 10126specifies the kind value of the return type; otherwise, it is of the 10127default integer kind. 10128 10129@item @emph{See also}: 10130@ref{MASKL} 10131@end table 10132 10133 10134 10135@node MATMUL 10136@section @code{MATMUL} --- matrix multiplication 10137@fnindex MATMUL 10138@cindex matrix multiplication 10139@cindex product, matrix 10140 10141@table @asis 10142@item @emph{Description}: 10143Performs a matrix multiplication on numeric or logical arguments. 10144 10145@item @emph{Standard}: 10146Fortran 90 and later 10147 10148@item @emph{Class}: 10149Transformational function 10150 10151@item @emph{Syntax}: 10152@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)} 10153 10154@item @emph{Arguments}: 10155@multitable @columnfractions .15 .70 10156@item @var{MATRIX_A} @tab An array of @code{INTEGER}, 10157@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of 10158one or two. 10159@item @var{MATRIX_B} @tab An array of @code{INTEGER}, 10160@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric 10161type; otherwise, an array of @code{LOGICAL} type. The rank shall be one 10162or two, and the first (or only) dimension of @var{MATRIX_B} shall be 10163equal to the last (or only) dimension of @var{MATRIX_A}. 10164@var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays. 10165@end multitable 10166 10167@item @emph{Return value}: 10168The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and 10169kind of the result follow the usual type and kind promotion rules, as 10170for the @code{*} or @code{.AND.} operators. 10171@end table 10172 10173 10174 10175@node MAX 10176@section @code{MAX} --- Maximum value of an argument list 10177@fnindex MAX 10178@fnindex MAX0 10179@fnindex AMAX0 10180@fnindex MAX1 10181@fnindex AMAX1 10182@fnindex DMAX1 10183@cindex maximum value 10184 10185@table @asis 10186@item @emph{Description}: 10187Returns the argument with the largest (most positive) value. 10188 10189@item @emph{Standard}: 10190Fortran 77 and later 10191 10192@item @emph{Class}: 10193Elemental function 10194 10195@item @emph{Syntax}: 10196@code{RESULT = MAX(A1, A2 [, A3 [, ...]])} 10197 10198@item @emph{Arguments}: 10199@multitable @columnfractions .15 .70 10200@item @var{A1} @tab The type shall be @code{INTEGER} or 10201@code{REAL}. 10202@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10203as @var{A1}. (As a GNU extension, arguments of different kinds are 10204permitted.) 10205@end multitable 10206 10207@item @emph{Return value}: 10208The return value corresponds to the maximum value among the arguments, 10209and has the same type and kind as the first argument. 10210 10211@item @emph{Specific names}: 10212@multitable @columnfractions .20 .23 .20 .33 10213@headitem Name @tab Argument @tab Return type @tab Standard 10214@item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10215@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later 10216@item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later 10217@item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10218@item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10219@end multitable 10220 10221@item @emph{See also}: 10222@ref{MAXLOC} @gol 10223@ref{MAXVAL}, @gol 10224@ref{MIN} 10225@end table 10226 10227 10228 10229@node MAXEXPONENT 10230@section @code{MAXEXPONENT} --- Maximum exponent of a real kind 10231@fnindex MAXEXPONENT 10232@cindex model representation, maximum exponent 10233 10234@table @asis 10235@item @emph{Description}: 10236@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the 10237type of @code{X}. 10238 10239@item @emph{Standard}: 10240Fortran 90 and later 10241 10242@item @emph{Class}: 10243Inquiry function 10244 10245@item @emph{Syntax}: 10246@code{RESULT = MAXEXPONENT(X)} 10247 10248@item @emph{Arguments}: 10249@multitable @columnfractions .15 .70 10250@item @var{X} @tab Shall be of type @code{REAL}. 10251@end multitable 10252 10253@item @emph{Return value}: 10254The return value is of type @code{INTEGER} and of the default integer 10255kind. 10256 10257@item @emph{Example}: 10258@smallexample 10259program exponents 10260 real(kind=4) :: x 10261 real(kind=8) :: y 10262 10263 print *, minexponent(x), maxexponent(x) 10264 print *, minexponent(y), maxexponent(y) 10265end program exponents 10266@end smallexample 10267@end table 10268 10269 10270 10271@node MAXLOC 10272@section @code{MAXLOC} --- Location of the maximum value within an array 10273@fnindex MAXLOC 10274@cindex array, location of maximum element 10275 10276@table @asis 10277@item @emph{Description}: 10278Determines the location of the element in the array with the maximum 10279value, or, if the @var{DIM} argument is supplied, determines the 10280locations of the maximum element along each row of the array in the 10281@var{DIM} direction. If @var{MASK} is present, only the elements for 10282which @var{MASK} is @code{.TRUE.} are considered. If more than one 10283element in the array has the maximum value, the location returned is 10284that of the first such element in array element order if the 10285@var{BACK} is not present, or is false; if @var{BACK} is true, the location 10286returned is that of the last such element. If the array has zero 10287size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10288the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10289and all of the elements of @var{MASK} along a given row are zero, the 10290result value for that row is zero. 10291 10292@item @emph{Standard}: 10293Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the 10294@var{KIND} argument are available in Fortran 2003 and later. 10295The @var{BACK} argument is available in Fortran 2008 and later. 10296 10297@item @emph{Class}: 10298Transformational function 10299 10300@item @emph{Syntax}: 10301@multitable @columnfractions .80 10302@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} 10303@item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])} 10304@end multitable 10305 10306@item @emph{Arguments}: 10307@multitable @columnfractions .15 .70 10308@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10309@code{REAL}. 10310@item @var{DIM} @tab (Optional) Shall be a scalar of type 10311@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10312inclusive. It may not be an optional dummy argument. 10313@item @var{MASK} @tab Shall be of type @code{LOGICAL}, 10314and conformable with @var{ARRAY}. 10315@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10316expression indicating the kind parameter of the result. 10317@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 10318@end multitable 10319 10320@item @emph{Return value}: 10321If @var{DIM} is absent, the result is a rank-one array with a length 10322equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10323is an array with a rank one less than the rank of @var{ARRAY}, and a 10324size corresponding to the size of @var{ARRAY} with the @var{DIM} 10325dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10326of one, the result is a scalar. If the optional argument @var{KIND} 10327is present, the result is an integer of kind @var{KIND}, otherwise it 10328is of default kind. 10329 10330@item @emph{See also}: 10331@ref{FINDLOC}, @gol 10332@ref{MAX}, @gol 10333@ref{MAXVAL} 10334@end table 10335 10336 10337 10338@node MAXVAL 10339@section @code{MAXVAL} --- Maximum value of an array 10340@fnindex MAXVAL 10341@cindex array, maximum value 10342@cindex maximum value 10343 10344@table @asis 10345@item @emph{Description}: 10346Determines the maximum value of the elements in an array value, or, if 10347the @var{DIM} argument is supplied, determines the maximum value along 10348each row of the array in the @var{DIM} direction. If @var{MASK} is 10349present, only the elements for which @var{MASK} is @code{.TRUE.} are 10350considered. If the array has zero size, or all of the elements of 10351@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)} 10352if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character 10353type. 10354 10355@item @emph{Standard}: 10356Fortran 90 and later 10357 10358@item @emph{Class}: 10359Transformational function 10360 10361@item @emph{Syntax}: 10362@multitable @columnfractions .80 10363@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])} 10364@item @code{RESULT = MAXVAL(ARRAY [, MASK])} 10365@end multitable 10366 10367@item @emph{Arguments}: 10368@multitable @columnfractions .15 .70 10369@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10370@code{REAL}. 10371@item @var{DIM} @tab (Optional) Shall be a scalar of type 10372@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10373inclusive. It may not be an optional dummy argument. 10374@item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL}, 10375and conformable with @var{ARRAY}. 10376@end multitable 10377 10378@item @emph{Return value}: 10379If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10380is a scalar. If @var{DIM} is present, the result is an array with a 10381rank one less than the rank of @var{ARRAY}, and a size corresponding to 10382the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10383cases, the result is of the same type and kind as @var{ARRAY}. 10384 10385@item @emph{See also}: 10386@ref{MAX}, @gol 10387@ref{MAXLOC} 10388@end table 10389 10390 10391 10392@node MCLOCK 10393@section @code{MCLOCK} --- Time function 10394@fnindex MCLOCK 10395@cindex time, clock ticks 10396@cindex clock ticks 10397 10398@table @asis 10399@item @emph{Description}: 10400Returns the number of clock ticks since the start of the process, based 10401on the function @code{clock(3)} in the C standard library. 10402 10403This intrinsic is not fully portable, such as to systems with 32-bit 10404@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 10405the values returned by this intrinsic might be, or become, negative, or 10406numerically less than previous values, during a single run of the 10407compiled program. 10408 10409@item @emph{Standard}: 10410GNU extension 10411 10412@item @emph{Class}: 10413Function 10414 10415@item @emph{Syntax}: 10416@code{RESULT = MCLOCK()} 10417 10418@item @emph{Return value}: 10419The return value is a scalar of type @code{INTEGER(4)}, equal to the 10420number of clock ticks since the start of the process, or @code{-1} if 10421the system does not support @code{clock(3)}. 10422 10423@item @emph{See also}: 10424@ref{CTIME}, @gol 10425@ref{GMTIME}, @gol 10426@ref{LTIME}, @gol 10427@ref{MCLOCK}, @gol 10428@ref{TIME} 10429@end table 10430 10431 10432 10433@node MCLOCK8 10434@section @code{MCLOCK8} --- Time function (64-bit) 10435@fnindex MCLOCK8 10436@cindex time, clock ticks 10437@cindex clock ticks 10438 10439@table @asis 10440@item @emph{Description}: 10441Returns the number of clock ticks since the start of the process, based 10442on the function @code{clock(3)} in the C standard library. 10443 10444@emph{Warning:} this intrinsic does not increase the range of the timing 10445values over that returned by @code{clock(3)}. On a system with a 32-bit 10446@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though 10447it is converted to a 64-bit @code{INTEGER(8)} value. That means 10448overflows of the 32-bit value can still occur. Therefore, the values 10449returned by this intrinsic might be or become negative or numerically 10450less than previous values during a single run of the compiled program. 10451 10452@item @emph{Standard}: 10453GNU extension 10454 10455@item @emph{Class}: 10456Function 10457 10458@item @emph{Syntax}: 10459@code{RESULT = MCLOCK8()} 10460 10461@item @emph{Return value}: 10462The return value is a scalar of type @code{INTEGER(8)}, equal to the 10463number of clock ticks since the start of the process, or @code{-1} if 10464the system does not support @code{clock(3)}. 10465 10466@item @emph{See also}: 10467@ref{CTIME}, @gol 10468@ref{GMTIME}, @gol 10469@ref{LTIME}, @gol 10470@ref{MCLOCK}, @gol 10471@ref{TIME8} 10472@end table 10473 10474 10475 10476@node MERGE 10477@section @code{MERGE} --- Merge variables 10478@fnindex MERGE 10479@cindex array, merge arrays 10480@cindex array, combine arrays 10481 10482@table @asis 10483@item @emph{Description}: 10484Select values from two arrays according to a logical mask. The result 10485is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to 10486@var{FSOURCE} if it is @code{.FALSE.}. 10487 10488@item @emph{Standard}: 10489Fortran 90 and later 10490 10491@item @emph{Class}: 10492Elemental function 10493 10494@item @emph{Syntax}: 10495@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)} 10496 10497@item @emph{Arguments}: 10498@multitable @columnfractions .15 .70 10499@item @var{TSOURCE} @tab May be of any type. 10500@item @var{FSOURCE} @tab Shall be of the same type and type parameters 10501as @var{TSOURCE}. 10502@item @var{MASK} @tab Shall be of type @code{LOGICAL}. 10503@end multitable 10504 10505@item @emph{Return value}: 10506The result is of the same type and type parameters as @var{TSOURCE}. 10507 10508@end table 10509 10510 10511 10512@node MERGE_BITS 10513@section @code{MERGE_BITS} --- Merge of bits under mask 10514@fnindex MERGE_BITS 10515@cindex bits, merge 10516 10517@table @asis 10518@item @emph{Description}: 10519@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J} 10520as determined by the mask. The i-th bit of the result is equal to the 10521i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to 10522the i-th bit of @var{J} otherwise. 10523 10524@item @emph{Standard}: 10525Fortran 2008 and later 10526 10527@item @emph{Class}: 10528Elemental function 10529 10530@item @emph{Syntax}: 10531@code{RESULT = MERGE_BITS(I, J, MASK)} 10532 10533@item @emph{Arguments}: 10534@multitable @columnfractions .15 .70 10535@item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant. 10536@item @var{J} @tab Shall be of type @code{INTEGER} with the same 10537kind type parameter as @var{I} or a boz-literal-constant. 10538@var{I} and @var{J} shall not both be boz-literal-constants. 10539@item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant 10540and of the same kind as @var{I}. 10541@end multitable 10542 10543@item @emph{Return value}: 10544The result is of the same type and kind as @var{I}. 10545 10546@end table 10547 10548 10549 10550@node MIN 10551@section @code{MIN} --- Minimum value of an argument list 10552@fnindex MIN 10553@fnindex MIN0 10554@fnindex AMIN0 10555@fnindex MIN1 10556@fnindex AMIN1 10557@fnindex DMIN1 10558@cindex minimum value 10559 10560@table @asis 10561@item @emph{Description}: 10562Returns the argument with the smallest (most negative) value. 10563 10564@item @emph{Standard}: 10565Fortran 77 and later 10566 10567@item @emph{Class}: 10568Elemental function 10569 10570@item @emph{Syntax}: 10571@code{RESULT = MIN(A1, A2 [, A3, ...])} 10572 10573@item @emph{Arguments}: 10574@multitable @columnfractions .15 .70 10575@item @var{A1} @tab The type shall be @code{INTEGER} or 10576@code{REAL}. 10577@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10578as @var{A1}. (As a GNU extension, arguments of different kinds are 10579permitted.) 10580@end multitable 10581 10582@item @emph{Return value}: 10583The return value corresponds to the minimum value among the arguments, 10584and has the same type and kind as the first argument. 10585 10586@item @emph{Specific names}: 10587@multitable @columnfractions .20 .23 .20 .33 10588@headitem Name @tab Argument @tab Return type @tab Standard 10589@item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10590@item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10591@item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10592@item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10593@item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10594@end multitable 10595 10596@item @emph{See also}: 10597@ref{MAX}, @gol 10598@ref{MINLOC}, @gol 10599@ref{MINVAL} 10600@end table 10601 10602 10603 10604@node MINEXPONENT 10605@section @code{MINEXPONENT} --- Minimum exponent of a real kind 10606@fnindex MINEXPONENT 10607@cindex model representation, minimum exponent 10608 10609@table @asis 10610@item @emph{Description}: 10611@code{MINEXPONENT(X)} returns the minimum exponent in the model of the 10612type of @code{X}. 10613 10614@item @emph{Standard}: 10615Fortran 90 and later 10616 10617@item @emph{Class}: 10618Inquiry function 10619 10620@item @emph{Syntax}: 10621@code{RESULT = MINEXPONENT(X)} 10622 10623@item @emph{Arguments}: 10624@multitable @columnfractions .15 .70 10625@item @var{X} @tab Shall be of type @code{REAL}. 10626@end multitable 10627 10628@item @emph{Return value}: 10629The return value is of type @code{INTEGER} and of the default integer 10630kind. 10631 10632@item @emph{Example}: 10633See @code{MAXEXPONENT} for an example. 10634@end table 10635 10636 10637 10638@node MINLOC 10639@section @code{MINLOC} --- Location of the minimum value within an array 10640@fnindex MINLOC 10641@cindex array, location of minimum element 10642 10643@table @asis 10644@item @emph{Description}: 10645Determines the location of the element in the array with the minimum 10646value, or, if the @var{DIM} argument is supplied, determines the 10647locations of the minimum element along each row of the array in the 10648@var{DIM} direction. If @var{MASK} is present, only the elements for 10649which @var{MASK} is @code{.TRUE.} are considered. If more than one 10650element in the array has the minimum value, the location returned is 10651that of the first such element in array element order if the 10652@var{BACK} is not present, or is false; if @var{BACK} is true, the location 10653returned is that of the last such element. If the array has 10654zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10655the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10656and all of the elements of @var{MASK} along a given row are zero, the 10657result value for that row is zero. 10658 10659@item @emph{Standard}: 10660Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the 10661@var{KIND} argument are available in Fortran 2003 and later. 10662The @var{BACK} argument is available in Fortran 2008 and later. 10663 10664@item @emph{Class}: 10665Transformational function 10666 10667@item @emph{Syntax}: 10668@multitable @columnfractions .80 10669@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} 10670@item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])} 10671@end multitable 10672 10673@item @emph{Arguments}: 10674@multitable @columnfractions .15 .70 10675@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 10676@code{REAL} or @code{CHARACTER}. 10677@item @var{DIM} @tab (Optional) Shall be a scalar of type 10678@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10679inclusive. It may not be an optional dummy argument. 10680@item @var{MASK} @tab Shall be of type @code{LOGICAL}, 10681and conformable with @var{ARRAY}. 10682@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10683expression indicating the kind parameter of the result. 10684@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 10685@end multitable 10686 10687@item @emph{Return value}: 10688If @var{DIM} is absent, the result is a rank-one array with a length 10689equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10690is an array with a rank one less than the rank of @var{ARRAY}, and a 10691size corresponding to the size of @var{ARRAY} with the @var{DIM} 10692dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10693of one, the result is a scalar. If the optional argument @var{KIND} 10694is present, the result is an integer of kind @var{KIND}, otherwise it 10695is of default kind. 10696 10697@item @emph{See also}: 10698@ref{FINDLOC}, @gol 10699@ref{MIN}, @gol 10700@ref{MINVAL} 10701@end table 10702 10703 10704 10705@node MINVAL 10706@section @code{MINVAL} --- Minimum value of an array 10707@fnindex MINVAL 10708@cindex array, minimum value 10709@cindex minimum value 10710 10711@table @asis 10712@item @emph{Description}: 10713Determines the minimum value of the elements in an array value, or, if 10714the @var{DIM} argument is supplied, determines the minimum value along 10715each row of the array in the @var{DIM} direction. If @var{MASK} is 10716present, only the elements for which @var{MASK} is @code{.TRUE.} are 10717considered. If the array has zero size, or all of the elements of 10718@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if 10719@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if 10720@var{ARRAY} is of character type. 10721 10722@item @emph{Standard}: 10723Fortran 90 and later 10724 10725@item @emph{Class}: 10726Transformational function 10727 10728@item @emph{Syntax}: 10729@multitable @columnfractions .80 10730@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])} 10731@item @code{RESULT = MINVAL(ARRAY [, MASK])} 10732@end multitable 10733 10734@item @emph{Arguments}: 10735@multitable @columnfractions .15 .70 10736@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10737@code{REAL}. 10738@item @var{DIM} @tab (Optional) Shall be a scalar of type 10739@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10740inclusive. It may not be an optional dummy argument. 10741@item @var{MASK} @tab Shall be of type @code{LOGICAL}, 10742and conformable with @var{ARRAY}. 10743@end multitable 10744 10745@item @emph{Return value}: 10746If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10747is a scalar. If @var{DIM} is present, the result is an array with a 10748rank one less than the rank of @var{ARRAY}, and a size corresponding to 10749the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10750cases, the result is of the same type and kind as @var{ARRAY}. 10751 10752@item @emph{See also}: 10753@ref{MIN}, @gol 10754@ref{MINLOC} 10755@end table 10756 10757 10758 10759@node MOD 10760@section @code{MOD} --- Remainder function 10761@fnindex MOD 10762@fnindex AMOD 10763@fnindex DMOD 10764@fnindex BMOD 10765@fnindex IMOD 10766@fnindex JMOD 10767@fnindex KMOD 10768@cindex remainder 10769@cindex division, remainder 10770 10771@table @asis 10772@item @emph{Description}: 10773@code{MOD(A,P)} computes the remainder of the division of A by P@. 10774 10775@item @emph{Standard}: 10776Fortran 77 and later, has overloads that are GNU extensions 10777 10778@item @emph{Class}: 10779Elemental function 10780 10781@item @emph{Syntax}: 10782@code{RESULT = MOD(A, P)} 10783 10784@item @emph{Arguments}: 10785@multitable @columnfractions .15 .70 10786@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10787@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A} 10788and not equal to zero. (As a GNU extension, arguments of different kinds are 10789permitted.) 10790@end multitable 10791 10792@item @emph{Return value}: 10793The return value is the result of @code{A - (INT(A/P) * P)}. The type 10794and kind of the return value is the same as that of the arguments. The 10795returned value has the same sign as A and a magnitude less than the 10796magnitude of P. (As a GNU extension, kind is the largest kind of the actual 10797arguments.) 10798 10799@item @emph{Example}: 10800@smallexample 10801program test_mod 10802 print *, mod(17,3) 10803 print *, mod(17.5,5.5) 10804 print *, mod(17.5d0,5.5) 10805 print *, mod(17.5,5.5d0) 10806 10807 print *, mod(-17,3) 10808 print *, mod(-17.5,5.5) 10809 print *, mod(-17.5d0,5.5) 10810 print *, mod(-17.5,5.5d0) 10811 10812 print *, mod(17,-3) 10813 print *, mod(17.5,-5.5) 10814 print *, mod(17.5d0,-5.5) 10815 print *, mod(17.5,-5.5d0) 10816end program test_mod 10817@end smallexample 10818 10819@item @emph{Specific names}: 10820@multitable @columnfractions .20 .25 .20 .31 10821@headitem Name @tab Arguments @tab Return type @tab Standard 10822@item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later 10823@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later 10824@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later 10825@item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension 10826@item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension 10827@item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension 10828@item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension 10829@end multitable 10830 10831@item @emph{See also}: 10832@ref{MODULO} 10833 10834@end table 10835 10836 10837 10838@node MODULO 10839@section @code{MODULO} --- Modulo function 10840@fnindex MODULO 10841@cindex modulo 10842@cindex division, modulo 10843 10844@table @asis 10845@item @emph{Description}: 10846@code{MODULO(A,P)} computes the @var{A} modulo @var{P}. 10847 10848@item @emph{Standard}: 10849Fortran 95 and later 10850 10851@item @emph{Class}: 10852Elemental function 10853 10854@item @emph{Syntax}: 10855@code{RESULT = MODULO(A, P)} 10856 10857@item @emph{Arguments}: 10858@multitable @columnfractions .15 .70 10859@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10860@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}. 10861It shall not be zero. (As a GNU extension, arguments of different kinds are 10862permitted.) 10863@end multitable 10864 10865@item @emph{Return value}: 10866The type and kind of the result are those of the arguments. (As a GNU 10867extension, kind is the largest kind of the actual arguments.) 10868@table @asis 10869@item If @var{A} and @var{P} are of type @code{INTEGER}: 10870@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where 10871@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P} 10872(exclusive). 10873@item If @var{A} and @var{P} are of type @code{REAL}: 10874@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}. 10875@end table 10876The returned value has the same sign as P and a magnitude less than 10877the magnitude of P. 10878 10879@item @emph{Example}: 10880@smallexample 10881program test_modulo 10882 print *, modulo(17,3) 10883 print *, modulo(17.5,5.5) 10884 10885 print *, modulo(-17,3) 10886 print *, modulo(-17.5,5.5) 10887 10888 print *, modulo(17,-3) 10889 print *, modulo(17.5,-5.5) 10890end program 10891@end smallexample 10892 10893@item @emph{See also}: 10894@ref{MOD} 10895 10896@end table 10897 10898 10899 10900@node MOVE_ALLOC 10901@section @code{MOVE_ALLOC} --- Move allocation from one object to another 10902@fnindex MOVE_ALLOC 10903@cindex moving allocation 10904@cindex allocation, moving 10905 10906@table @asis 10907@item @emph{Description}: 10908@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to 10909@var{TO}. @var{FROM} will become deallocated in the process. 10910 10911@item @emph{Standard}: 10912Fortran 2003 and later 10913 10914@item @emph{Class}: 10915Pure subroutine 10916 10917@item @emph{Syntax}: 10918@code{CALL MOVE_ALLOC(FROM, TO)} 10919 10920@item @emph{Arguments}: 10921@multitable @columnfractions .15 .70 10922@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be 10923of any type and kind. 10924@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be 10925of the same type, kind and rank as @var{FROM}. 10926@end multitable 10927 10928@item @emph{Return value}: 10929None 10930 10931@item @emph{Example}: 10932@smallexample 10933program test_move_alloc 10934 integer, allocatable :: a(:), b(:) 10935 10936 allocate(a(3)) 10937 a = [ 1, 2, 3 ] 10938 call move_alloc(a, b) 10939 print *, allocated(a), allocated(b) 10940 print *, b 10941end program test_move_alloc 10942@end smallexample 10943@end table 10944 10945 10946 10947@node MVBITS 10948@section @code{MVBITS} --- Move bits from one integer to another 10949@fnindex MVBITS 10950@fnindex BMVBITS 10951@fnindex IMVBITS 10952@fnindex JMVBITS 10953@fnindex KMVBITS 10954@cindex bits, move 10955 10956@table @asis 10957@item @emph{Description}: 10958Moves @var{LEN} bits from positions @var{FROMPOS} through 10959@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through 10960@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not 10961affected by the movement of bits is unchanged. The values of 10962@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than 10963@code{BIT_SIZE(FROM)}. 10964 10965@item @emph{Standard}: 10966Fortran 90 and later, has overloads that are GNU extensions 10967 10968@item @emph{Class}: 10969Elemental subroutine 10970 10971@item @emph{Syntax}: 10972@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)} 10973 10974@item @emph{Arguments}: 10975@multitable @columnfractions .15 .70 10976@item @var{FROM} @tab The type shall be @code{INTEGER}. 10977@item @var{FROMPOS} @tab The type shall be @code{INTEGER}. 10978@item @var{LEN} @tab The type shall be @code{INTEGER}. 10979@item @var{TO} @tab The type shall be @code{INTEGER}, of the 10980same kind as @var{FROM}. 10981@item @var{TOPOS} @tab The type shall be @code{INTEGER}. 10982@end multitable 10983 10984@item @emph{Specific names}: 10985@multitable @columnfractions .20 .23 .20 .33 10986@headitem Name @tab Argument @tab Return type @tab Standard 10987@item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 10988@item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 10989@item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 10990@item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 10991@item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 10992@end multitable 10993 10994@item @emph{See also}: 10995@ref{IBCLR}, @gol 10996@ref{IBSET}, @gol 10997@ref{IBITS}, @gol 10998@ref{IAND}, @gol 10999@ref{IOR}, @gol 11000@ref{IEOR} 11001@end table 11002 11003 11004 11005@node NEAREST 11006@section @code{NEAREST} --- Nearest representable number 11007@fnindex NEAREST 11008@cindex real number, nearest different 11009@cindex floating point, nearest different 11010 11011@table @asis 11012@item @emph{Description}: 11013@code{NEAREST(X, S)} returns the processor-representable number nearest 11014to @code{X} in the direction indicated by the sign of @code{S}. 11015 11016@item @emph{Standard}: 11017Fortran 90 and later 11018 11019@item @emph{Class}: 11020Elemental function 11021 11022@item @emph{Syntax}: 11023@code{RESULT = NEAREST(X, S)} 11024 11025@item @emph{Arguments}: 11026@multitable @columnfractions .15 .70 11027@item @var{X} @tab Shall be of type @code{REAL}. 11028@item @var{S} @tab Shall be of type @code{REAL} and 11029not equal to zero. 11030@end multitable 11031 11032@item @emph{Return value}: 11033The return value is of the same type as @code{X}. If @code{S} is 11034positive, @code{NEAREST} returns the processor-representable number 11035greater than @code{X} and nearest to it. If @code{S} is negative, 11036@code{NEAREST} returns the processor-representable number smaller than 11037@code{X} and nearest to it. 11038 11039@item @emph{Example}: 11040@smallexample 11041program test_nearest 11042 real :: x, y 11043 x = nearest(42.0, 1.0) 11044 y = nearest(42.0, -1.0) 11045 write (*,"(3(G20.15))") x, y, x - y 11046end program test_nearest 11047@end smallexample 11048@end table 11049 11050 11051 11052@node NEW_LINE 11053@section @code{NEW_LINE} --- New line character 11054@fnindex NEW_LINE 11055@cindex newline 11056@cindex output, newline 11057 11058@table @asis 11059@item @emph{Description}: 11060@code{NEW_LINE(C)} returns the new-line character. 11061 11062@item @emph{Standard}: 11063Fortran 2003 and later 11064 11065@item @emph{Class}: 11066Inquiry function 11067 11068@item @emph{Syntax}: 11069@code{RESULT = NEW_LINE(C)} 11070 11071@item @emph{Arguments}: 11072@multitable @columnfractions .15 .70 11073@item @var{C} @tab The argument shall be a scalar or array of the 11074type @code{CHARACTER}. 11075@end multitable 11076 11077@item @emph{Return value}: 11078Returns a @var{CHARACTER} scalar of length one with the new-line character of 11079the same kind as parameter @var{C}. 11080 11081@item @emph{Example}: 11082@smallexample 11083program newline 11084 implicit none 11085 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' 11086end program newline 11087@end smallexample 11088@end table 11089 11090 11091 11092@node NINT 11093@section @code{NINT} --- Nearest whole number 11094@fnindex NINT 11095@fnindex IDNINT 11096@cindex rounding, nearest whole number 11097 11098@table @asis 11099@item @emph{Description}: 11100@code{NINT(A)} rounds its argument to the nearest whole number. 11101 11102@item @emph{Standard}: 11103Fortran 77 and later, with @var{KIND} argument Fortran 90 and later 11104 11105@item @emph{Class}: 11106Elemental function 11107 11108@item @emph{Syntax}: 11109@code{RESULT = NINT(A [, KIND])} 11110 11111@item @emph{Arguments}: 11112@multitable @columnfractions .15 .70 11113@item @var{A} @tab The type of the argument shall be @code{REAL}. 11114@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 11115expression indicating the kind parameter of the result. 11116@end multitable 11117 11118@item @emph{Return value}: 11119Returns @var{A} with the fractional portion of its magnitude eliminated by 11120rounding to the nearest whole number and with its sign preserved, 11121converted to an @code{INTEGER} of the default kind. 11122 11123@item @emph{Example}: 11124@smallexample 11125program test_nint 11126 real(4) x4 11127 real(8) x8 11128 x4 = 1.234E0_4 11129 x8 = 4.321_8 11130 print *, nint(x4), idnint(x8) 11131end program test_nint 11132@end smallexample 11133 11134@item @emph{Specific names}: 11135@multitable @columnfractions .20 .23 .20 .33 11136@headitem Name @tab Argument @tab Return Type @tab Standard 11137@item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 11138@item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 11139@end multitable 11140 11141@item @emph{See also}: 11142@ref{CEILING}, @gol 11143@ref{FLOOR} 11144@end table 11145 11146 11147 11148@node NORM2 11149@section @code{NORM2} --- Euclidean vector norms 11150@fnindex NORM2 11151@cindex Euclidean vector norm 11152@cindex L2 vector norm 11153@cindex norm, Euclidean 11154 11155@table @asis 11156@item @emph{Description}: 11157Calculates the Euclidean vector norm (@math{L_2} norm) 11158of @var{ARRAY} along dimension @var{DIM}. 11159 11160@item @emph{Standard}: 11161Fortran 2008 and later 11162 11163@item @emph{Class}: 11164Transformational function 11165 11166@item @emph{Syntax}: 11167@multitable @columnfractions .80 11168@item @code{RESULT = NORM2(ARRAY[, DIM])} 11169@end multitable 11170 11171@item @emph{Arguments}: 11172@multitable @columnfractions .15 .70 11173@item @var{ARRAY} @tab Shall be an array of type @code{REAL} 11174@item @var{DIM} @tab (Optional) shall be a scalar of type 11175@code{INTEGER} with a value in the range from 1 to n, where n 11176equals the rank of @var{ARRAY}. 11177@end multitable 11178 11179@item @emph{Return value}: 11180The result is of the same type as @var{ARRAY}. 11181 11182If @var{DIM} is absent, a scalar with the square root of the sum of all 11183elements in @var{ARRAY} squared is returned. Otherwise, an array of 11184rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a 11185shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped 11186is returned. 11187 11188@item @emph{Example}: 11189@smallexample 11190PROGRAM test_sum 11191 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] 11192 print *, NORM2(x) ! = sqrt(55.) ~ 7.416 11193END PROGRAM 11194@end smallexample 11195@end table 11196 11197 11198 11199@node NOT 11200@section @code{NOT} --- Logical negation 11201@fnindex NOT 11202@fnindex BNOT 11203@fnindex INOT 11204@fnindex JNOT 11205@fnindex KNOT 11206@cindex bits, negate 11207@cindex bitwise logical not 11208@cindex logical not, bitwise 11209 11210@table @asis 11211@item @emph{Description}: 11212@code{NOT} returns the bitwise Boolean inverse of @var{I}. 11213 11214@item @emph{Standard}: 11215Fortran 90 and later, has overloads that are GNU extensions 11216 11217@item @emph{Class}: 11218Elemental function 11219 11220@item @emph{Syntax}: 11221@code{RESULT = NOT(I)} 11222 11223@item @emph{Arguments}: 11224@multitable @columnfractions .15 .70 11225@item @var{I} @tab The type shall be @code{INTEGER}. 11226@end multitable 11227 11228@item @emph{Return value}: 11229The return type is @code{INTEGER}, of the same kind as the 11230argument. 11231 11232@item @emph{Specific names}: 11233@multitable @columnfractions .20 .23 .20 .33 11234@headitem Name @tab Argument @tab Return type @tab Standard 11235@item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 11236@item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 11237@item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 11238@item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 11239@item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 11240@end multitable 11241 11242@item @emph{See also}: 11243@ref{IAND}, @gol 11244@ref{IEOR}, @gol 11245@ref{IOR}, @gol 11246@ref{IBITS}, @gol 11247@ref{IBSET}, @gol 11248@ref{IBCLR} 11249@end table 11250 11251 11252 11253@node NULL 11254@section @code{NULL} --- Function that returns an disassociated pointer 11255@fnindex NULL 11256@cindex pointer, status 11257@cindex pointer, disassociated 11258 11259@table @asis 11260@item @emph{Description}: 11261Returns a disassociated pointer. 11262 11263If @var{MOLD} is present, a disassociated pointer of the same type is 11264returned, otherwise the type is determined by context. 11265 11266In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003 11267includes cases where it is required. 11268 11269@item @emph{Standard}: 11270Fortran 95 and later 11271 11272@item @emph{Class}: 11273Transformational function 11274 11275@item @emph{Syntax}: 11276@code{PTR => NULL([MOLD])} 11277 11278@item @emph{Arguments}: 11279@multitable @columnfractions .15 .70 11280@item @var{MOLD} @tab (Optional) shall be a pointer of any association 11281status and of any type. 11282@end multitable 11283 11284@item @emph{Return value}: 11285A disassociated pointer. 11286 11287@item @emph{Example}: 11288@smallexample 11289REAL, POINTER, DIMENSION(:) :: VEC => NULL () 11290@end smallexample 11291 11292@item @emph{See also}: 11293@ref{ASSOCIATED} 11294@end table 11295 11296 11297 11298@node NUM_IMAGES 11299@section @code{NUM_IMAGES} --- Function that returns the number of images 11300@fnindex NUM_IMAGES 11301@cindex coarray, @code{NUM_IMAGES} 11302@cindex images, number of 11303 11304@table @asis 11305@item @emph{Description}: 11306Returns the number of images. 11307 11308@item @emph{Standard}: 11309Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument, 11310Technical Specification (TS) 18508 or later 11311 11312 11313@item @emph{Class}: 11314Transformational function 11315 11316@item @emph{Syntax}: 11317@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} 11318 11319@item @emph{Arguments}: 11320@multitable @columnfractions .15 .70 11321@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 11322@item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression 11323@end multitable 11324 11325@item @emph{Return value}: 11326Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, 11327the number of images in the current team is returned. For values smaller or 11328equal distance to the initial team, it returns the number of images index 11329on the ancestor team which has a distance of @var{DISTANCE} from the invoking 11330team. If @var{DISTANCE} is larger than the distance to the initial team, the 11331number of images of the initial team is returned. If @var{FAILED} is not present 11332the total number of images is returned; if it has the value @code{.TRUE.}, 11333the number of failed images is returned, otherwise, the number of images which 11334do have not the failed status. 11335 11336@item @emph{Example}: 11337@smallexample 11338INTEGER :: value[*] 11339INTEGER :: i 11340value = THIS_IMAGE() 11341SYNC ALL 11342IF (THIS_IMAGE() == 1) THEN 11343 DO i = 1, NUM_IMAGES() 11344 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 11345 END DO 11346END IF 11347@end smallexample 11348 11349@item @emph{See also}: 11350@ref{THIS_IMAGE}, @gol 11351@ref{IMAGE_INDEX} 11352@end table 11353 11354 11355 11356@node OR 11357@section @code{OR} --- Bitwise logical OR 11358@fnindex OR 11359@cindex bitwise logical or 11360@cindex logical or, bitwise 11361 11362@table @asis 11363@item @emph{Description}: 11364Bitwise logical @code{OR}. 11365 11366This intrinsic routine is provided for backwards compatibility with 11367GNU Fortran 77. For integer arguments, programmers should consider 11368the use of the @ref{IOR} intrinsic defined by the Fortran standard. 11369 11370@item @emph{Standard}: 11371GNU extension 11372 11373@item @emph{Class}: 11374Function 11375 11376@item @emph{Syntax}: 11377@code{RESULT = OR(I, J)} 11378 11379@item @emph{Arguments}: 11380@multitable @columnfractions .15 .70 11381@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 11382type or a scalar @code{LOGICAL} type or a boz-literal-constant. 11383@item @var{J} @tab The type shall be the same as the type of @var{I} or 11384a boz-literal-constant. @var{I} and @var{J} shall not both be 11385boz-literal-constants. If either @var{I} and @var{J} is a 11386boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 11387@end multitable 11388 11389@item @emph{Return value}: 11390The return type is either a scalar @code{INTEGER} or a scalar 11391@code{LOGICAL}. If the kind type parameters differ, then the 11392smaller kind type is implicitly converted to larger kind, and the 11393return has the larger kind. A boz-literal-constant is 11394converted to an @code{INTEGER} with the kind type parameter of 11395the other argument as-if a call to @ref{INT} occurred. 11396 11397@item @emph{Example}: 11398@smallexample 11399PROGRAM test_or 11400 LOGICAL :: T = .TRUE., F = .FALSE. 11401 INTEGER :: a, b 11402 DATA a / Z'F' /, b / Z'3' / 11403 11404 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F) 11405 WRITE (*,*) OR(a, b) 11406END PROGRAM 11407@end smallexample 11408 11409@item @emph{See also}: 11410Fortran 95 elemental function: @gol 11411@ref{IOR} 11412@end table 11413 11414 11415 11416@node PACK 11417@section @code{PACK} --- Pack an array into an array of rank one 11418@fnindex PACK 11419@cindex array, packing 11420@cindex array, reduce dimension 11421@cindex array, gather elements 11422 11423@table @asis 11424@item @emph{Description}: 11425Stores the elements of @var{ARRAY} in an array of rank one. 11426 11427The beginning of the resulting array is made up of elements whose @var{MASK} 11428equals @code{TRUE}. Afterwards, positions are filled with elements taken from 11429@var{VECTOR}. 11430 11431@item @emph{Standard}: 11432Fortran 90 and later 11433 11434@item @emph{Class}: 11435Transformational function 11436 11437@item @emph{Syntax}: 11438@code{RESULT = PACK(ARRAY, MASK[,VECTOR])} 11439 11440@item @emph{Arguments}: 11441@multitable @columnfractions .15 .70 11442@item @var{ARRAY} @tab Shall be an array of any type. 11443@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and 11444of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} 11445scalar. 11446@item @var{VECTOR} @tab (Optional) shall be an array of the same type 11447as @var{ARRAY} and of rank one. If present, the number of elements in 11448@var{VECTOR} shall be equal to or greater than the number of true elements 11449in @var{MASK}. If @var{MASK} is scalar, the number of elements in 11450@var{VECTOR} shall be equal to or greater than the number of elements in 11451@var{ARRAY}. 11452@end multitable 11453 11454@item @emph{Return value}: 11455The result is an array of rank one and the same type as that of @var{ARRAY}. 11456If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the 11457number of @code{TRUE} values in @var{MASK} otherwise. 11458 11459@item @emph{Example}: 11460Gathering nonzero elements from an array: 11461@smallexample 11462PROGRAM test_pack_1 11463 INTEGER :: m(6) 11464 m = (/ 1, 0, 0, 0, 5, 0 /) 11465 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5" 11466END PROGRAM 11467@end smallexample 11468 11469Gathering nonzero elements from an array and appending elements from @var{VECTOR}: 11470@smallexample 11471PROGRAM test_pack_2 11472 INTEGER :: m(4) 11473 m = (/ 1, 0, 0, 2 /) 11474 ! The following results in "1 2 3 4" 11475 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) 11476END PROGRAM 11477@end smallexample 11478 11479@item @emph{See also}: 11480@ref{UNPACK} 11481@end table 11482 11483 11484 11485@node PARITY 11486@section @code{PARITY} --- Reduction with exclusive OR 11487@fnindex PARITY 11488@cindex Parity 11489@cindex Reduction, XOR 11490@cindex XOR reduction 11491 11492@table @asis 11493@item @emph{Description}: 11494Calculates the parity, i.e. the reduction using @code{.XOR.}, 11495of @var{MASK} along dimension @var{DIM}. 11496 11497@item @emph{Standard}: 11498Fortran 2008 and later 11499 11500@item @emph{Class}: 11501Transformational function 11502 11503@item @emph{Syntax}: 11504@multitable @columnfractions .80 11505@item @code{RESULT = PARITY(MASK[, DIM])} 11506@end multitable 11507 11508@item @emph{Arguments}: 11509@multitable @columnfractions .15 .70 11510@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} 11511@item @var{DIM} @tab (Optional) shall be a scalar of type 11512@code{INTEGER} with a value in the range from 1 to n, where n 11513equals the rank of @var{MASK}. 11514@end multitable 11515 11516@item @emph{Return value}: 11517The result is of the same type as @var{MASK}. 11518 11519If @var{DIM} is absent, a scalar with the parity of all elements in 11520@var{MASK} is returned, i.e. true if an odd number of elements is 11521@code{.true.} and false otherwise. If @var{DIM} is present, an array 11522of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, 11523and a shape similar to that of @var{MASK} with dimension @var{DIM} 11524dropped is returned. 11525 11526@item @emph{Example}: 11527@smallexample 11528PROGRAM test_sum 11529 LOGICAL :: x(2) = [ .true., .false. ] 11530 print *, PARITY(x) ! prints "T" (true). 11531END PROGRAM 11532@end smallexample 11533@end table 11534 11535 11536 11537@node PERROR 11538@section @code{PERROR} --- Print system error message 11539@fnindex PERROR 11540@cindex system, error handling 11541 11542@table @asis 11543@item @emph{Description}: 11544Prints (on the C @code{stderr} stream) a newline-terminated error 11545message corresponding to the last system error. This is prefixed by 11546@var{STRING}, a colon and a space. See @code{perror(3)}. 11547 11548@item @emph{Standard}: 11549GNU extension 11550 11551@item @emph{Class}: 11552Subroutine 11553 11554@item @emph{Syntax}: 11555@code{CALL PERROR(STRING)} 11556 11557@item @emph{Arguments}: 11558@multitable @columnfractions .15 .70 11559@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the 11560default kind. 11561@end multitable 11562 11563@item @emph{See also}: 11564@ref{IERRNO} 11565@end table 11566 11567 11568 11569@node POPCNT 11570@section @code{POPCNT} --- Number of bits set 11571@fnindex POPCNT 11572@cindex binary representation 11573@cindex bits set 11574 11575@table @asis 11576@item @emph{Description}: 11577@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary 11578representation of @code{I}. 11579 11580@item @emph{Standard}: 11581Fortran 2008 and later 11582 11583@item @emph{Class}: 11584Elemental function 11585 11586@item @emph{Syntax}: 11587@code{RESULT = POPCNT(I)} 11588 11589@item @emph{Arguments}: 11590@multitable @columnfractions .15 .70 11591@item @var{I} @tab Shall be of type @code{INTEGER}. 11592@end multitable 11593 11594@item @emph{Return value}: 11595The return value is of type @code{INTEGER} and of the default integer 11596kind. 11597 11598@item @emph{Example}: 11599@smallexample 11600program test_population 11601 print *, popcnt(127), poppar(127) 11602 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11603 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11604end program test_population 11605@end smallexample 11606@item @emph{See also}: 11607@ref{POPPAR}, @gol 11608@ref{LEADZ}, @gol 11609@ref{TRAILZ} 11610@end table 11611 11612 11613 11614@node POPPAR 11615@section @code{POPPAR} --- Parity of the number of bits set 11616@fnindex POPPAR 11617@cindex binary representation 11618@cindex parity 11619 11620@table @asis 11621@item @emph{Description}: 11622@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity 11623of the number of bits set ('1' bits) in the binary representation of 11624@code{I}. It is equal to 0 if @code{I} has an even number of bits set, 11625and 1 for an odd number of '1' bits. 11626 11627@item @emph{Standard}: 11628Fortran 2008 and later 11629 11630@item @emph{Class}: 11631Elemental function 11632 11633@item @emph{Syntax}: 11634@code{RESULT = POPPAR(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{POPCNT}, @gol 11655@ref{LEADZ}, @gol 11656@ref{TRAILZ} 11657@end table 11658 11659 11660 11661@node PRECISION 11662@section @code{PRECISION} --- Decimal precision of a real kind 11663@fnindex PRECISION 11664@cindex model representation, precision 11665 11666@table @asis 11667@item @emph{Description}: 11668@code{PRECISION(X)} returns the decimal precision in the model of the 11669type of @code{X}. 11670 11671@item @emph{Standard}: 11672Fortran 90 and later 11673 11674@item @emph{Class}: 11675Inquiry function 11676 11677@item @emph{Syntax}: 11678@code{RESULT = PRECISION(X)} 11679 11680@item @emph{Arguments}: 11681@multitable @columnfractions .15 .70 11682@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may 11683be scalar or valued. 11684@end multitable 11685 11686@item @emph{Return value}: 11687The return value is of type @code{INTEGER} and of the default integer 11688kind. 11689 11690@item @emph{Example}: 11691@smallexample 11692program prec_and_range 11693 real(kind=4) :: x(2) 11694 complex(kind=8) :: y 11695 11696 print *, precision(x), range(x) 11697 print *, precision(y), range(y) 11698end program prec_and_range 11699@end smallexample 11700@item @emph{See also}: 11701@ref{SELECTED_REAL_KIND}, @gol 11702@ref{RANGE} 11703@end table 11704 11705 11706 11707@node PRESENT 11708@section @code{PRESENT} --- Determine whether an optional dummy argument is specified 11709@fnindex PRESENT 11710 11711@table @asis 11712@item @emph{Description}: 11713Determines whether an optional dummy argument is present. 11714 11715@item @emph{Standard}: 11716Fortran 90 and later 11717 11718@item @emph{Class}: 11719Inquiry function 11720 11721@item @emph{Syntax}: 11722@code{RESULT = PRESENT(A)} 11723 11724@item @emph{Arguments}: 11725@multitable @columnfractions .15 .70 11726@item @var{A} @tab May be of any type and may be a pointer, scalar or array 11727value, or a dummy procedure. It shall be the name of an optional dummy argument 11728accessible within the current subroutine or function. 11729@end multitable 11730 11731@item @emph{Return value}: 11732Returns either @code{TRUE} if the optional argument @var{A} is present, or 11733@code{FALSE} otherwise. 11734 11735@item @emph{Example}: 11736@smallexample 11737PROGRAM test_present 11738 WRITE(*,*) f(), f(42) ! "F T" 11739CONTAINS 11740 LOGICAL FUNCTION f(x) 11741 INTEGER, INTENT(IN), OPTIONAL :: x 11742 f = PRESENT(x) 11743 END FUNCTION 11744END PROGRAM 11745@end smallexample 11746@end table 11747 11748 11749 11750@node PRODUCT 11751@section @code{PRODUCT} --- Product of array elements 11752@fnindex PRODUCT 11753@cindex array, product 11754@cindex array, multiply elements 11755@cindex array, conditionally multiply elements 11756@cindex multiply array elements 11757 11758@table @asis 11759@item @emph{Description}: 11760Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if 11761the corresponding element in @var{MASK} is @code{TRUE}. 11762 11763@item @emph{Standard}: 11764Fortran 90 and later 11765 11766@item @emph{Class}: 11767Transformational function 11768 11769@item @emph{Syntax}: 11770@multitable @columnfractions .80 11771@item @code{RESULT = PRODUCT(ARRAY[, MASK])} 11772@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])} 11773@end multitable 11774 11775@item @emph{Arguments}: 11776@multitable @columnfractions .15 .70 11777@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 11778@code{REAL} or @code{COMPLEX}. 11779@item @var{DIM} @tab (Optional) shall be a scalar of type 11780@code{INTEGER} with a value in the range from 1 to n, where n 11781equals the rank of @var{ARRAY}. 11782@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 11783and either be a scalar or an array of the same shape as @var{ARRAY}. 11784@end multitable 11785 11786@item @emph{Return value}: 11787The result is of the same type as @var{ARRAY}. 11788 11789If @var{DIM} is absent, a scalar with the product of all elements in 11790@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 11791the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 11792dimension @var{DIM} dropped is returned. 11793 11794 11795@item @emph{Example}: 11796@smallexample 11797PROGRAM test_product 11798 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 11799 print *, PRODUCT(x) ! all elements, product = 120 11800 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15 11801END PROGRAM 11802@end smallexample 11803 11804@item @emph{See also}: 11805@ref{SUM} 11806@end table 11807 11808 11809 11810@node RADIX 11811@section @code{RADIX} --- Base of a model number 11812@fnindex RADIX 11813@cindex model representation, base 11814@cindex model representation, radix 11815 11816@table @asis 11817@item @emph{Description}: 11818@code{RADIX(X)} returns the base of the model representing the entity @var{X}. 11819 11820@item @emph{Standard}: 11821Fortran 90 and later 11822 11823@item @emph{Class}: 11824Inquiry function 11825 11826@item @emph{Syntax}: 11827@code{RESULT = RADIX(X)} 11828 11829@item @emph{Arguments}: 11830@multitable @columnfractions .15 .70 11831@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL} 11832@end multitable 11833 11834@item @emph{Return value}: 11835The return value is a scalar of type @code{INTEGER} and of the default 11836integer kind. 11837 11838@item @emph{Example}: 11839@smallexample 11840program test_radix 11841 print *, "The radix for the default integer kind is", radix(0) 11842 print *, "The radix for the default real kind is", radix(0.0) 11843end program test_radix 11844@end smallexample 11845@item @emph{See also}: 11846@ref{SELECTED_REAL_KIND} 11847@end table 11848 11849 11850 11851@node RAN 11852@section @code{RAN} --- Real pseudo-random number 11853@fnindex RAN 11854@cindex random number generation 11855 11856@table @asis 11857@item @emph{Description}: 11858For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is 11859provided as an alias for @code{RAND}. See @ref{RAND} for complete 11860documentation. 11861 11862@item @emph{Standard}: 11863GNU extension 11864 11865@item @emph{Class}: 11866Function 11867 11868@item @emph{See also}: 11869@ref{RAND}, @gol 11870@ref{RANDOM_NUMBER} 11871@end table 11872 11873 11874 11875@node RAND 11876@section @code{RAND} --- Real pseudo-random number 11877@fnindex RAND 11878@cindex random number generation 11879 11880@table @asis 11881@item @emph{Description}: 11882@code{RAND(FLAG)} returns a pseudo-random number from a uniform 11883distribution between 0 and 1. If @var{FLAG} is 0, the next number 11884in the current sequence is returned; if @var{FLAG} is 1, the generator 11885is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 11886it is used as a new seed with @code{SRAND}. 11887 11888This intrinsic routine is provided for backwards compatibility with 11889GNU Fortran 77. It implements a simple modulo generator as provided 11890by @command{g77}. For new code, one should consider the use of 11891@ref{RANDOM_NUMBER} as it implements a superior algorithm. 11892 11893@item @emph{Standard}: 11894GNU extension 11895 11896@item @emph{Class}: 11897Function 11898 11899@item @emph{Syntax}: 11900@code{RESULT = RAND(I)} 11901 11902@item @emph{Arguments}: 11903@multitable @columnfractions .15 .70 11904@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 11905@end multitable 11906 11907@item @emph{Return value}: 11908The return value is of @code{REAL} type and the default kind. 11909 11910@item @emph{Example}: 11911@smallexample 11912program test_rand 11913 integer,parameter :: seed = 86456 11914 11915 call srand(seed) 11916 print *, rand(), rand(), rand(), rand() 11917 print *, rand(seed), rand(), rand(), rand() 11918end program test_rand 11919@end smallexample 11920 11921@item @emph{See also}: 11922@ref{SRAND}, @gol 11923@ref{RANDOM_NUMBER} 11924 11925@end table 11926 11927 11928@node RANDOM_INIT 11929@section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator 11930@fnindex RANDOM_INIT 11931@cindex random number generation, initialization 11932 11933@table @asis 11934@item @emph{Description}: 11935Initializes the state of the pseudorandom number generator used by 11936@code{RANDOM_NUMBER}. 11937 11938@item @emph{Standard}: 11939Fortran 2018 11940 11941@item @emph{Class}: 11942Subroutine 11943 11944@item @emph{Syntax}: 11945@code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)} 11946 11947@item @emph{Arguments}: 11948@multitable @columnfractions .25 .70 11949@item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type, 11950and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to 11951a processor-dependent value that is the same each time @code{RANDOM_INIT} 11952is called from the same image. The term ``same image'' means a single 11953instance of program execution. The sequence of random numbers is different 11954for repeated execution of the program. If it is @code{.false.}, the seed 11955is set to a processor-dependent value. 11956@item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a 11957@code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.}, 11958the seed is set to a processor-dependent value that is distinct from th 11959seed set by a call to @code{RANDOM_INIT} in another image. If it is 11960@code{.false.}, the seed is set to a value that does depend which image called 11961@code{RANDOM_INIT}. 11962@end multitable 11963 11964@item @emph{Example}: 11965@smallexample 11966program test_random_seed 11967 implicit none 11968 real x(3), y(3) 11969 call random_init(.true., .true.) 11970 call random_number(x) 11971 call random_init(.true., .true.) 11972 call random_number(y) 11973 ! x and y are the same sequence 11974 if (any(x /= y)) call abort 11975end program test_random_seed 11976@end smallexample 11977 11978@item @emph{See also}: 11979@ref{RANDOM_NUMBER}, @gol 11980@ref{RANDOM_SEED} 11981@end table 11982 11983 11984@node RANDOM_NUMBER 11985@section @code{RANDOM_NUMBER} --- Pseudo-random number 11986@fnindex RANDOM_NUMBER 11987@cindex random number generation 11988 11989@table @asis 11990@item @emph{Description}: 11991Returns a single pseudorandom number or an array of pseudorandom numbers 11992from the uniform distribution over the range @math{ 0 \leq x < 1}. 11993 11994The runtime-library implements the xoshiro256** pseudorandom number 11995generator (PRNG). This generator has a period of @math{2^{256} - 1}, 11996and when using multiple threads up to @math{2^{128}} threads can each 11997generate @math{2^{128}} random numbers before any aliasing occurs. 11998 11999Note that in a multi-threaded program (e.g. using OpenMP directives), 12000each thread will have its own random number state. For details of the 12001seeding procedure, see the documentation for the @code{RANDOM_SEED} 12002intrinsic. 12003 12004 12005@item @emph{Standard}: 12006Fortran 90 and later 12007 12008@item @emph{Class}: 12009Subroutine 12010 12011@item @emph{Syntax}: 12012@code{CALL RANDOM_NUMBER(HARVEST)} 12013 12014@item @emph{Arguments}: 12015@multitable @columnfractions .15 .70 12016@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}. 12017@end multitable 12018 12019@item @emph{Example}: 12020@smallexample 12021program test_random_number 12022 REAL :: r(5,5) 12023 CALL RANDOM_NUMBER(r) 12024end program 12025@end smallexample 12026 12027@item @emph{See also}: 12028@ref{RANDOM_SEED}, @gol 12029@ref{RANDOM_INIT} 12030@end table 12031 12032 12033 12034@node RANDOM_SEED 12035@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence 12036@fnindex RANDOM_SEED 12037@cindex random number generation, seeding 12038@cindex seeding a random number generator 12039 12040@table @asis 12041@item @emph{Description}: 12042Restarts or queries the state of the pseudorandom number generator used by 12043@code{RANDOM_NUMBER}. 12044 12045If @code{RANDOM_SEED} is called without arguments, it is seeded with 12046random data retrieved from the operating system. 12047 12048As an extension to the Fortran standard, the GFortran 12049@code{RANDOM_NUMBER} supports multiple threads. Each thread in a 12050multi-threaded program has its own seed. When @code{RANDOM_SEED} is 12051called either without arguments or with the @var{PUT} argument, the 12052given seed is copied into a master seed as well as the seed of the 12053current thread. When a new thread uses @code{RANDOM_NUMBER} for the 12054first time, the seed is copied from the master seed, and forwarded 12055@math{N * 2^{128}} steps to guarantee that the random stream does not 12056alias any other stream in the system, where @var{N} is the number of 12057threads that have used @code{RANDOM_NUMBER} so far during the program 12058execution. 12059 12060@item @emph{Standard}: 12061Fortran 90 and later 12062 12063@item @emph{Class}: 12064Subroutine 12065 12066@item @emph{Syntax}: 12067@code{CALL RANDOM_SEED([SIZE, PUT, GET])} 12068 12069@item @emph{Arguments}: 12070@multitable @columnfractions .15 .70 12071@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default 12072@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size 12073of the arrays used with the @var{PUT} and @var{GET} arguments. 12074@item @var{PUT} @tab (Optional) Shall be an array of type default 12075@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of 12076the array must be larger than or equal to the number returned by the 12077@var{SIZE} argument. 12078@item @var{GET} @tab (Optional) Shall be an array of type default 12079@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size 12080of the array must be larger than or equal to the number returned by 12081the @var{SIZE} argument. 12082@end multitable 12083 12084@item @emph{Example}: 12085@smallexample 12086program test_random_seed 12087 implicit none 12088 integer, allocatable :: seed(:) 12089 integer :: n 12090 12091 call random_seed(size = n) 12092 allocate(seed(n)) 12093 call random_seed(get=seed) 12094 write (*, *) seed 12095end program test_random_seed 12096@end smallexample 12097 12098@item @emph{See also}: 12099@ref{RANDOM_NUMBER}, @gol 12100@ref{RANDOM_INIT} 12101@end table 12102 12103 12104 12105@node RANGE 12106@section @code{RANGE} --- Decimal exponent range 12107@fnindex RANGE 12108@cindex model representation, range 12109 12110@table @asis 12111@item @emph{Description}: 12112@code{RANGE(X)} returns the decimal exponent range in the model of the 12113type of @code{X}. 12114 12115@item @emph{Standard}: 12116Fortran 90 and later 12117 12118@item @emph{Class}: 12119Inquiry function 12120 12121@item @emph{Syntax}: 12122@code{RESULT = RANGE(X)} 12123 12124@item @emph{Arguments}: 12125@multitable @columnfractions .15 .70 12126@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL} 12127or @code{COMPLEX}. 12128@end multitable 12129 12130@item @emph{Return value}: 12131The return value is of type @code{INTEGER} and of the default integer 12132kind. 12133 12134@item @emph{Example}: 12135See @code{PRECISION} for an example. 12136@item @emph{See also}: 12137@ref{SELECTED_REAL_KIND}, @gol 12138@ref{PRECISION} 12139@end table 12140 12141 12142 12143@node RANK 12144@section @code{RANK} --- Rank of a data object 12145@fnindex RANK 12146@cindex rank 12147 12148@table @asis 12149@item @emph{Description}: 12150@code{RANK(A)} returns the rank of a scalar or array data object. 12151 12152@item @emph{Standard}: 12153Technical Specification (TS) 29113 12154 12155@item @emph{Class}: 12156Inquiry function 12157 12158@item @emph{Syntax}: 12159@code{RESULT = RANK(A)} 12160 12161@item @emph{Arguments}: 12162@multitable @columnfractions .15 .70 12163@item @var{A} @tab can be of any type 12164@end multitable 12165 12166@item @emph{Return value}: 12167The return value is of type @code{INTEGER} and of the default integer 12168kind. For arrays, their rank is returned; for scalars zero is returned. 12169 12170@item @emph{Example}: 12171@smallexample 12172program test_rank 12173 integer :: a 12174 real, allocatable :: b(:,:) 12175 12176 print *, rank(a), rank(b) ! Prints: 0 2 12177end program test_rank 12178@end smallexample 12179 12180@end table 12181 12182 12183 12184@node REAL 12185@section @code{REAL} --- Convert to real type 12186@fnindex REAL 12187@fnindex REALPART 12188@fnindex FLOAT 12189@fnindex DFLOAT 12190@fnindex FLOATI 12191@fnindex FLOATJ 12192@fnindex FLOATK 12193@fnindex SNGL 12194@cindex conversion, to real 12195@cindex complex numbers, real part 12196 12197@table @asis 12198@item @emph{Description}: 12199@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The 12200@code{REALPART} function is provided for compatibility with @command{g77}, 12201and its use is strongly discouraged. 12202 12203@item @emph{Standard}: 12204Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions 12205 12206@item @emph{Class}: 12207Elemental function 12208 12209@item @emph{Syntax}: 12210@multitable @columnfractions .80 12211@item @code{RESULT = REAL(A [, KIND])} 12212@item @code{RESULT = REALPART(Z)} 12213@end multitable 12214 12215@item @emph{Arguments}: 12216@multitable @columnfractions .15 .70 12217@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or 12218@code{COMPLEX}. 12219@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12220expression indicating the kind parameter of the result. 12221@end multitable 12222 12223@item @emph{Return value}: 12224These functions return a @code{REAL} variable or array under 12225the following rules: 12226 12227@table @asis 12228@item (A) 12229@code{REAL(A)} is converted to a default real type if @var{A} is an 12230integer or real variable. 12231@item (B) 12232@code{REAL(A)} is converted to a real type with the kind type parameter 12233of @var{A} if @var{A} is a complex variable. 12234@item (C) 12235@code{REAL(A, KIND)} is converted to a real type with kind type 12236parameter @var{KIND} if @var{A} is a complex, integer, or real 12237variable. 12238@end table 12239 12240@item @emph{Example}: 12241@smallexample 12242program test_real 12243 complex :: x = (1.0, 2.0) 12244 print *, real(x), real(x,8), realpart(x) 12245end program test_real 12246@end smallexample 12247 12248@item @emph{Specific names}: 12249@multitable @columnfractions .20 .23 .20 .33 12250@headitem Name @tab Argument @tab Return type @tab Standard 12251@item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later 12252@item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension 12253@item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension (-fdec) 12254@item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension (-fdec) 12255@item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension (-fdec) 12256@item @code{SNGL(A)} @tab @code{REAL(8)} @tab @code{REAL(4)} @tab Fortran 77 and later 12257@end multitable 12258 12259 12260@item @emph{See also}: 12261@ref{DBLE} 12262 12263@end table 12264 12265 12266 12267@node RENAME 12268@section @code{RENAME} --- Rename a file 12269@fnindex RENAME 12270@cindex file system, rename file 12271 12272@table @asis 12273@item @emph{Description}: 12274Renames a file from file @var{PATH1} to @var{PATH2}. A null 12275character (@code{CHAR(0)}) can be used to mark the end of the names in 12276@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 12277names are ignored. If the @var{STATUS} argument is supplied, it 12278contains 0 on success or a nonzero error code upon return; see 12279@code{rename(2)}. 12280 12281This intrinsic is provided in both subroutine and function forms; 12282however, only one form can be used in any given program unit. 12283 12284@item @emph{Standard}: 12285GNU extension 12286 12287@item @emph{Class}: 12288Subroutine, function 12289 12290@item @emph{Syntax}: 12291@multitable @columnfractions .80 12292@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])} 12293@item @code{STATUS = RENAME(PATH1, PATH2)} 12294@end multitable 12295 12296@item @emph{Arguments}: 12297@multitable @columnfractions .15 .70 12298@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 12299@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 12300@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 12301@end multitable 12302 12303@item @emph{See also}: 12304@ref{LINK} 12305 12306@end table 12307 12308 12309 12310@node REPEAT 12311@section @code{REPEAT} --- Repeated string concatenation 12312@fnindex REPEAT 12313@cindex string, repeat 12314@cindex string, concatenate 12315 12316@table @asis 12317@item @emph{Description}: 12318Concatenates @var{NCOPIES} copies of a string. 12319 12320@item @emph{Standard}: 12321Fortran 90 and later 12322 12323@item @emph{Class}: 12324Transformational function 12325 12326@item @emph{Syntax}: 12327@code{RESULT = REPEAT(STRING, NCOPIES)} 12328 12329@item @emph{Arguments}: 12330@multitable @columnfractions .15 .70 12331@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}. 12332@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}. 12333@end multitable 12334 12335@item @emph{Return value}: 12336A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies 12337of @var{STRING}. 12338 12339@item @emph{Example}: 12340@smallexample 12341program test_repeat 12342 write(*,*) repeat("x", 5) ! "xxxxx" 12343end program 12344@end smallexample 12345@end table 12346 12347 12348 12349@node RESHAPE 12350@section @code{RESHAPE} --- Function to reshape an array 12351@fnindex RESHAPE 12352@cindex array, change dimensions 12353@cindex array, transmogrify 12354 12355@table @asis 12356@item @emph{Description}: 12357Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary, 12358the new array may be padded with elements from @var{PAD} or permuted 12359as defined by @var{ORDER}. 12360 12361@item @emph{Standard}: 12362Fortran 90 and later 12363 12364@item @emph{Class}: 12365Transformational function 12366 12367@item @emph{Syntax}: 12368@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])} 12369 12370@item @emph{Arguments}: 12371@multitable @columnfractions .15 .70 12372@item @var{SOURCE} @tab Shall be an array of any type. 12373@item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an 12374array of rank one. Its values must be positive or zero. 12375@item @var{PAD} @tab (Optional) shall be an array of the same 12376type as @var{SOURCE}. 12377@item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER} 12378and an array of the same shape as @var{SHAPE}. Its values shall 12379be a permutation of the numbers from 1 to n, where n is the size of 12380@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall 12381be assumed. 12382@end multitable 12383 12384@item @emph{Return value}: 12385The result is an array of shape @var{SHAPE} with the same type as 12386@var{SOURCE}. 12387 12388@item @emph{Example}: 12389@smallexample 12390PROGRAM test_reshape 12391 INTEGER, DIMENSION(4) :: x 12392 WRITE(*,*) SHAPE(x) ! prints "4" 12393 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" 12394END PROGRAM 12395@end smallexample 12396 12397@item @emph{See also}: 12398@ref{SHAPE} 12399@end table 12400 12401 12402 12403@node RRSPACING 12404@section @code{RRSPACING} --- Reciprocal of the relative spacing 12405@fnindex RRSPACING 12406@cindex real number, relative spacing 12407@cindex floating point, relative spacing 12408 12409 12410@table @asis 12411@item @emph{Description}: 12412@code{RRSPACING(X)} returns the reciprocal of the relative spacing of 12413model numbers near @var{X}. 12414 12415@item @emph{Standard}: 12416Fortran 90 and later 12417 12418@item @emph{Class}: 12419Elemental function 12420 12421@item @emph{Syntax}: 12422@code{RESULT = RRSPACING(X)} 12423 12424@item @emph{Arguments}: 12425@multitable @columnfractions .15 .70 12426@item @var{X} @tab Shall be of type @code{REAL}. 12427@end multitable 12428 12429@item @emph{Return value}: 12430The return value is of the same type and kind as @var{X}. 12431The value returned is equal to 12432@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}. 12433 12434@item @emph{See also}: 12435@ref{SPACING} 12436@end table 12437 12438 12439 12440@node RSHIFT 12441@section @code{RSHIFT} --- Right shift bits 12442@fnindex RSHIFT 12443@cindex bits, shift right 12444 12445@table @asis 12446@item @emph{Description}: 12447@code{RSHIFT} returns a value corresponding to @var{I} with all of the 12448bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be 12449nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 12450the result value is undefined. Bits shifted out from the right end 12451are lost. The fill is arithmetic: the bits shifted in from the left 12452end are equal to the leftmost bit, which in two's complement 12453representation is the sign bit. 12454 12455This function has been superseded by the @code{SHIFTA} intrinsic, which 12456is standard in Fortran 2008 and later. 12457 12458@item @emph{Standard}: 12459GNU extension 12460 12461@item @emph{Class}: 12462Elemental function 12463 12464@item @emph{Syntax}: 12465@code{RESULT = RSHIFT(I, SHIFT)} 12466 12467@item @emph{Arguments}: 12468@multitable @columnfractions .15 .70 12469@item @var{I} @tab The type shall be @code{INTEGER}. 12470@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12471@end multitable 12472 12473@item @emph{Return value}: 12474The return value is of type @code{INTEGER} and of the same kind as 12475@var{I}. 12476 12477@item @emph{See also}: 12478@ref{ISHFT}, @gol 12479@ref{ISHFTC}, @gol 12480@ref{LSHIFT}, @gol 12481@ref{SHIFTA}, @gol 12482@ref{SHIFTR}, @gol 12483@ref{SHIFTL} 12484 12485@end table 12486 12487 12488 12489@node SAME_TYPE_AS 12490@section @code{SAME_TYPE_AS} --- Query dynamic types for equality 12491@fnindex SAME_TYPE_AS 12492 12493@table @asis 12494@item @emph{Description}: 12495Query dynamic types for equality. 12496 12497@item @emph{Standard}: 12498Fortran 2003 and later 12499 12500@item @emph{Class}: 12501Inquiry function 12502 12503@item @emph{Syntax}: 12504@code{RESULT = SAME_TYPE_AS(A, B)} 12505 12506@item @emph{Arguments}: 12507@multitable @columnfractions .15 .70 12508@item @var{A} @tab Shall be an object of extensible declared type or 12509unlimited polymorphic. 12510@item @var{B} @tab Shall be an object of extensible declared type or 12511unlimited polymorphic. 12512@end multitable 12513 12514@item @emph{Return value}: 12515The return value is a scalar of type default logical. It is true if and 12516only if the dynamic type of A is the same as the dynamic type of B. 12517 12518@item @emph{See also}: 12519@ref{EXTENDS_TYPE_OF} 12520 12521@end table 12522 12523 12524 12525@node SCALE 12526@section @code{SCALE} --- Scale a real value 12527@fnindex SCALE 12528@cindex real number, scale 12529@cindex floating point, scale 12530 12531@table @asis 12532@item @emph{Description}: 12533@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}. 12534 12535@item @emph{Standard}: 12536Fortran 90 and later 12537 12538@item @emph{Class}: 12539Elemental function 12540 12541@item @emph{Syntax}: 12542@code{RESULT = SCALE(X, I)} 12543 12544@item @emph{Arguments}: 12545@multitable @columnfractions .15 .70 12546@item @var{X} @tab The type of the argument shall be a @code{REAL}. 12547@item @var{I} @tab The type of the argument shall be a @code{INTEGER}. 12548@end multitable 12549 12550@item @emph{Return value}: 12551The return value is of the same type and kind as @var{X}. 12552Its value is @code{X * RADIX(X)**I}. 12553 12554@item @emph{Example}: 12555@smallexample 12556program test_scale 12557 real :: x = 178.1387e-4 12558 integer :: i = 5 12559 print *, scale(x,i), x*radix(x)**i 12560end program test_scale 12561@end smallexample 12562 12563@end table 12564 12565 12566 12567@node SCAN 12568@section @code{SCAN} --- Scan a string for the presence of a set of characters 12569@fnindex SCAN 12570@cindex string, find subset 12571 12572@table @asis 12573@item @emph{Description}: 12574Scans a @var{STRING} for any of the characters in a @var{SET} 12575of characters. 12576 12577If @var{BACK} is either absent or equals @code{FALSE}, this function 12578returns the position of the leftmost character of @var{STRING} that is 12579in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position 12580is returned. If no character of @var{SET} is found in @var{STRING}, the 12581result is zero. 12582 12583@item @emph{Standard}: 12584Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 12585 12586@item @emph{Class}: 12587Elemental function 12588 12589@item @emph{Syntax}: 12590@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])} 12591 12592@item @emph{Arguments}: 12593@multitable @columnfractions .15 .70 12594@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 12595@item @var{SET} @tab Shall be of type @code{CHARACTER}. 12596@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 12597@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12598expression indicating the kind parameter of the result. 12599@end multitable 12600 12601@item @emph{Return value}: 12602The return value is of type @code{INTEGER} and of kind @var{KIND}. If 12603@var{KIND} is absent, the return value is of default integer kind. 12604 12605@item @emph{Example}: 12606@smallexample 12607PROGRAM test_scan 12608 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O' 12609 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A' 12610 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none 12611END PROGRAM 12612@end smallexample 12613 12614@item @emph{See also}: 12615@ref{INDEX intrinsic}, @gol 12616@ref{VERIFY} 12617@end table 12618 12619 12620 12621@node SECNDS 12622@section @code{SECNDS} --- Time function 12623@fnindex SECNDS 12624@cindex time, elapsed 12625@cindex elapsed time 12626 12627@table @asis 12628@item @emph{Description}: 12629@code{SECNDS(X)} gets the time in seconds from the real-time system clock. 12630@var{X} is a reference time, also in seconds. If this is zero, the time in 12631seconds from midnight is returned. This function is non-standard and its 12632use is discouraged. 12633 12634@item @emph{Standard}: 12635GNU extension 12636 12637@item @emph{Class}: 12638Function 12639 12640@item @emph{Syntax}: 12641@code{RESULT = SECNDS (X)} 12642 12643@item @emph{Arguments}: 12644@multitable @columnfractions .15 .70 12645@item @var{T} @tab Shall be of type @code{REAL(4)}. 12646@item @var{X} @tab Shall be of type @code{REAL(4)}. 12647@end multitable 12648 12649@item @emph{Return value}: 12650None 12651 12652@item @emph{Example}: 12653@smallexample 12654program test_secnds 12655 integer :: i 12656 real(4) :: t1, t2 12657 print *, secnds (0.0) ! seconds since midnight 12658 t1 = secnds (0.0) ! reference time 12659 do i = 1, 10000000 ! do something 12660 end do 12661 t2 = secnds (t1) ! elapsed time 12662 print *, "Something took ", t2, " seconds." 12663end program test_secnds 12664@end smallexample 12665@end table 12666 12667 12668 12669@node SECOND 12670@section @code{SECOND} --- CPU time function 12671@fnindex SECOND 12672@cindex time, elapsed 12673@cindex elapsed time 12674 12675@table @asis 12676@item @emph{Description}: 12677Returns a @code{REAL(4)} value representing the elapsed CPU time in 12678seconds. This provides the same functionality as the standard 12679@code{CPU_TIME} intrinsic, and is only included for backwards 12680compatibility. 12681 12682This intrinsic is provided in both subroutine and function forms; 12683however, only one form can be used in any given program unit. 12684 12685@item @emph{Standard}: 12686GNU extension 12687 12688@item @emph{Class}: 12689Subroutine, function 12690 12691@item @emph{Syntax}: 12692@multitable @columnfractions .80 12693@item @code{CALL SECOND(TIME)} 12694@item @code{TIME = SECOND()} 12695@end multitable 12696 12697@item @emph{Arguments}: 12698@multitable @columnfractions .15 .70 12699@item @var{TIME} @tab Shall be of type @code{REAL(4)}. 12700@end multitable 12701 12702@item @emph{Return value}: 12703In either syntax, @var{TIME} is set to the process's current runtime in 12704seconds. 12705 12706@item @emph{See also}: 12707@ref{CPU_TIME} 12708 12709@end table 12710 12711 12712 12713@node SELECTED_CHAR_KIND 12714@section @code{SELECTED_CHAR_KIND} --- Choose character kind 12715@fnindex SELECTED_CHAR_KIND 12716@cindex character kind 12717@cindex kind, character 12718 12719@table @asis 12720@item @emph{Description}: 12721 12722@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character 12723set named @var{NAME}, if a character set with such a name is supported, 12724or @math{-1} otherwise. Currently, supported character sets include 12725``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646'' 12726(Universal Character Set, UCS-4) which is commonly known as Unicode. 12727 12728@item @emph{Standard}: 12729Fortran 2003 and later 12730 12731@item @emph{Class}: 12732Transformational function 12733 12734@item @emph{Syntax}: 12735@code{RESULT = SELECTED_CHAR_KIND(NAME)} 12736 12737@item @emph{Arguments}: 12738@multitable @columnfractions .15 .70 12739@item @var{NAME} @tab Shall be a scalar and of the default character type. 12740@end multitable 12741 12742@item @emph{Example}: 12743@smallexample 12744program character_kind 12745 use iso_fortran_env 12746 implicit none 12747 integer, parameter :: ascii = selected_char_kind ("ascii") 12748 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646') 12749 12750 character(kind=ascii, len=26) :: alphabet 12751 character(kind=ucs4, len=30) :: hello_world 12752 12753 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz" 12754 hello_world = ucs4_'Hello World and Ni Hao -- ' & 12755 // char (int (z'4F60'), ucs4) & 12756 // char (int (z'597D'), ucs4) 12757 12758 write (*,*) alphabet 12759 12760 open (output_unit, encoding='UTF-8') 12761 write (*,*) trim (hello_world) 12762end program character_kind 12763@end smallexample 12764@end table 12765 12766 12767 12768@node SELECTED_INT_KIND 12769@section @code{SELECTED_INT_KIND} --- Choose integer kind 12770@fnindex SELECTED_INT_KIND 12771@cindex integer kind 12772@cindex kind, integer 12773 12774@table @asis 12775@item @emph{Description}: 12776@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer 12777type that can represent all values ranging from @math{-10^R} (exclusive) 12778to @math{10^R} (exclusive). If there is no integer kind that accommodates 12779this range, @code{SELECTED_INT_KIND} returns @math{-1}. 12780 12781@item @emph{Standard}: 12782Fortran 90 and later 12783 12784@item @emph{Class}: 12785Transformational function 12786 12787@item @emph{Syntax}: 12788@code{RESULT = SELECTED_INT_KIND(R)} 12789 12790@item @emph{Arguments}: 12791@multitable @columnfractions .15 .70 12792@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}. 12793@end multitable 12794 12795@item @emph{Example}: 12796@smallexample 12797program large_integers 12798 integer,parameter :: k5 = selected_int_kind(5) 12799 integer,parameter :: k15 = selected_int_kind(15) 12800 integer(kind=k5) :: i5 12801 integer(kind=k15) :: i15 12802 12803 print *, huge(i5), huge(i15) 12804 12805 ! The following inequalities are always true 12806 print *, huge(i5) >= 10_k5**5-1 12807 print *, huge(i15) >= 10_k15**15-1 12808end program large_integers 12809@end smallexample 12810@end table 12811 12812 12813 12814@node SELECTED_REAL_KIND 12815@section @code{SELECTED_REAL_KIND} --- Choose real kind 12816@fnindex SELECTED_REAL_KIND 12817@cindex real kind 12818@cindex kind, real 12819@cindex radix, real 12820 12821@table @asis 12822@item @emph{Description}: 12823@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type 12824with decimal precision of at least @code{P} digits, exponent range of 12825at least @code{R}, and with a radix of @code{RADIX}. 12826 12827@item @emph{Standard}: 12828Fortran 90 and later, with @code{RADIX} Fortran 2008 or later 12829 12830@item @emph{Class}: 12831Transformational function 12832 12833@item @emph{Syntax}: 12834@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])} 12835 12836@item @emph{Arguments}: 12837@multitable @columnfractions .15 .70 12838@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12839@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12840@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12841@end multitable 12842Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall 12843be present; since Fortran 2008, they are assumed to be zero if absent. 12844 12845@item @emph{Return value}: 12846 12847@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of 12848a real data type with decimal precision of at least @code{P} digits, a 12849decimal exponent range of at least @code{R}, and with the requested 12850@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with 12851any radix can be returned. If more than one real data type meet the 12852criteria, the kind of the data type with the smallest decimal precision 12853is returned. If no real data type matches the criteria, the result is 12854@table @asis 12855@item -1 if the processor does not support a real data type with a 12856precision greater than or equal to @code{P}, but the @code{R} and 12857@code{RADIX} requirements can be fulfilled 12858@item -2 if the processor does not support a real type with an exponent 12859range greater than or equal to @code{R}, but @code{P} and @code{RADIX} 12860are fulfillable 12861@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements 12862are fulfillable 12863@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements 12864are fulfillable 12865@item -5 if there is no real type with the given @code{RADIX} 12866@end table 12867 12868@item @emph{Example}: 12869@smallexample 12870program real_kinds 12871 integer,parameter :: p6 = selected_real_kind(6) 12872 integer,parameter :: p10r100 = selected_real_kind(10,100) 12873 integer,parameter :: r400 = selected_real_kind(r=400) 12874 real(kind=p6) :: x 12875 real(kind=p10r100) :: y 12876 real(kind=r400) :: z 12877 12878 print *, precision(x), range(x) 12879 print *, precision(y), range(y) 12880 print *, precision(z), range(z) 12881end program real_kinds 12882@end smallexample 12883@item @emph{See also}: 12884@ref{PRECISION}, @gol 12885@ref{RANGE}, @gol 12886@ref{RADIX} 12887@end table 12888 12889 12890 12891@node SET_EXPONENT 12892@section @code{SET_EXPONENT} --- Set the exponent of the model 12893@fnindex SET_EXPONENT 12894@cindex real number, set exponent 12895@cindex floating point, set exponent 12896 12897@table @asis 12898@item @emph{Description}: 12899@code{SET_EXPONENT(X, I)} returns the real number whose fractional part 12900is that that of @var{X} and whose exponent part is @var{I}. 12901 12902@item @emph{Standard}: 12903Fortran 90 and later 12904 12905@item @emph{Class}: 12906Elemental function 12907 12908@item @emph{Syntax}: 12909@code{RESULT = SET_EXPONENT(X, I)} 12910 12911@item @emph{Arguments}: 12912@multitable @columnfractions .15 .70 12913@item @var{X} @tab Shall be of type @code{REAL}. 12914@item @var{I} @tab Shall be of type @code{INTEGER}. 12915@end multitable 12916 12917@item @emph{Return value}: 12918The return value is of the same type and kind as @var{X}. 12919The real number whose fractional part 12920is that that of @var{X} and whose exponent part if @var{I} is returned; 12921it is @code{FRACTION(X) * RADIX(X)**I}. 12922 12923@item @emph{Example}: 12924@smallexample 12925PROGRAM test_setexp 12926 REAL :: x = 178.1387e-4 12927 INTEGER :: i = 17 12928 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i 12929END PROGRAM 12930@end smallexample 12931 12932@end table 12933 12934 12935 12936@node SHAPE 12937@section @code{SHAPE} --- Determine the shape of an array 12938@fnindex SHAPE 12939@cindex array, shape 12940 12941@table @asis 12942@item @emph{Description}: 12943Determines the shape of an array. 12944 12945@item @emph{Standard}: 12946Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 12947 12948@item @emph{Class}: 12949Inquiry function 12950 12951@item @emph{Syntax}: 12952@code{RESULT = SHAPE(SOURCE [, KIND])} 12953 12954@item @emph{Arguments}: 12955@multitable @columnfractions .15 .70 12956@item @var{SOURCE} @tab Shall be an array or scalar of any type. 12957If @var{SOURCE} is a pointer it must be associated and allocatable 12958arrays must be allocated. 12959@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12960expression indicating the kind parameter of the result. 12961@end multitable 12962 12963@item @emph{Return value}: 12964An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 12965has dimensions. The elements of the resulting array correspond to the extend 12966of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar, 12967the result is the rank one array of size zero. If @var{KIND} is absent, the 12968return value has the default integer kind otherwise the specified kind. 12969 12970@item @emph{Example}: 12971@smallexample 12972PROGRAM test_shape 12973 INTEGER, DIMENSION(-1:1, -1:2) :: A 12974 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) 12975 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) 12976END PROGRAM 12977@end smallexample 12978 12979@item @emph{See also}: 12980@ref{RESHAPE}, @gol 12981@ref{SIZE} 12982@end table 12983 12984 12985 12986@node SHIFTA 12987@section @code{SHIFTA} --- Right shift with fill 12988@fnindex SHIFTA 12989@cindex bits, shift right 12990@cindex shift, right with fill 12991 12992@table @asis 12993@item @emph{Description}: 12994@code{SHIFTA} returns a value corresponding to @var{I} with all of the 12995bits shifted right by @var{SHIFT} places. @var{SHIFT} that be 12996nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 12997the result value is undefined. Bits shifted out from the right end 12998are lost. The fill is arithmetic: the bits shifted in from the left 12999end are equal to the leftmost bit, which in two's complement 13000representation is the sign bit. 13001 13002@item @emph{Standard}: 13003Fortran 2008 and later 13004 13005@item @emph{Class}: 13006Elemental function 13007 13008@item @emph{Syntax}: 13009@code{RESULT = SHIFTA(I, SHIFT)} 13010 13011@item @emph{Arguments}: 13012@multitable @columnfractions .15 .70 13013@item @var{I} @tab The type shall be @code{INTEGER}. 13014@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13015@end multitable 13016 13017@item @emph{Return value}: 13018The return value is of type @code{INTEGER} and of the same kind as 13019@var{I}. 13020 13021@item @emph{See also}: 13022@ref{SHIFTL}, @gol 13023@ref{SHIFTR} 13024@end table 13025 13026 13027 13028@node SHIFTL 13029@section @code{SHIFTL} --- Left shift 13030@fnindex SHIFTL 13031@cindex bits, shift left 13032@cindex shift, left 13033 13034@table @asis 13035@item @emph{Description}: 13036@code{SHIFTL} returns a value corresponding to @var{I} with all of the 13037bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be 13038nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 13039the result value is undefined. Bits shifted out from the left end are 13040lost, and bits shifted in from the right end are set to 0. 13041 13042@item @emph{Standard}: 13043Fortran 2008 and later 13044 13045@item @emph{Class}: 13046Elemental function 13047 13048@item @emph{Syntax}: 13049@code{RESULT = SHIFTL(I, SHIFT)} 13050 13051@item @emph{Arguments}: 13052@multitable @columnfractions .15 .70 13053@item @var{I} @tab The type shall be @code{INTEGER}. 13054@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13055@end multitable 13056 13057@item @emph{Return value}: 13058The return value is of type @code{INTEGER} and of the same kind as 13059@var{I}. 13060 13061@item @emph{See also}: 13062@ref{SHIFTA}, @gol 13063@ref{SHIFTR} 13064@end table 13065 13066 13067 13068@node SHIFTR 13069@section @code{SHIFTR} --- Right shift 13070@fnindex SHIFTR 13071@cindex bits, shift right 13072@cindex shift, right 13073 13074@table @asis 13075@item @emph{Description}: 13076@code{SHIFTR} returns a value corresponding to @var{I} with all of the 13077bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be 13078nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 13079the result value is undefined. Bits shifted out from the right end 13080are lost, and bits shifted in from the left end are set to 0. 13081 13082@item @emph{Standard}: 13083Fortran 2008 and later 13084 13085@item @emph{Class}: 13086Elemental function 13087 13088@item @emph{Syntax}: 13089@code{RESULT = SHIFTR(I, SHIFT)} 13090 13091@item @emph{Arguments}: 13092@multitable @columnfractions .15 .70 13093@item @var{I} @tab The type shall be @code{INTEGER}. 13094@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13095@end multitable 13096 13097@item @emph{Return value}: 13098The return value is of type @code{INTEGER} and of the same kind as 13099@var{I}. 13100 13101@item @emph{See also}: 13102@ref{SHIFTA}, @gol 13103@ref{SHIFTL} 13104@end table 13105 13106 13107 13108@node SIGN 13109@section @code{SIGN} --- Sign copying function 13110@fnindex SIGN 13111@fnindex ISIGN 13112@fnindex DSIGN 13113@cindex sign copying 13114 13115@table @asis 13116@item @emph{Description}: 13117@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}. 13118 13119@item @emph{Standard}: 13120Fortran 77 and later 13121 13122@item @emph{Class}: 13123Elemental function 13124 13125@item @emph{Syntax}: 13126@code{RESULT = SIGN(A, B)} 13127 13128@item @emph{Arguments}: 13129@multitable @columnfractions .15 .70 13130@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL} 13131@item @var{B} @tab Shall be of the same type and kind as @var{A}. 13132@end multitable 13133 13134@item @emph{Return value}: 13135The kind of the return value is that of @var{A} and @var{B}. 13136If @math{B \ge 0} then the result is @code{ABS(A)}, else 13137it is @code{-ABS(A)}. 13138 13139@item @emph{Example}: 13140@smallexample 13141program test_sign 13142 print *, sign(-12,1) 13143 print *, sign(-12,0) 13144 print *, sign(-12,-1) 13145 13146 print *, sign(-12.,1.) 13147 print *, sign(-12.,0.) 13148 print *, sign(-12.,-1.) 13149end program test_sign 13150@end smallexample 13151 13152@item @emph{Specific names}: 13153@multitable @columnfractions .20 .26 .20 .30 13154@headitem Name @tab Arguments @tab Return type @tab Standard 13155@item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later 13156@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later 13157@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later 13158@end multitable 13159@end table 13160 13161 13162 13163@node SIGNAL 13164@section @code{SIGNAL} --- Signal handling subroutine (or function) 13165@fnindex SIGNAL 13166@cindex system, signal handling 13167 13168@table @asis 13169@item @emph{Description}: 13170@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine 13171@var{HANDLER} to be executed with a single integer argument when signal 13172@var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to 13173turn off handling of signal @var{NUMBER} or revert to its default 13174action. See @code{signal(2)}. 13175 13176If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument 13177is supplied, it is set to the value returned by @code{signal(2)}. 13178 13179@item @emph{Standard}: 13180GNU extension 13181 13182@item @emph{Class}: 13183Subroutine, function 13184 13185@item @emph{Syntax}: 13186@multitable @columnfractions .80 13187@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])} 13188@item @code{STATUS = SIGNAL(NUMBER, HANDLER)} 13189@end multitable 13190 13191@item @emph{Arguments}: 13192@multitable @columnfractions .15 .70 13193@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)} 13194@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or 13195@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. 13196@code{INTEGER}. It is @code{INTENT(IN)}. 13197@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 13198integer. It has @code{INTENT(OUT)}. 13199@end multitable 13200@c TODO: What should the interface of the handler be? Does it take arguments? 13201 13202@item @emph{Return value}: 13203The @code{SIGNAL} function returns the value returned by @code{signal(2)}. 13204 13205@item @emph{Example}: 13206@smallexample 13207program test_signal 13208 intrinsic signal 13209 external handler_print 13210 13211 call signal (12, handler_print) 13212 call signal (10, 1) 13213 13214 call sleep (30) 13215end program test_signal 13216@end smallexample 13217@end table 13218 13219 13220 13221@node SIN 13222@section @code{SIN} --- Sine function 13223@fnindex SIN 13224@fnindex DSIN 13225@fnindex CSIN 13226@fnindex ZSIN 13227@fnindex CDSIN 13228@cindex trigonometric function, sine 13229@cindex sine 13230 13231@table @asis 13232@item @emph{Description}: 13233@code{SIN(X)} computes the sine of @var{X}. 13234 13235@item @emph{Standard}: 13236Fortran 77 and later 13237 13238@item @emph{Class}: 13239Elemental function 13240 13241@item @emph{Syntax}: 13242@code{RESULT = SIN(X)} 13243 13244@item @emph{Arguments}: 13245@multitable @columnfractions .15 .70 13246@item @var{X} @tab The type shall be @code{REAL} or 13247@code{COMPLEX}. 13248@end multitable 13249 13250@item @emph{Return value}: 13251The return value has same type and kind as @var{X}. 13252 13253@item @emph{Example}: 13254@smallexample 13255program test_sin 13256 real :: x = 0.0 13257 x = sin(x) 13258end program test_sin 13259@end smallexample 13260 13261@item @emph{Specific names}: 13262@multitable @columnfractions .20 .23 .20 .33 13263@headitem Name @tab Argument @tab Return type @tab Standard 13264@item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 13265@item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 13266@item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 13267@item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13268@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13269@end multitable 13270 13271@item @emph{See also}: 13272Inverse function: @gol 13273@ref{ASIN} @gol 13274Degrees function: @gol 13275@ref{SIND} 13276@end table 13277 13278 13279 13280@node SIND 13281@section @code{SIND} --- Sine function, degrees 13282@fnindex SIND 13283@fnindex DSIND 13284@fnindex CSIND 13285@fnindex ZSIND 13286@fnindex CDSIND 13287@cindex trigonometric function, sine, degrees 13288@cindex sine, degrees 13289 13290@table @asis 13291@item @emph{Description}: 13292@code{SIND(X)} computes the sine of @var{X} in degrees. 13293 13294This function is for compatibility only and should be avoided in favor of 13295standard constructs wherever possible. 13296 13297@item @emph{Standard}: 13298GNU extension, enabled with @option{-fdec-math}. 13299 13300@item @emph{Class}: 13301Elemental function 13302 13303@item @emph{Syntax}: 13304@code{RESULT = SIND(X)} 13305 13306@item @emph{Arguments}: 13307@multitable @columnfractions .15 .70 13308@item @var{X} @tab The type shall be @code{REAL} or 13309@code{COMPLEX}. 13310@end multitable 13311 13312@item @emph{Return value}: 13313The return value has same type and kind as @var{X}, and its value is in degrees. 13314 13315@item @emph{Example}: 13316@smallexample 13317program test_sind 13318 real :: x = 0.0 13319 x = sind(x) 13320end program test_sind 13321@end smallexample 13322 13323@item @emph{Specific names}: 13324@multitable @columnfractions .20 .23 .20 .33 13325@headitem Name @tab Argument @tab Return type @tab Standard 13326@item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 13327@item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 13328@item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension 13329@item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13330@item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13331@end multitable 13332 13333@item @emph{See also}: 13334Inverse function: @gol 13335@ref{ASIND} @gol 13336Radians function: @gol 13337@ref{SIN} @gol 13338@end table 13339 13340 13341 13342@node SINH 13343@section @code{SINH} --- Hyperbolic sine function 13344@fnindex SINH 13345@fnindex DSINH 13346@cindex hyperbolic sine 13347@cindex hyperbolic function, sine 13348@cindex sine, hyperbolic 13349 13350@table @asis 13351@item @emph{Description}: 13352@code{SINH(X)} computes the hyperbolic sine of @var{X}. 13353 13354@item @emph{Standard}: 13355Fortran 90 and later, for a complex argument Fortran 2008 or later, has 13356a GNU extension 13357 13358@item @emph{Class}: 13359Elemental function 13360 13361@item @emph{Syntax}: 13362@code{RESULT = SINH(X)} 13363 13364@item @emph{Arguments}: 13365@multitable @columnfractions .15 .70 13366@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13367@end multitable 13368 13369@item @emph{Return value}: 13370The return value has same type and kind as @var{X}. 13371 13372@item @emph{Example}: 13373@smallexample 13374program test_sinh 13375 real(8) :: x = - 1.0_8 13376 x = sinh(x) 13377end program test_sinh 13378@end smallexample 13379 13380@item @emph{Specific names}: 13381@multitable @columnfractions .20 .23 .20 .33 13382@headitem Name @tab Argument @tab Return type @tab Standard 13383@item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 and later 13384@end multitable 13385 13386@item @emph{See also}: 13387@ref{ASINH} 13388@end table 13389 13390 13391 13392@node SIZE 13393@section @code{SIZE} --- Determine the size of an array 13394@fnindex SIZE 13395@cindex array, size 13396@cindex array, number of elements 13397@cindex array, count elements 13398 13399@table @asis 13400@item @emph{Description}: 13401Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}, 13402or the total number of elements in @var{ARRAY} if @var{DIM} is absent. 13403 13404@item @emph{Standard}: 13405Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 13406 13407@item @emph{Class}: 13408Inquiry function 13409 13410@item @emph{Syntax}: 13411@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])} 13412 13413@item @emph{Arguments}: 13414@multitable @columnfractions .15 .70 13415@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is 13416a pointer it must be associated and allocatable arrays must be allocated. 13417@item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} 13418and its value shall be in the range from 1 to n, where n equals the rank 13419of @var{ARRAY}. 13420@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13421expression indicating the kind parameter of the result. 13422@end multitable 13423 13424@item @emph{Return value}: 13425The return value is of type @code{INTEGER} and of kind @var{KIND}. If 13426@var{KIND} is absent, the return value is of default integer kind. 13427 13428@item @emph{Example}: 13429@smallexample 13430PROGRAM test_size 13431 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 13432END PROGRAM 13433@end smallexample 13434 13435@item @emph{See also}: 13436@ref{SHAPE}, @gol 13437@ref{RESHAPE} 13438@end table 13439 13440 13441@node SIZEOF 13442@section @code{SIZEOF} --- Size in bytes of an expression 13443@fnindex SIZEOF 13444@cindex expression size 13445@cindex size of an expression 13446 13447@table @asis 13448@item @emph{Description}: 13449@code{SIZEOF(X)} calculates the number of bytes of storage the 13450expression @code{X} occupies. 13451 13452@item @emph{Standard}: 13453GNU extension 13454 13455@item @emph{Class}: 13456Inquiry function 13457 13458@item @emph{Syntax}: 13459@code{N = SIZEOF(X)} 13460 13461@item @emph{Arguments}: 13462@multitable @columnfractions .15 .70 13463@item @var{X} @tab The argument shall be of any type, rank or shape. 13464@end multitable 13465 13466@item @emph{Return value}: 13467The return value is of type integer and of the system-dependent kind 13468@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the 13469number of bytes occupied by the argument. If the argument has the 13470@code{POINTER} attribute, the number of bytes of the storage area pointed 13471to is returned. If the argument is of a derived type with @code{POINTER} 13472or @code{ALLOCATABLE} components, the return value does not account for 13473the sizes of the data pointed to by these components. If the argument is 13474polymorphic, the size according to the dynamic type is returned. The argument 13475may not be a procedure or procedure pointer. Note that the code assumes for 13476arrays that those are contiguous; for contiguous arrays, it returns the 13477storage or an array element multiplied by the size of the array. 13478 13479@item @emph{Example}: 13480@smallexample 13481 integer :: i 13482 real :: r, s(5) 13483 print *, (sizeof(s)/sizeof(r) == 5) 13484 end 13485@end smallexample 13486The example will print @code{.TRUE.} unless you are using a platform 13487where default @code{REAL} variables are unusually padded. 13488 13489@item @emph{See also}: 13490@ref{C_SIZEOF}, @gol 13491@ref{STORAGE_SIZE} 13492@end table 13493 13494 13495@node SLEEP 13496@section @code{SLEEP} --- Sleep for the specified number of seconds 13497@fnindex SLEEP 13498@cindex delayed execution 13499 13500@table @asis 13501@item @emph{Description}: 13502Calling this subroutine causes the process to pause for @var{SECONDS} seconds. 13503 13504@item @emph{Standard}: 13505GNU extension 13506 13507@item @emph{Class}: 13508Subroutine 13509 13510@item @emph{Syntax}: 13511@code{CALL SLEEP(SECONDS)} 13512 13513@item @emph{Arguments}: 13514@multitable @columnfractions .15 .70 13515@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}. 13516@end multitable 13517 13518@item @emph{Example}: 13519@smallexample 13520program test_sleep 13521 call sleep(5) 13522end 13523@end smallexample 13524@end table 13525 13526 13527 13528@node SPACING 13529@section @code{SPACING} --- Smallest distance between two numbers of a given type 13530@fnindex SPACING 13531@cindex real number, relative spacing 13532@cindex floating point, relative spacing 13533 13534@table @asis 13535@item @emph{Description}: 13536Determines the distance between the argument @var{X} and the nearest 13537adjacent number of the same type. 13538 13539@item @emph{Standard}: 13540Fortran 90 and later 13541 13542@item @emph{Class}: 13543Elemental function 13544 13545@item @emph{Syntax}: 13546@code{RESULT = SPACING(X)} 13547 13548@item @emph{Arguments}: 13549@multitable @columnfractions .15 .70 13550@item @var{X} @tab Shall be of type @code{REAL}. 13551@end multitable 13552 13553@item @emph{Return value}: 13554The result is of the same type as the input argument @var{X}. 13555 13556@item @emph{Example}: 13557@smallexample 13558PROGRAM test_spacing 13559 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37) 13560 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200) 13561 13562 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686 13563 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686 13564END PROGRAM 13565@end smallexample 13566 13567@item @emph{See also}: 13568@ref{RRSPACING} 13569@end table 13570 13571 13572 13573@node SPREAD 13574@section @code{SPREAD} --- Add a dimension to an array 13575@fnindex SPREAD 13576@cindex array, increase dimension 13577@cindex array, duplicate elements 13578@cindex array, duplicate dimensions 13579 13580@table @asis 13581@item @emph{Description}: 13582Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified 13583dimension @var{DIM}. 13584 13585@item @emph{Standard}: 13586Fortran 90 and later 13587 13588@item @emph{Class}: 13589Transformational function 13590 13591@item @emph{Syntax}: 13592@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)} 13593 13594@item @emph{Arguments}: 13595@multitable @columnfractions .15 .70 13596@item @var{SOURCE} @tab Shall be a scalar or an array of any type and 13597a rank less than seven. 13598@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a 13599value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}. 13600@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}. 13601@end multitable 13602 13603@item @emph{Return value}: 13604The result is an array of the same type as @var{SOURCE} and has rank n+1 13605where n equals the rank of @var{SOURCE}. 13606 13607@item @emph{Example}: 13608@smallexample 13609PROGRAM test_spread 13610 INTEGER :: a = 1, b(2) = (/ 1, 2 /) 13611 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1" 13612 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2" 13613END PROGRAM 13614@end smallexample 13615 13616@item @emph{See also}: 13617@ref{UNPACK} 13618@end table 13619 13620 13621 13622@node SQRT 13623@section @code{SQRT} --- Square-root function 13624@fnindex SQRT 13625@fnindex DSQRT 13626@fnindex CSQRT 13627@fnindex ZSQRT 13628@fnindex CDSQRT 13629@cindex root 13630@cindex square-root 13631 13632@table @asis 13633@item @emph{Description}: 13634@code{SQRT(X)} computes the square root of @var{X}. 13635 13636@item @emph{Standard}: 13637Fortran 77 and later 13638 13639@item @emph{Class}: 13640Elemental function 13641 13642@item @emph{Syntax}: 13643@code{RESULT = SQRT(X)} 13644 13645@item @emph{Arguments}: 13646@multitable @columnfractions .15 .70 13647@item @var{X} @tab The type shall be @code{REAL} or 13648@code{COMPLEX}. 13649@end multitable 13650 13651@item @emph{Return value}: 13652The return value is of type @code{REAL} or @code{COMPLEX}. 13653The kind type parameter is the same as @var{X}. 13654 13655@item @emph{Example}: 13656@smallexample 13657program test_sqrt 13658 real(8) :: x = 2.0_8 13659 complex :: z = (1.0, 2.0) 13660 x = sqrt(x) 13661 z = sqrt(z) 13662end program test_sqrt 13663@end smallexample 13664 13665@item @emph{Specific names}: 13666@multitable @columnfractions .20 .23 .20 .33 13667@headitem Name @tab Argument @tab Return type @tab Standard 13668@item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 13669@item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 13670@item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 13671@item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13672@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13673@end multitable 13674@end table 13675 13676 13677 13678@node SRAND 13679@section @code{SRAND} --- Reinitialize the random number generator 13680@fnindex SRAND 13681@cindex random number generation, seeding 13682@cindex seeding a random number generator 13683 13684@table @asis 13685@item @emph{Description}: 13686@code{SRAND} reinitializes the pseudo-random number generator 13687called by @code{RAND} and @code{IRAND}. The new seed used by the 13688generator is specified by the required argument @var{SEED}. 13689 13690@item @emph{Standard}: 13691GNU extension 13692 13693@item @emph{Class}: 13694Subroutine 13695 13696@item @emph{Syntax}: 13697@code{CALL SRAND(SEED)} 13698 13699@item @emph{Arguments}: 13700@multitable @columnfractions .15 .70 13701@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}. 13702@end multitable 13703 13704@item @emph{Return value}: 13705Does not return anything. 13706 13707@item @emph{Example}: 13708See @code{RAND} and @code{IRAND} for examples. 13709 13710@item @emph{Notes}: 13711The Fortran standard specifies the intrinsic subroutines 13712@code{RANDOM_SEED} to initialize the pseudo-random number 13713generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers. 13714These subroutines should be used in new codes. 13715 13716Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND}, 13717@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and 13718@code{RANDOM_SEED} on the other hand) access two independent 13719pseudo-random number generators. 13720 13721@item @emph{See also}: 13722@ref{RAND}, @gol 13723@ref{RANDOM_SEED}, @gol 13724@ref{RANDOM_NUMBER} 13725@end table 13726 13727 13728 13729@node STAT 13730@section @code{STAT} --- Get file status 13731@fnindex STAT 13732@cindex file system, file status 13733 13734@table @asis 13735@item @emph{Description}: 13736This function returns information about a file. No permissions are required on 13737the file itself, but execute (search) permission is required on all of the 13738directories in path that lead to the file. 13739 13740The elements that are obtained and stored in the array @code{VALUES}: 13741@multitable @columnfractions .15 .70 13742@item @code{VALUES(1)} @tab Device ID 13743@item @code{VALUES(2)} @tab Inode number 13744@item @code{VALUES(3)} @tab File mode 13745@item @code{VALUES(4)} @tab Number of links 13746@item @code{VALUES(5)} @tab Owner's uid 13747@item @code{VALUES(6)} @tab Owner's gid 13748@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available) 13749@item @code{VALUES(8)} @tab File size (bytes) 13750@item @code{VALUES(9)} @tab Last access time 13751@item @code{VALUES(10)} @tab Last modification time 13752@item @code{VALUES(11)} @tab Last file status change time 13753@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available) 13754@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available) 13755@end multitable 13756 13757Not all these elements are relevant on all systems. 13758If an element is not relevant, it is returned as 0. 13759 13760This intrinsic is provided in both subroutine and function forms; however, 13761only one form can be used in any given program unit. 13762 13763@item @emph{Standard}: 13764GNU extension 13765 13766@item @emph{Class}: 13767Subroutine, function 13768 13769@item @emph{Syntax}: 13770@multitable @columnfractions .80 13771@item @code{CALL STAT(NAME, VALUES [, STATUS])} 13772@item @code{STATUS = STAT(NAME, VALUES)} 13773@end multitable 13774 13775@item @emph{Arguments}: 13776@multitable @columnfractions .15 .70 13777@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the 13778default kind and a valid path within the file system. 13779@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 13780@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 13781on success and a system specific error code otherwise. 13782@end multitable 13783 13784@item @emph{Example}: 13785@smallexample 13786PROGRAM test_stat 13787 INTEGER, DIMENSION(13) :: buff 13788 INTEGER :: status 13789 13790 CALL STAT("/etc/passwd", buff, status) 13791 13792 IF (status == 0) THEN 13793 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1) 13794 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2) 13795 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3) 13796 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4) 13797 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5) 13798 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6) 13799 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7) 13800 WRITE (*, FMT="('File size:', T30, I19)") buff(8) 13801 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9)) 13802 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10)) 13803 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11)) 13804 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12) 13805 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13) 13806 END IF 13807END PROGRAM 13808@end smallexample 13809 13810@item @emph{See also}: 13811To stat an open file: @gol 13812@ref{FSTAT} @gol 13813To stat a link: @gol 13814@ref{LSTAT} 13815@end table 13816 13817 13818 13819@node STORAGE_SIZE 13820@section @code{STORAGE_SIZE} --- Storage size in bits 13821@fnindex STORAGE_SIZE 13822@cindex storage size 13823 13824@table @asis 13825@item @emph{Description}: 13826Returns the storage size of argument @var{A} in bits. 13827@item @emph{Standard}: 13828Fortran 2008 and later 13829@item @emph{Class}: 13830Inquiry function 13831@item @emph{Syntax}: 13832@code{RESULT = STORAGE_SIZE(A [, KIND])} 13833 13834@item @emph{Arguments}: 13835@multitable @columnfractions .15 .70 13836@item @var{A} @tab Shall be a scalar or array of any type. 13837@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression. 13838@end multitable 13839 13840@item @emph{Return Value}: 13841The result is a scalar integer with the kind type parameter specified by KIND 13842(or default integer type if KIND is missing). The result value is the size 13843expressed in bits for an element of an array that has the dynamic type and type 13844parameters of A. 13845 13846@item @emph{See also}: 13847@ref{C_SIZEOF}, @gol 13848@ref{SIZEOF} 13849@end table 13850 13851 13852 13853@node SUM 13854@section @code{SUM} --- Sum of array elements 13855@fnindex SUM 13856@cindex array, sum 13857@cindex array, add elements 13858@cindex array, conditionally add elements 13859@cindex sum array elements 13860 13861@table @asis 13862@item @emph{Description}: 13863Adds the elements of @var{ARRAY} along dimension @var{DIM} if 13864the corresponding element in @var{MASK} is @code{TRUE}. 13865 13866@item @emph{Standard}: 13867Fortran 90 and later 13868 13869@item @emph{Class}: 13870Transformational function 13871 13872@item @emph{Syntax}: 13873@multitable @columnfractions .80 13874@item @code{RESULT = SUM(ARRAY[, MASK])} 13875@item @code{RESULT = SUM(ARRAY, DIM[, MASK])} 13876@end multitable 13877 13878@item @emph{Arguments}: 13879@multitable @columnfractions .15 .70 13880@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 13881@code{REAL} or @code{COMPLEX}. 13882@item @var{DIM} @tab (Optional) shall be a scalar of type 13883@code{INTEGER} with a value in the range from 1 to n, where n 13884equals the rank of @var{ARRAY}. 13885@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 13886and either be a scalar or an array of the same shape as @var{ARRAY}. 13887@end multitable 13888 13889@item @emph{Return value}: 13890The result is of the same type as @var{ARRAY}. 13891 13892If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY} 13893is returned. Otherwise, an array of rank n-1, where n equals the rank of 13894@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} 13895dropped is returned. 13896 13897@item @emph{Example}: 13898@smallexample 13899PROGRAM test_sum 13900 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 13901 print *, SUM(x) ! all elements, sum = 15 13902 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9 13903END PROGRAM 13904@end smallexample 13905 13906@item @emph{See also}: 13907@ref{PRODUCT} 13908@end table 13909 13910 13911 13912@node SYMLNK 13913@section @code{SYMLNK} --- Create a symbolic link 13914@fnindex SYMLNK 13915@cindex file system, create link 13916@cindex file system, soft link 13917 13918@table @asis 13919@item @emph{Description}: 13920Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null 13921character (@code{CHAR(0)}) can be used to mark the end of the names in 13922@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 13923names are ignored. If the @var{STATUS} argument is supplied, it 13924contains 0 on success or a nonzero error code upon return; see 13925@code{symlink(2)}. If the system does not supply @code{symlink(2)}, 13926@code{ENOSYS} is returned. 13927 13928This intrinsic is provided in both subroutine and function forms; 13929however, only one form can be used in any given program unit. 13930 13931@item @emph{Standard}: 13932GNU extension 13933 13934@item @emph{Class}: 13935Subroutine, function 13936 13937@item @emph{Syntax}: 13938@multitable @columnfractions .80 13939@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])} 13940@item @code{STATUS = SYMLNK(PATH1, PATH2)} 13941@end multitable 13942 13943@item @emph{Arguments}: 13944@multitable @columnfractions .15 .70 13945@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 13946@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 13947@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13948@end multitable 13949 13950@item @emph{See also}: 13951@ref{LINK}, @gol 13952@ref{UNLINK} 13953@end table 13954 13955 13956 13957@node SYSTEM 13958@section @code{SYSTEM} --- Execute a shell command 13959@fnindex SYSTEM 13960@cindex system, system call 13961 13962@table @asis 13963@item @emph{Description}: 13964Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If 13965argument @var{STATUS} is present, it contains the value returned by 13966@code{system(3)}, which is presumably 0 if the shell command succeeded. 13967Note that which shell is used to invoke the command is system-dependent 13968and environment-dependent. 13969 13970This intrinsic is provided in both subroutine and function forms; 13971however, only one form can be used in any given program unit. 13972 13973Note that the @code{system} function need not be thread-safe. It is 13974the responsibility of the user to ensure that @code{system} is not 13975called concurrently. 13976 13977@item @emph{Standard}: 13978GNU extension 13979 13980@item @emph{Class}: 13981Subroutine, function 13982 13983@item @emph{Syntax}: 13984@multitable @columnfractions .80 13985@item @code{CALL SYSTEM(COMMAND [, STATUS])} 13986@item @code{STATUS = SYSTEM(COMMAND)} 13987@end multitable 13988 13989@item @emph{Arguments}: 13990@multitable @columnfractions .15 .70 13991@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type. 13992@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13993@end multitable 13994 13995@item @emph{See also}: 13996@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard 13997and should considered in new code for future portability. 13998@end table 13999 14000 14001 14002@node SYSTEM_CLOCK 14003@section @code{SYSTEM_CLOCK} --- Time function 14004@fnindex SYSTEM_CLOCK 14005@cindex time, clock ticks 14006@cindex clock ticks 14007 14008@table @asis 14009@item @emph{Description}: 14010Determines the @var{COUNT} of a processor clock since an unspecified 14011time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines 14012the number of clock ticks per second. If the platform supports a 14013monotonic clock, that clock is used and can, depending on the platform 14014clock implementation, provide up to nanosecond resolution. If a 14015monotonic clock is not available, the implementation falls back to a 14016realtime clock. 14017 14018@var{COUNT_RATE} is system dependent and can vary depending on the kind of 14019the arguments. For @var{kind=4} arguments (and smaller integer kinds), 14020@var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and 14021larger integer kinds), @var{COUNT} typically represents micro- or 14022nanoseconds depending on resolution of the underlying platform clock. 14023@var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the 14024millisecond resolution of the @var{kind=4} version implies that the 14025@var{COUNT} will wrap around in roughly 25 days. In order to avoid issues 14026with the wrap around and for more precise timing, please use the 14027@var{kind=8} version. 14028 14029If there is no clock, or querying the clock fails, @var{COUNT} is set 14030to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are 14031set to zero. 14032 14033When running on a platform using the GNU C library (glibc) version 140342.16 or older, or a derivative thereof, the high resolution monotonic 14035clock is available only when linking with the @var{rt} library. This 14036can be done explicitly by adding the @code{-lrt} flag when linking the 14037application, but is also done implicitly when using OpenMP. 14038 14039On the Windows platform, the version with @var{kind=4} arguments uses 14040the @code{GetTickCount} function, whereas the @var{kind=8} version 14041uses @code{QueryPerformanceCounter} and 14042@code{QueryPerformanceCounterFrequency}. For more information, and 14043potential caveats, please see the platform documentation. 14044 14045@item @emph{Standard}: 14046Fortran 90 and later 14047 14048@item @emph{Class}: 14049Subroutine 14050 14051@item @emph{Syntax}: 14052@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} 14053 14054@item @emph{Arguments}: 14055@multitable @columnfractions .20 .65 14056@item @var{COUNT} @tab (Optional) shall be a scalar of type 14057@code{INTEGER} with @code{INTENT(OUT)}. 14058@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type 14059@code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}. 14060@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type 14061@code{INTEGER} with @code{INTENT(OUT)}. 14062@end multitable 14063 14064@item @emph{Example}: 14065@smallexample 14066PROGRAM test_system_clock 14067 INTEGER :: count, count_rate, count_max 14068 CALL SYSTEM_CLOCK(count, count_rate, count_max) 14069 WRITE(*,*) count, count_rate, count_max 14070END PROGRAM 14071@end smallexample 14072 14073@item @emph{See also}: 14074@ref{DATE_AND_TIME}, @gol 14075@ref{CPU_TIME} 14076@end table 14077 14078 14079 14080@node TAN 14081@section @code{TAN} --- Tangent function 14082@fnindex TAN 14083@fnindex DTAN 14084@cindex trigonometric function, tangent 14085@cindex tangent 14086 14087@table @asis 14088@item @emph{Description}: 14089@code{TAN(X)} computes the tangent of @var{X}. 14090 14091@item @emph{Standard}: 14092Fortran 77 and later, for a complex argument Fortran 2008 or later 14093 14094@item @emph{Class}: 14095Elemental function 14096 14097@item @emph{Syntax}: 14098@code{RESULT = TAN(X)} 14099 14100@item @emph{Arguments}: 14101@multitable @columnfractions .15 .70 14102@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14103@end multitable 14104 14105@item @emph{Return value}: 14106The return value has same type and kind as @var{X}, and its value is in radians. 14107 14108@item @emph{Example}: 14109@smallexample 14110program test_tan 14111 real(8) :: x = 0.165_8 14112 x = tan(x) 14113end program test_tan 14114@end smallexample 14115 14116@item @emph{Specific names}: 14117@multitable @columnfractions .20 .23 .20 .33 14118@headitem Name @tab Argument @tab Return type @tab Standard 14119@item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 14120@item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 14121@end multitable 14122 14123@item @emph{See also}: 14124Inverse function: @gol 14125@ref{ATAN} @gol 14126Degrees function: @gol 14127@ref{TAND} 14128@end table 14129 14130 14131 14132@node TAND 14133@section @code{TAND} --- Tangent function, degrees 14134@fnindex TAND 14135@fnindex DTAND 14136@cindex trigonometric function, tangent, degrees 14137@cindex tangent, degrees 14138 14139@table @asis 14140@item @emph{Description}: 14141@code{TAND(X)} computes the tangent of @var{X} in degrees. 14142 14143This function is for compatibility only and should be avoided in favor of 14144standard constructs wherever possible. 14145 14146@item @emph{Standard}: 14147GNU extension, enabled with @option{-fdec-math}. 14148 14149@item @emph{Class}: 14150Elemental function 14151 14152@item @emph{Syntax}: 14153@code{RESULT = TAND(X)} 14154 14155@item @emph{Arguments}: 14156@multitable @columnfractions .15 .70 14157@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14158@end multitable 14159 14160@item @emph{Return value}: 14161The return value has same type and kind as @var{X}, and its value is in degrees. 14162 14163@item @emph{Example}: 14164@smallexample 14165program test_tand 14166 real(8) :: x = 0.165_8 14167 x = tand(x) 14168end program test_tand 14169@end smallexample 14170 14171@item @emph{Specific names}: 14172@multitable @columnfractions .20 .23 .20 .33 14173@headitem Name @tab Argument @tab Return type @tab Standard 14174@item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 14175@item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 14176@end multitable 14177 14178@item @emph{See also}: 14179Inverse function: @gol 14180@ref{ATAND} @gol 14181Radians function: @gol 14182@ref{TAN} 14183@end table 14184 14185 14186 14187@node TANH 14188@section @code{TANH} --- Hyperbolic tangent function 14189@fnindex TANH 14190@fnindex DTANH 14191@cindex hyperbolic tangent 14192@cindex hyperbolic function, tangent 14193@cindex tangent, hyperbolic 14194 14195@table @asis 14196@item @emph{Description}: 14197@code{TANH(X)} computes the hyperbolic tangent of @var{X}. 14198 14199@item @emph{Standard}: 14200Fortran 77 and later, for a complex argument Fortran 2008 or later 14201 14202@item @emph{Class}: 14203Elemental function 14204 14205@item @emph{Syntax}: 14206@code{X = TANH(X)} 14207 14208@item @emph{Arguments}: 14209@multitable @columnfractions .15 .70 14210@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14211@end multitable 14212 14213@item @emph{Return value}: 14214The return value has same type and kind as @var{X}. If @var{X} is 14215complex, the imaginary part of the result is in radians. If @var{X} 14216is @code{REAL}, the return value lies in the range 14217@math{ - 1 \leq tanh(x) \leq 1 }. 14218 14219@item @emph{Example}: 14220@smallexample 14221program test_tanh 14222 real(8) :: x = 2.1_8 14223 x = tanh(x) 14224end program test_tanh 14225@end smallexample 14226 14227@item @emph{Specific names}: 14228@multitable @columnfractions .20 .23 .20 .33 14229@headitem Name @tab Argument @tab Return type @tab Standard 14230@item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 14231@item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 14232@end multitable 14233 14234@item @emph{See also}: 14235@ref{ATANH} 14236@end table 14237 14238 14239 14240@node THIS_IMAGE 14241@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image 14242@fnindex THIS_IMAGE 14243@cindex coarray, @code{THIS_IMAGE} 14244@cindex images, index of this image 14245 14246@table @asis 14247@item @emph{Description}: 14248Returns the cosubscript for this image. 14249 14250@item @emph{Standard}: 14251Fortran 2008 and later. With @var{DISTANCE} argument, 14252Technical Specification (TS) 18508 or later 14253 14254@item @emph{Class}: 14255Transformational function 14256 14257@item @emph{Syntax}: 14258@multitable @columnfractions .80 14259@item @code{RESULT = THIS_IMAGE()} 14260@item @code{RESULT = THIS_IMAGE(DISTANCE)} 14261@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} 14262@end multitable 14263 14264@item @emph{Arguments}: 14265@multitable @columnfractions .15 .70 14266@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 14267(not permitted together with @var{COARRAY}). 14268@item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} 14269present, required). 14270@item @var{DIM} @tab default integer scalar (optional). If present, 14271@var{DIM} shall be between one and the corank of @var{COARRAY}. 14272@end multitable 14273 14274 14275@item @emph{Return value}: 14276Default integer. If @var{COARRAY} is not present, it is scalar; if 14277@var{DISTANCE} is not present or has value 0, its value is the image index on 14278the invoking image for the current team, for values smaller or equal 14279distance to the initial team, it returns the image index on the ancestor team 14280which has a distance of @var{DISTANCE} from the invoking team. If 14281@var{DISTANCE} is larger than the distance to the initial team, the image 14282index of the initial team is returned. Otherwise when the @var{COARRAY} is 14283present, if @var{DIM} is not present, a rank-1 array with corank elements is 14284returned, containing the cosubscripts for @var{COARRAY} specifying the invoking 14285image. If @var{DIM} is present, a scalar is returned, with the value of 14286the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}. 14287 14288@item @emph{Example}: 14289@smallexample 14290INTEGER :: value[*] 14291INTEGER :: i 14292value = THIS_IMAGE() 14293SYNC ALL 14294IF (THIS_IMAGE() == 1) THEN 14295 DO i = 1, NUM_IMAGES() 14296 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 14297 END DO 14298END IF 14299 14300! Check whether the current image is the initial image 14301IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) 14302 error stop "something is rotten here" 14303@end smallexample 14304 14305@item @emph{See also}: 14306@ref{NUM_IMAGES}, @gol 14307@ref{IMAGE_INDEX} 14308@end table 14309 14310 14311 14312@node TIME 14313@section @code{TIME} --- Time function 14314@fnindex TIME 14315@cindex time, current 14316@cindex current time 14317 14318@table @asis 14319@item @emph{Description}: 14320Returns the current time encoded as an integer (in the manner of the 14321function @code{time(3)} in the C standard library). This value is 14322suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 14323 14324This intrinsic is not fully portable, such as to systems with 32-bit 14325@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 14326the values returned by this intrinsic might be, or become, negative, or 14327numerically less than previous values, during a single run of the 14328compiled program. 14329 14330See @ref{TIME8}, for information on a similar intrinsic that might be 14331portable to more GNU Fortran implementations, though to fewer Fortran 14332compilers. 14333 14334@item @emph{Standard}: 14335GNU extension 14336 14337@item @emph{Class}: 14338Function 14339 14340@item @emph{Syntax}: 14341@code{RESULT = TIME()} 14342 14343@item @emph{Return value}: 14344The return value is a scalar of type @code{INTEGER(4)}. 14345 14346@item @emph{See also}: 14347@ref{DATE_AND_TIME}, @gol 14348@ref{CTIME}, @gol 14349@ref{GMTIME}, @gol 14350@ref{LTIME}, @gol 14351@ref{MCLOCK}, @gol 14352@ref{TIME8} 14353@end table 14354 14355 14356 14357@node TIME8 14358@section @code{TIME8} --- Time function (64-bit) 14359@fnindex TIME8 14360@cindex time, current 14361@cindex current time 14362 14363@table @asis 14364@item @emph{Description}: 14365Returns the current time encoded as an integer (in the manner of the 14366function @code{time(3)} in the C standard library). This value is 14367suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 14368 14369@emph{Warning:} this intrinsic does not increase the range of the timing 14370values over that returned by @code{time(3)}. On a system with a 32-bit 14371@code{time(3)}, @code{TIME8} will return a 32-bit value, even though 14372it is converted to a 64-bit @code{INTEGER(8)} value. That means 14373overflows of the 32-bit value can still occur. Therefore, the values 14374returned by this intrinsic might be or become negative or numerically 14375less than previous values during a single run of the compiled program. 14376 14377@item @emph{Standard}: 14378GNU extension 14379 14380@item @emph{Class}: 14381Function 14382 14383@item @emph{Syntax}: 14384@code{RESULT = TIME8()} 14385 14386@item @emph{Return value}: 14387The return value is a scalar of type @code{INTEGER(8)}. 14388 14389@item @emph{See also}: 14390@ref{DATE_AND_TIME}, @gol 14391@ref{CTIME}, @gol 14392@ref{GMTIME}, @gol 14393@ref{LTIME}, @gol 14394@ref{MCLOCK8}, @gol 14395@ref{TIME} 14396@end table 14397 14398 14399 14400@node TINY 14401@section @code{TINY} --- Smallest positive number of a real kind 14402@fnindex TINY 14403@cindex limits, smallest number 14404@cindex model representation, smallest number 14405 14406@table @asis 14407@item @emph{Description}: 14408@code{TINY(X)} returns the smallest positive (non zero) number 14409in the model of the type of @code{X}. 14410 14411@item @emph{Standard}: 14412Fortran 90 and later 14413 14414@item @emph{Class}: 14415Inquiry function 14416 14417@item @emph{Syntax}: 14418@code{RESULT = TINY(X)} 14419 14420@item @emph{Arguments}: 14421@multitable @columnfractions .15 .70 14422@item @var{X} @tab Shall be of type @code{REAL}. 14423@end multitable 14424 14425@item @emph{Return value}: 14426The return value is of the same type and kind as @var{X} 14427 14428@item @emph{Example}: 14429See @code{HUGE} for an example. 14430@end table 14431 14432 14433 14434@node TRAILZ 14435@section @code{TRAILZ} --- Number of trailing zero bits of an integer 14436@fnindex TRAILZ 14437@cindex zero bits 14438 14439@table @asis 14440@item @emph{Description}: 14441@code{TRAILZ} returns the number of trailing zero bits of an integer. 14442 14443@item @emph{Standard}: 14444Fortran 2008 and later 14445 14446@item @emph{Class}: 14447Elemental function 14448 14449@item @emph{Syntax}: 14450@code{RESULT = TRAILZ(I)} 14451 14452@item @emph{Arguments}: 14453@multitable @columnfractions .15 .70 14454@item @var{I} @tab Shall be of type @code{INTEGER}. 14455@end multitable 14456 14457@item @emph{Return value}: 14458The type of the return value is the default @code{INTEGER}. 14459If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 14460 14461@item @emph{Example}: 14462@smallexample 14463PROGRAM test_trailz 14464 WRITE (*,*) TRAILZ(8) ! prints 3 14465END PROGRAM 14466@end smallexample 14467 14468@item @emph{See also}: 14469@ref{BIT_SIZE}, @gol 14470@ref{LEADZ}, @gol 14471@ref{POPPAR}, @gol 14472@ref{POPCNT} 14473@end table 14474 14475 14476 14477@node TRANSFER 14478@section @code{TRANSFER} --- Transfer bit patterns 14479@fnindex TRANSFER 14480@cindex bits, move 14481@cindex type cast 14482 14483@table @asis 14484@item @emph{Description}: 14485Interprets the bitwise representation of @var{SOURCE} in memory as if it 14486is the representation of a variable or array of the same type and type 14487parameters as @var{MOLD}. 14488 14489This is approximately equivalent to the C concept of @emph{casting} one 14490type to another. 14491 14492@item @emph{Standard}: 14493Fortran 90 and later 14494 14495@item @emph{Class}: 14496Transformational function 14497 14498@item @emph{Syntax}: 14499@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])} 14500 14501@item @emph{Arguments}: 14502@multitable @columnfractions .15 .70 14503@item @var{SOURCE} @tab Shall be a scalar or an array of any type. 14504@item @var{MOLD} @tab Shall be a scalar or an array of any type. 14505@item @var{SIZE} @tab (Optional) shall be a scalar of type 14506@code{INTEGER}. 14507@end multitable 14508 14509@item @emph{Return value}: 14510The result has the same type as @var{MOLD}, with the bit level 14511representation of @var{SOURCE}. If @var{SIZE} is present, the result is 14512a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent 14513but @var{MOLD} is an array (of any size or shape), the result is a one- 14514dimensional array of the minimum length needed to contain the entirety 14515of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent 14516and @var{MOLD} is a scalar, the result is a scalar. 14517 14518If the bitwise representation of the result is longer than that of 14519@var{SOURCE}, then the leading bits of the result correspond to those of 14520@var{SOURCE} and any trailing bits are filled arbitrarily. 14521 14522When the resulting bit representation does not correspond to a valid 14523representation of a variable of the same type as @var{MOLD}, the results 14524are undefined, and subsequent operations on the result cannot be 14525guaranteed to produce sensible behavior. For example, it is possible to 14526create @code{LOGICAL} variables for which @code{@var{VAR}} and 14527@code{.NOT.@var{VAR}} both appear to be true. 14528 14529@item @emph{Example}: 14530@smallexample 14531PROGRAM test_transfer 14532 integer :: x = 2143289344 14533 print *, transfer(x, 1.0) ! prints "NaN" on i686 14534END PROGRAM 14535@end smallexample 14536@end table 14537 14538 14539 14540@node TRANSPOSE 14541@section @code{TRANSPOSE} --- Transpose an array of rank two 14542@fnindex TRANSPOSE 14543@cindex array, transpose 14544@cindex matrix, transpose 14545@cindex transpose 14546 14547@table @asis 14548@item @emph{Description}: 14549Transpose an array of rank two. Element (i, j) of the result has the value 14550@code{MATRIX(j, i)}, for all i, j. 14551 14552@item @emph{Standard}: 14553Fortran 90 and later 14554 14555@item @emph{Class}: 14556Transformational function 14557 14558@item @emph{Syntax}: 14559@code{RESULT = TRANSPOSE(MATRIX)} 14560 14561@item @emph{Arguments}: 14562@multitable @columnfractions .15 .70 14563@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two. 14564@end multitable 14565 14566@item @emph{Return value}: 14567The result has the same type as @var{MATRIX}, and has shape 14568@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}. 14569@end table 14570 14571 14572 14573@node TRIM 14574@section @code{TRIM} --- Remove trailing blank characters of a string 14575@fnindex TRIM 14576@cindex string, remove trailing whitespace 14577 14578@table @asis 14579@item @emph{Description}: 14580Removes trailing blank characters of a string. 14581 14582@item @emph{Standard}: 14583Fortran 90 and later 14584 14585@item @emph{Class}: 14586Transformational function 14587 14588@item @emph{Syntax}: 14589@code{RESULT = TRIM(STRING)} 14590 14591@item @emph{Arguments}: 14592@multitable @columnfractions .15 .70 14593@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}. 14594@end multitable 14595 14596@item @emph{Return value}: 14597A scalar of type @code{CHARACTER} which length is that of @var{STRING} 14598less the number of trailing blanks. 14599 14600@item @emph{Example}: 14601@smallexample 14602PROGRAM test_trim 14603 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " 14604 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks 14605END PROGRAM 14606@end smallexample 14607 14608@item @emph{See also}: 14609@ref{ADJUSTL}, @gol 14610@ref{ADJUSTR} 14611@end table 14612 14613 14614 14615@node TTYNAM 14616@section @code{TTYNAM} --- Get the name of a terminal device. 14617@fnindex TTYNAM 14618@cindex system, terminal 14619 14620@table @asis 14621@item @emph{Description}: 14622Get the name of a terminal device. For more information, 14623see @code{ttyname(3)}. 14624 14625This intrinsic is provided in both subroutine and function forms; 14626however, only one form can be used in any given program unit. 14627 14628@item @emph{Standard}: 14629GNU extension 14630 14631@item @emph{Class}: 14632Subroutine, function 14633 14634@item @emph{Syntax}: 14635@multitable @columnfractions .80 14636@item @code{CALL TTYNAM(UNIT, NAME)} 14637@item @code{NAME = TTYNAM(UNIT)} 14638@end multitable 14639 14640@item @emph{Arguments}: 14641@multitable @columnfractions .15 .70 14642@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 14643@item @var{NAME} @tab Shall be of type @code{CHARACTER}. 14644@end multitable 14645 14646@item @emph{Example}: 14647@smallexample 14648PROGRAM test_ttynam 14649 INTEGER :: unit 14650 DO unit = 1, 10 14651 IF (isatty(unit=unit)) write(*,*) ttynam(unit) 14652 END DO 14653END PROGRAM 14654@end smallexample 14655 14656@item @emph{See also}: 14657@ref{ISATTY} 14658@end table 14659 14660 14661 14662@node UBOUND 14663@section @code{UBOUND} --- Upper dimension bounds of an array 14664@fnindex UBOUND 14665@cindex array, upper bound 14666 14667@table @asis 14668@item @emph{Description}: 14669Returns the upper bounds of an array, or a single upper bound 14670along the @var{DIM} dimension. 14671@item @emph{Standard}: 14672Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 14673 14674@item @emph{Class}: 14675Inquiry function 14676 14677@item @emph{Syntax}: 14678@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])} 14679 14680@item @emph{Arguments}: 14681@multitable @columnfractions .15 .70 14682@item @var{ARRAY} @tab Shall be an array, of any type. 14683@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14684@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization 14685expression indicating the kind parameter of the result. 14686@end multitable 14687 14688@item @emph{Return value}: 14689The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14690@var{KIND} is absent, the return value is of default integer kind. 14691If @var{DIM} is absent, the result is an array of the upper bounds of 14692@var{ARRAY}. If @var{DIM} is present, the result is a scalar 14693corresponding to the upper bound of the array along that dimension. If 14694@var{ARRAY} is an expression rather than a whole array or array 14695structure component, or if it has a zero extent along the relevant 14696dimension, the upper bound is taken to be the number of elements along 14697the relevant dimension. 14698 14699@item @emph{See also}: 14700@ref{LBOUND}, @gol 14701@ref{LCOBOUND} 14702@end table 14703 14704 14705 14706@node UCOBOUND 14707@section @code{UCOBOUND} --- Upper codimension bounds of an array 14708@fnindex UCOBOUND 14709@cindex coarray, upper bound 14710 14711@table @asis 14712@item @emph{Description}: 14713Returns the upper cobounds of a coarray, or a single upper cobound 14714along the @var{DIM} codimension. 14715@item @emph{Standard}: 14716Fortran 2008 and later 14717 14718@item @emph{Class}: 14719Inquiry function 14720 14721@item @emph{Syntax}: 14722@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])} 14723 14724@item @emph{Arguments}: 14725@multitable @columnfractions .15 .70 14726@item @var{ARRAY} @tab Shall be an coarray, of any type. 14727@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14728@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14729expression indicating the kind parameter of the result. 14730@end multitable 14731 14732@item @emph{Return value}: 14733The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14734@var{KIND} is absent, the return value is of default integer kind. 14735If @var{DIM} is absent, the result is an array of the lower cobounds of 14736@var{COARRAY}. If @var{DIM} is present, the result is a scalar 14737corresponding to the lower cobound of the array along that codimension. 14738 14739@item @emph{See also}: 14740@ref{LCOBOUND}, @gol 14741@ref{LBOUND} 14742@end table 14743 14744 14745 14746@node UMASK 14747@section @code{UMASK} --- Set the file creation mask 14748@fnindex UMASK 14749@cindex file system, file creation mask 14750 14751@table @asis 14752@item @emph{Description}: 14753Sets the file creation mask to @var{MASK}. If called as a function, it 14754returns the old value. If called as a subroutine and argument @var{OLD} 14755if it is supplied, it is set to the old value. See @code{umask(2)}. 14756 14757@item @emph{Standard}: 14758GNU extension 14759 14760@item @emph{Class}: 14761Subroutine, function 14762 14763@item @emph{Syntax}: 14764@multitable @columnfractions .80 14765@item @code{CALL UMASK(MASK [, OLD])} 14766@item @code{OLD = UMASK(MASK)} 14767@end multitable 14768 14769@item @emph{Arguments}: 14770@multitable @columnfractions .15 .70 14771@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}. 14772@item @var{OLD} @tab (Optional) Shall be a scalar of type 14773@code{INTEGER}. 14774@end multitable 14775 14776@end table 14777 14778 14779 14780@node UNLINK 14781@section @code{UNLINK} --- Remove a file from the file system 14782@fnindex UNLINK 14783@cindex file system, remove file 14784 14785@table @asis 14786@item @emph{Description}: 14787Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be 14788used to mark the end of the name in @var{PATH}; otherwise, trailing 14789blanks in the file name are ignored. If the @var{STATUS} argument is 14790supplied, it contains 0 on success or a nonzero error code upon return; 14791see @code{unlink(2)}. 14792 14793This intrinsic is provided in both subroutine and function forms; 14794however, only one form can be used in any given program unit. 14795 14796@item @emph{Standard}: 14797GNU extension 14798 14799@item @emph{Class}: 14800Subroutine, function 14801 14802@item @emph{Syntax}: 14803@multitable @columnfractions .80 14804@item @code{CALL UNLINK(PATH [, STATUS])} 14805@item @code{STATUS = UNLINK(PATH)} 14806@end multitable 14807 14808@item @emph{Arguments}: 14809@multitable @columnfractions .15 .70 14810@item @var{PATH} @tab Shall be of default @code{CHARACTER} type. 14811@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 14812@end multitable 14813 14814@item @emph{See also}: 14815@ref{LINK}, @gol 14816@ref{SYMLNK} 14817@end table 14818 14819 14820 14821@node UNPACK 14822@section @code{UNPACK} --- Unpack an array of rank one into an array 14823@fnindex UNPACK 14824@cindex array, unpacking 14825@cindex array, increase dimension 14826@cindex array, scatter elements 14827 14828@table @asis 14829@item @emph{Description}: 14830Store the elements of @var{VECTOR} in an array of higher rank. 14831 14832@item @emph{Standard}: 14833Fortran 90 and later 14834 14835@item @emph{Class}: 14836Transformational function 14837 14838@item @emph{Syntax}: 14839@code{RESULT = UNPACK(VECTOR, MASK, FIELD)} 14840 14841@item @emph{Arguments}: 14842@multitable @columnfractions .15 .70 14843@item @var{VECTOR} @tab Shall be an array of any type and rank one. It 14844shall have at least as many elements as @var{MASK} has @code{TRUE} values. 14845@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}. 14846@item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have 14847the same shape as @var{MASK}. 14848@end multitable 14849 14850@item @emph{Return value}: 14851The resulting array corresponds to @var{FIELD} with @code{TRUE} elements 14852of @var{MASK} replaced by values from @var{VECTOR} in array element order. 14853 14854@item @emph{Example}: 14855@smallexample 14856PROGRAM test_unpack 14857 integer :: vector(2) = (/1,1/) 14858 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /) 14859 integer :: field(2,2) = 0, unity(2,2) 14860 14861 ! result: unity matrix 14862 unity = unpack(vector, reshape(mask, (/2,2/)), field) 14863END PROGRAM 14864@end smallexample 14865 14866@item @emph{See also}: 14867@ref{PACK}, @gol 14868@ref{SPREAD} 14869@end table 14870 14871 14872 14873@node VERIFY 14874@section @code{VERIFY} --- Scan a string for characters not a given set 14875@fnindex VERIFY 14876@cindex string, find missing set 14877 14878@table @asis 14879@item @emph{Description}: 14880Verifies that all the characters in @var{STRING} belong to the set of 14881characters in @var{SET}. 14882 14883If @var{BACK} is either absent or equals @code{FALSE}, this function 14884returns the position of the leftmost character of @var{STRING} that is 14885not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost 14886position is returned. If all characters of @var{STRING} are found in 14887@var{SET}, the result is zero. 14888 14889@item @emph{Standard}: 14890Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 14891 14892@item @emph{Class}: 14893Elemental function 14894 14895@item @emph{Syntax}: 14896@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])} 14897 14898@item @emph{Arguments}: 14899@multitable @columnfractions .15 .70 14900@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 14901@item @var{SET} @tab Shall be of type @code{CHARACTER}. 14902@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 14903@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14904expression indicating the kind parameter of the result. 14905@end multitable 14906 14907@item @emph{Return value}: 14908The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14909@var{KIND} is absent, the return value is of default integer kind. 14910 14911@item @emph{Example}: 14912@smallexample 14913PROGRAM test_verify 14914 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F' 14915 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R' 14916 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F' 14917 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N' 14918 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none 14919END PROGRAM 14920@end smallexample 14921 14922@item @emph{See also}: 14923@ref{SCAN}, @gol 14924@ref{INDEX intrinsic} 14925@end table 14926 14927 14928 14929@node XOR 14930@section @code{XOR} --- Bitwise logical exclusive OR 14931@fnindex XOR 14932@cindex bitwise logical exclusive or 14933@cindex logical exclusive or, bitwise 14934 14935@table @asis 14936@item @emph{Description}: 14937Bitwise logical exclusive or. 14938 14939This intrinsic routine is provided for backwards compatibility with 14940GNU Fortran 77. For integer arguments, programmers should consider 14941the use of the @ref{IEOR} intrinsic and for logical arguments the 14942@code{.NEQV.} operator, which are both defined by the Fortran standard. 14943 14944@item @emph{Standard}: 14945GNU extension 14946 14947@item @emph{Class}: 14948Function 14949 14950@item @emph{Syntax}: 14951@code{RESULT = XOR(I, J)} 14952 14953@item @emph{Arguments}: 14954@multitable @columnfractions .15 .70 14955@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 14956type or a scalar @code{LOGICAL} type or a boz-literal-constant. 14957@item @var{J} @tab The type shall be the same as the type of @var{I} or 14958a boz-literal-constant. @var{I} and @var{J} shall not both be 14959boz-literal-constants. If either @var{I} and @var{J} is a 14960boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 14961@end multitable 14962 14963@item @emph{Return value}: 14964The return type is either a scalar @code{INTEGER} or a scalar 14965@code{LOGICAL}. If the kind type parameters differ, then the 14966smaller kind type is implicitly converted to larger kind, and the 14967return has the larger kind. A boz-literal-constant is 14968converted to an @code{INTEGER} with the kind type parameter of 14969the other argument as-if a call to @ref{INT} occurred. 14970 14971@item @emph{Example}: 14972@smallexample 14973PROGRAM test_xor 14974 LOGICAL :: T = .TRUE., F = .FALSE. 14975 INTEGER :: a, b 14976 DATA a / Z'F' /, b / Z'3' / 14977 14978 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F) 14979 WRITE (*,*) XOR(a, b) 14980END PROGRAM 14981@end smallexample 14982 14983@item @emph{See also}: 14984Fortran 95 elemental function: @gol 14985@ref{IEOR} 14986@end table 14987 14988 14989 14990@node Intrinsic Modules 14991@chapter Intrinsic Modules 14992@cindex intrinsic Modules 14993 14994@menu 14995* ISO_FORTRAN_ENV:: 14996* ISO_C_BINDING:: 14997* IEEE modules:: 14998* OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: 14999* OpenACC Module OPENACC:: 15000@end menu 15001 15002@node ISO_FORTRAN_ENV 15003@section @code{ISO_FORTRAN_ENV} 15004@table @asis 15005@item @emph{Standard}: 15006Fortran 2003 and later, except when otherwise noted 15007@end table 15008 15009The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer 15010named constants: 15011 15012@table @asis 15013@item @code{ATOMIC_INT_KIND}: 15014Default-kind integer constant to be used as kind parameter when defining 15015integer variables used in atomic operations. (Fortran 2008 or later.) 15016 15017@item @code{ATOMIC_LOGICAL_KIND}: 15018Default-kind integer constant to be used as kind parameter when defining 15019logical variables used in atomic operations. (Fortran 2008 or later.) 15020 15021@item @code{CHARACTER_KINDS}: 15022Default-kind integer constant array of rank one containing the supported kind 15023parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) 15024 15025@item @code{CHARACTER_STORAGE_SIZE}: 15026Size in bits of the character storage unit. 15027 15028@item @code{ERROR_UNIT}: 15029Identifies the preconnected unit used for error reporting. 15030 15031@item @code{FILE_STORAGE_SIZE}: 15032Size in bits of the file-storage unit. 15033 15034@item @code{INPUT_UNIT}: 15035Identifies the preconnected unit identified by the asterisk 15036(@code{*}) in @code{READ} statement. 15037 15038@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}: 15039Kind type parameters to specify an INTEGER type with a storage 15040size of 16, 32, and 64 bits. It is negative if a target platform 15041does not support the particular kind. (Fortran 2008 or later.) 15042 15043@item @code{INTEGER_KINDS}: 15044Default-kind integer constant array of rank one containing the supported kind 15045parameters of the @code{INTEGER} type. (Fortran 2008 or later.) 15046 15047@item @code{IOSTAT_END}: 15048The value assigned to the variable passed to the @code{IOSTAT=} specifier of 15049an input/output statement if an end-of-file condition occurred. 15050 15051@item @code{IOSTAT_EOR}: 15052The value assigned to the variable passed to the @code{IOSTAT=} specifier of 15053an input/output statement if an end-of-record condition occurred. 15054 15055@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}: 15056Scalar default-integer constant, used by @code{INQUIRE} for the 15057@code{IOSTAT=} specifier to denote an that a unit number identifies an 15058internal unit. (Fortran 2008 or later.) 15059 15060@item @code{NUMERIC_STORAGE_SIZE}: 15061The size in bits of the numeric storage unit. 15062 15063@item @code{LOGICAL_KINDS}: 15064Default-kind integer constant array of rank one containing the supported kind 15065parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) 15066 15067@item @code{OUTPUT_UNIT}: 15068Identifies the preconnected unit identified by the asterisk 15069(@code{*}) in @code{WRITE} statement. 15070 15071@item @code{REAL32}, @code{REAL64}, @code{REAL128}: 15072Kind type parameters to specify a REAL type with a storage 15073size of 32, 64, and 128 bits. It is negative if a target platform 15074does not support the particular kind. (Fortran 2008 or later.) 15075 15076@item @code{REAL_KINDS}: 15077Default-kind integer constant array of rank one containing the supported kind 15078parameters of the @code{REAL} type. (Fortran 2008 or later.) 15079 15080@item @code{STAT_LOCKED}: 15081Scalar default-integer constant used as STAT= return value by @code{LOCK} to 15082denote that the lock variable is locked by the executing image. (Fortran 2008 15083or later.) 15084 15085@item @code{STAT_LOCKED_OTHER_IMAGE}: 15086Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 15087denote that the lock variable is locked by another image. (Fortran 2008 or 15088later.) 15089 15090@item @code{STAT_STOPPED_IMAGE}: 15091Positive, scalar default-integer constant used as STAT= return value if the 15092argument in the statement requires synchronisation with an image, which has 15093initiated the termination of the execution. (Fortran 2008 or later.) 15094 15095@item @code{STAT_FAILED_IMAGE}: 15096Positive, scalar default-integer constant used as STAT= return value if the 15097argument in the statement requires communication with an image, which has 15098is in the failed state. (TS 18508 or later.) 15099 15100@item @code{STAT_UNLOCKED}: 15101Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 15102denote that the lock variable is unlocked. (Fortran 2008 or later.) 15103@end table 15104 15105The module provides the following derived type: 15106 15107@table @asis 15108@item @code{LOCK_TYPE}: 15109Derived type with private components to be use with the @code{LOCK} and 15110@code{UNLOCK} statement. A variable of its type has to be always declared 15111as coarray and may not appear in a variable-definition context. 15112(Fortran 2008 or later.) 15113@end table 15114 15115The module also provides the following intrinsic procedures: 15116@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}. 15117 15118 15119 15120@node ISO_C_BINDING 15121@section @code{ISO_C_BINDING} 15122@table @asis 15123@item @emph{Standard}: 15124Fortran 2003 and later, GNU extensions 15125@end table 15126 15127The following intrinsic procedures are provided by the module; their 15128definition can be found in the section Intrinsic Procedures of this 15129manual. 15130 15131@table @asis 15132@item @code{C_ASSOCIATED} 15133@item @code{C_F_POINTER} 15134@item @code{C_F_PROCPOINTER} 15135@item @code{C_FUNLOC} 15136@item @code{C_LOC} 15137@item @code{C_SIZEOF} 15138@end table 15139@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF, 15140@c don't really know why. 15141 15142The @code{ISO_C_BINDING} module provides the following named constants of 15143type default integer, which can be used as KIND type parameters. 15144 15145In addition to the integer named constants required by the Fortran 2003 15146standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an 15147extension named constants for the 128-bit integer types supported by the 15148C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}. 15149Furthermore, if @code{_Float128} is supported in C, the named constants 15150@code{C_FLOAT128} and @code{C_FLOAT128_COMPLEX} are defined. 15151 15152@multitable @columnfractions .19 .32 .34 .15 15153@headitem Fortran Type @tab Named constant @tab C type @tab Extension 15154@item @code{INTEGER}@tab @code{C_INT} @tab @code{int} 15155@item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int} 15156@item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int} 15157@item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int} 15158@item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char} 15159@item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t} 15160@item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t} 15161@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t} 15162@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t} 15163@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t} 15164@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext. 15165@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t} 15166@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t} 15167@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t} 15168@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t} 15169@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext. 15170@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t} 15171@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t} 15172@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t} 15173@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t} 15174@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext. 15175@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t} 15176@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t} 15177@item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113 15178@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float} 15179@item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double} 15180@item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double} 15181@item @code{REAL} @tab @code{C_FLOAT128} @tab @code{_Float128} @tab Ext. 15182@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex} 15183@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex} 15184@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex} 15185@item @code{COMPLEX}@tab @code{C_FLOAT128_COMPLEX} @tab @code{_Float128 _Complex} @tab Ext. 15186@item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool} 15187@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char} 15188@end multitable 15189 15190Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)} 15191are defined. 15192 15193@multitable @columnfractions .20 .45 .15 15194@headitem Name @tab C definition @tab Value 15195@item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'} 15196@item @code{C_ALERT} @tab alert @tab @code{'\a'} 15197@item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'} 15198@item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'} 15199@item @code{C_NEW_LINE} @tab new line @tab @code{'\n'} 15200@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'} 15201@item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'} 15202@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'} 15203@end multitable 15204 15205Moreover, the following two named constants are defined: 15206 15207@multitable @columnfractions .20 .80 15208@headitem Name @tab Type 15209@item @code{C_NULL_PTR} @tab @code{C_PTR} 15210@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR} 15211@end multitable 15212 15213Both are equivalent to the value @code{NULL} in C. 15214 15215 15216 15217@node IEEE modules 15218@section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 15219@table @asis 15220@item @emph{Standard}: 15221Fortran 2003 and later 15222@end table 15223 15224The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 15225intrinsic modules provide support for exceptions and IEEE arithmetic, as 15226defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard 15227(@emph{Binary floating-point arithmetic for microprocessor systems}). These 15228modules are only provided on the following supported platforms: 15229 15230@itemize @bullet 15231@item i386 and x86_64 processors 15232@item platforms which use the GNU C Library (glibc) 15233@item platforms with support for SysV/386 routines for floating point 15234interface (including Solaris and BSDs) 15235@item platforms with the AIX OS 15236@end itemize 15237 15238For full compliance with the Fortran standards, code using the 15239@code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled 15240with the following options: @code{-fno-unsafe-math-optimizations 15241-frounding-math -fsignaling-nans}. 15242 15243 15244 15245@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS 15246@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS} 15247@table @asis 15248@item @emph{Standard}: 15249OpenMP Application Program Interface v4.5, 15250OpenMP Application Program Interface v5.0 (partially supported) and 15251OpenMP Application Program Interface v5.1 (partially supported). 15252@end table 15253 15254The OpenMP Fortran runtime library routines are provided both in 15255a form of two Fortran modules, named @code{OMP_LIB} and 15256@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named 15257@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found 15258in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi 15259Processing Runtime Library} manual, 15260the named constants defined in the modules are listed 15261below. 15262 15263For details refer to the actual 15264@uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf, 15265OpenMP Application Program Interface v4.5} and 15266@uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf, 15267OpenMP Application Program Interface v5.0}. 15268 15269@code{OMP_LIB_KINDS} provides the following scalar default-integer 15270named constants: 15271 15272@table @asis 15273@item @code{omp_allocator_handle_kind} 15274@item @code{omp_alloctrait_key_kind} 15275@item @code{omp_alloctrait_val_kind} 15276@item @code{omp_depend_kind} 15277@item @code{omp_lock_kind} 15278@item @code{omp_lock_hint_kind} 15279@item @code{omp_nest_lock_kind} 15280@item @code{omp_pause_resource_kind} 15281@item @code{omp_memspace_handle_kind} 15282@item @code{omp_proc_bind_kind} 15283@item @code{omp_sched_kind} 15284@item @code{omp_sync_hint_kind} 15285@end table 15286 15287@code{OMP_LIB} provides the scalar default-integer 15288named constant @code{openmp_version} with a value of the form 15289@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 15290of the OpenMP version; for OpenMP v4.5 the value is @code{201511}. 15291 15292The following derived type: 15293 15294@table @asis 15295@item @code{omp_alloctrait} 15296@end table 15297 15298The following scalar integer named constants of the 15299kind @code{omp_sched_kind}: 15300 15301@table @asis 15302@item @code{omp_sched_static} 15303@item @code{omp_sched_dynamic} 15304@item @code{omp_sched_guided} 15305@item @code{omp_sched_auto} 15306@end table 15307 15308And the following scalar integer named constants of the 15309kind @code{omp_proc_bind_kind}: 15310 15311@table @asis 15312@item @code{omp_proc_bind_false} 15313@item @code{omp_proc_bind_true} 15314@item @code{omp_proc_bind_primary} 15315@item @code{omp_proc_bind_master} 15316@item @code{omp_proc_bind_close} 15317@item @code{omp_proc_bind_spread} 15318@end table 15319 15320The following scalar integer named constants are of the 15321kind @code{omp_lock_hint_kind}: 15322 15323@table @asis 15324@item @code{omp_lock_hint_none} 15325@item @code{omp_lock_hint_uncontended} 15326@item @code{omp_lock_hint_contended} 15327@item @code{omp_lock_hint_nonspeculative} 15328@item @code{omp_lock_hint_speculative} 15329@item @code{omp_sync_hint_none} 15330@item @code{omp_sync_hint_uncontended} 15331@item @code{omp_sync_hint_contended} 15332@item @code{omp_sync_hint_nonspeculative} 15333@item @code{omp_sync_hint_speculative} 15334@end table 15335 15336And the following two scalar integer named constants are of the 15337kind @code{omp_pause_resource_kind}: 15338 15339@table @asis 15340@item @code{omp_pause_soft} 15341@item @code{omp_pause_hard} 15342@end table 15343 15344The following scalar integer named constants are of the kind 15345@code{omp_alloctrait_key_kind}: 15346 15347@table @asis 15348@item @code{omp_atk_sync_hint} 15349@item @code{omp_atk_alignment} 15350@item @code{omp_atk_access} 15351@item @code{omp_atk_pool_size} 15352@item @code{omp_atk_fallback} 15353@item @code{omp_atk_fb_data} 15354@item @code{omp_atk_pinned} 15355@item @code{omp_atk_partition} 15356@end table 15357 15358The following scalar integer named constants are of the kind 15359@code{omp_alloctrait_val_kind}: 15360 15361@table @asis 15362@code{omp_alloctrait_key_kind}: 15363@item @code{omp_atv_default} 15364@item @code{omp_atv_false} 15365@item @code{omp_atv_true} 15366@item @code{omp_atv_contended} 15367@item @code{omp_atv_uncontended} 15368@item @code{omp_atv_serialized} 15369@item @code{omp_atv_sequential} 15370@item @code{omp_atv_private} 15371@item @code{omp_atv_all} 15372@item @code{omp_atv_thread} 15373@item @code{omp_atv_pteam} 15374@item @code{omp_atv_cgroup} 15375@item @code{omp_atv_default_mem_fb} 15376@item @code{omp_atv_null_fb} 15377@item @code{omp_atv_abort_fb} 15378@item @code{omp_atv_allocator_fb} 15379@item @code{omp_atv_environment} 15380@item @code{omp_atv_nearest} 15381@item @code{omp_atv_blocked} 15382@end table 15383 15384The following scalar integer named constants are of the kind 15385@code{omp_allocator_handle_kind}: 15386 15387@table @asis 15388@item @code{omp_null_allocator} 15389@item @code{omp_default_mem_alloc} 15390@item @code{omp_large_cap_mem_alloc} 15391@item @code{omp_const_mem_alloc} 15392@item @code{omp_high_bw_mem_alloc} 15393@item @code{omp_low_lat_mem_alloc} 15394@item @code{omp_cgroup_mem_alloc} 15395@item @code{omp_pteam_mem_alloc} 15396@item @code{omp_thread_mem_alloc} 15397@end table 15398 15399The following scalar integer named constants are of the kind 15400@code{omp_memspace_handle_kind}: 15401 15402@table @asis 15403@item @code{omp_default_mem_space} 15404@item @code{omp_large_cap_mem_space} 15405@item @code{omp_const_mem_space} 15406@item @code{omp_high_bw_mem_space} 15407@item @code{omp_low_lat_mem_space} 15408@end table 15409 15410 15411 15412@node OpenACC Module OPENACC 15413@section OpenACC Module @code{OPENACC} 15414@table @asis 15415@item @emph{Standard}: 15416OpenACC Application Programming Interface v2.6 15417@end table 15418 15419 15420The OpenACC Fortran runtime library routines are provided both in a 15421form of a Fortran 90 module, named @code{OPENACC}, and in form of a 15422Fortran @code{include} file named @file{openacc_lib.h}. The 15423procedures provided by @code{OPENACC} can be found in the 15424@ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing 15425Runtime Library} manual, the named constants defined in the modules 15426are listed below. 15427 15428For details refer to the actual 15429@uref{http://www.openacc.org/, 15430OpenACC Application Programming Interface v2.6}. 15431 15432@code{OPENACC} provides the scalar default-integer 15433named constant @code{openacc_version} with a value of the form 15434@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 15435of the OpenACC version; for OpenACC v2.6 the value is @code{201711}. 15436