1@ignore 2Copyright (C) 2005-2020 Free Software Foundation, Inc. 3This is part of the GNU Fortran manual. 4For copying conditions, see the file gfortran.texi. 5 6Permission is granted to copy, distribute and/or modify this document 7under the terms of the GNU Free Documentation License, Version 1.3 or 8any later version published by the Free Software Foundation; with the 9Invariant Sections being ``Funding Free Software'', the Front-Cover 10Texts being (a) (see below), and with the Back-Cover Texts being (b) 11(see below). A copy of the license is included in the gfdl(7) man page. 12 13 14Some basic guidelines for editing this document: 15 16 (1) The intrinsic procedures are to be listed in alphabetical order. 17 (2) The generic name is to be used. 18 (3) The specific names are included in the function index and in a 19 table at the end of the node (See ABS entry). 20 (4) Try to maintain the same style for each entry. 21 22 23@end ignore 24 25@tex 26\gdef\acosd{\mathop{\rm acosd}\nolimits} 27\gdef\asind{\mathop{\rm asind}\nolimits} 28\gdef\atand{\mathop{\rm atand}\nolimits} 29\gdef\acos{\mathop{\rm acos}\nolimits} 30\gdef\asin{\mathop{\rm asin}\nolimits} 31\gdef\atan{\mathop{\rm atan}\nolimits} 32\gdef\acosh{\mathop{\rm acosh}\nolimits} 33\gdef\asinh{\mathop{\rm asinh}\nolimits} 34\gdef\atanh{\mathop{\rm atanh}\nolimits} 35\gdef\cosd{\mathop{\rm cosd}\nolimits} 36@end tex 37 38 39@node Intrinsic Procedures 40@chapter Intrinsic Procedures 41@cindex intrinsic procedures 42 43@menu 44* Introduction: Introduction to Intrinsics 45* @code{ABORT}: ABORT, Abort the program 46* @code{ABS}: ABS, Absolute value 47* @code{ACCESS}: ACCESS, Checks file access modes 48* @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence 49* @code{ACOS}: ACOS, Arccosine function 50* @code{ACOSD}: ACOSD, Arccosine function, degrees 51* @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function 52* @code{ADJUSTL}: ADJUSTL, Left adjust a string 53* @code{ADJUSTR}: ADJUSTR, Right adjust a string 54* @code{AIMAG}: AIMAG, Imaginary part of complex number 55* @code{AINT}: AINT, Truncate to a whole number 56* @code{ALARM}: ALARM, Set an alarm clock 57* @code{ALL}: ALL, Determine if all values are true 58* @code{ALLOCATED}: ALLOCATED, Status of allocatable entity 59* @code{AND}: AND, Bitwise logical AND 60* @code{ANINT}: ANINT, Nearest whole number 61* @code{ANY}: ANY, Determine if any values are true 62* @code{ASIN}: ASIN, Arcsine function 63* @code{ASIND}: ASIND, Arcsine function, degrees 64* @code{ASINH}: ASINH, Inverse hyperbolic sine function 65* @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair 66* @code{ATAN}: ATAN, Arctangent function 67* @code{ATAND}: ATAND, Arctangent function, degrees 68* @code{ATAN2}: ATAN2, Arctangent function 69* @code{ATAN2D}: ATAN2D, Arctangent function, degrees 70* @code{ATANH}: ATANH, Inverse hyperbolic tangent function 71* @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation 72* @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation 73* @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap 74* @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically 75* @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch 76* @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch 77* @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch 78* @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch 79* @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation 80* @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically 81* @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation 82* @code{BACKTRACE}: BACKTRACE, Show a backtrace 83* @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0 84* @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1 85* @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind 86* @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0 87* @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1 88* @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind 89* @code{BGE}: BGE, Bitwise greater than or equal to 90* @code{BGT}: BGT, Bitwise greater than 91* @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function 92* @code{BLE}: BLE, Bitwise less than or equal to 93* @code{BLT}: BLT, Bitwise less than 94* @code{BTEST}: BTEST, Bit test function 95* @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer 96* @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer 97* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer 98* @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure 99* @code{C_LOC}: C_LOC, Obtain the C address of an object 100* @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression 101* @code{CEILING}: CEILING, Integer ceiling function 102* @code{CHAR}: CHAR, Integer-to-character conversion function 103* @code{CHDIR}: CHDIR, Change working directory 104* @code{CHMOD}: CHMOD, Change access permissions of files 105* @code{CMPLX}: CMPLX, Complex conversion function 106* @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images 107* @code{CO_MAX}: CO_MAX, Maximal value on the current set of images 108* @code{CO_MIN}: CO_MIN, Minimal value on the current set of images 109* @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images 110* @code{CO_SUM}: CO_SUM, Sum of values on the current set of images 111* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments 112* @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler 113* @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string 114* @code{COMPLEX}: COMPLEX, Complex conversion function 115* @code{CONJG}: CONJG, Complex conjugate function 116* @code{COS}: COS, Cosine function 117* @code{COSD}: COSD, Cosine function, degrees 118* @code{COSH}: COSH, Hyperbolic cosine function 119* @code{COTAN}: COTAN, Cotangent function 120* @code{COTAND}: COTAND, Cotangent function, degrees 121* @code{COUNT}: COUNT, Count occurrences of TRUE in an array 122* @code{CPU_TIME}: CPU_TIME, CPU time subroutine 123* @code{CSHIFT}: CSHIFT, Circular shift elements of an array 124* @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string 125* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine 126* @code{DBLE}: DBLE, Double precision conversion function 127* @code{DCMPLX}: DCMPLX, Double complex conversion function 128* @code{DIGITS}: DIGITS, Significant digits function 129* @code{DIM}: DIM, Positive difference 130* @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function 131* @code{DPROD}: DPROD, Double product function 132* @code{DREAL}: DREAL, Double real part function 133* @code{DSHIFTL}: DSHIFTL, Combined left shift 134* @code{DSHIFTR}: DSHIFTR, Combined right shift 135* @code{DTIME}: DTIME, Execution time subroutine (or function) 136* @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array 137* @code{EPSILON}: EPSILON, Epsilon function 138* @code{ERF}: ERF, Error function 139* @code{ERFC}: ERFC, Complementary error function 140* @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function 141* @code{ETIME}: ETIME, Execution time subroutine (or function) 142* @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred 143* @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command 144* @code{EXIT}: EXIT, Exit the program with status. 145* @code{EXP}: EXP, Exponential function 146* @code{EXPONENT}: EXPONENT, Exponent function 147* @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension 148* @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string 149* @code{FGET}: FGET, Read a single character in stream mode from stdin 150* @code{FGETC}: FGETC, Read a single character in stream mode 151* @code{FINDLOC}: FINDLOC, Search an array for a value 152* @code{FLOOR}: FLOOR, Integer floor function 153* @code{FLUSH}: FLUSH, Flush I/O unit(s) 154* @code{FNUM}: FNUM, File number function 155* @code{FPUT}: FPUT, Write a single character in stream mode to stdout 156* @code{FPUTC}: FPUTC, Write a single character in stream mode 157* @code{FRACTION}: FRACTION, Fractional part of the model representation 158* @code{FREE}: FREE, Memory de-allocation subroutine 159* @code{FSEEK}: FSEEK, Low level file positioning subroutine 160* @code{FSTAT}: FSTAT, Get file status 161* @code{FTELL}: FTELL, Current stream position 162* @code{GAMMA}: GAMMA, Gamma function 163* @code{GERROR}: GERROR, Get last system error message 164* @code{GETARG}: GETARG, Get command line arguments 165* @code{GET_COMMAND}: GET_COMMAND, Get the entire command line 166* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments 167* @code{GETCWD}: GETCWD, Get current working directory 168* @code{GETENV}: GETENV, Get an environmental variable 169* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable 170* @code{GETGID}: GETGID, Group ID function 171* @code{GETLOG}: GETLOG, Get login name 172* @code{GETPID}: GETPID, Process ID function 173* @code{GETUID}: GETUID, User ID function 174* @code{GMTIME}: GMTIME, Convert time to GMT info 175* @code{HOSTNM}: HOSTNM, Get system host name 176* @code{HUGE}: HUGE, Largest number of a kind 177* @code{HYPOT}: HYPOT, Euclidean distance function 178* @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence 179* @code{IALL}: IALL, Bitwise AND of array elements 180* @code{IAND}: IAND, Bitwise logical and 181* @code{IANY}: IANY, Bitwise OR of array elements 182* @code{IARGC}: IARGC, Get the number of command line arguments 183* @code{IBCLR}: IBCLR, Clear bit 184* @code{IBITS}: IBITS, Bit extraction 185* @code{IBSET}: IBSET, Set bit 186* @code{ICHAR}: ICHAR, Character-to-integer conversion function 187* @code{IDATE}: IDATE, Current local time (day/month/year) 188* @code{IEOR}: IEOR, Bitwise logical exclusive or 189* @code{IERRNO}: IERRNO, Function to get the last system error number 190* @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion 191* @code{INDEX}: INDEX intrinsic, Position of a substring within a string 192* @code{INT}: INT, Convert to integer type 193* @code{INT2}: INT2, Convert to 16-bit integer type 194* @code{INT8}: INT8, Convert to 64-bit integer type 195* @code{IOR}: IOR, Bitwise logical or 196* @code{IPARITY}: IPARITY, Bitwise XOR of array elements 197* @code{IRAND}: IRAND, Integer pseudo-random number 198* @code{IS_CONTIGUOUS}: IS_CONTIGUOUS, Test whether an array is contiguous 199* @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value 200* @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value 201* @code{ISATTY}: ISATTY, Whether a unit is a terminal device 202* @code{ISHFT}: ISHFT, Shift bits 203* @code{ISHFTC}: ISHFTC, Shift bits circularly 204* @code{ISNAN}: ISNAN, Tests for a NaN 205* @code{ITIME}: ITIME, Current local time (hour/minutes/seconds) 206* @code{KILL}: KILL, Send a signal to a process 207* @code{KIND}: KIND, Kind of an entity 208* @code{LBOUND}: LBOUND, Lower dimension bounds of an array 209* @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array 210* @code{LEADZ}: LEADZ, Number of leading zero bits of an integer 211* @code{LEN}: LEN, Length of a character entity 212* @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters 213* @code{LGE}: LGE, Lexical greater than or equal 214* @code{LGT}: LGT, Lexical greater than 215* @code{LINK}: LINK, Create a hard link 216* @code{LLE}: LLE, Lexical less than or equal 217* @code{LLT}: LLT, Lexical less than 218* @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string 219* @code{LOC}: LOC, Returns the address of a variable 220* @code{LOG}: LOG, Logarithm function 221* @code{LOG10}: LOG10, Base 10 logarithm function 222* @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function 223* @code{LOGICAL}: LOGICAL, Convert to logical type 224* @code{LONG}: LONG, Convert to integer type 225* @code{LSHIFT}: LSHIFT, Left shift bits 226* @code{LSTAT}: LSTAT, Get file status 227* @code{LTIME}: LTIME, Convert time to local time info 228* @code{MALLOC}: MALLOC, Dynamic memory allocation function 229* @code{MASKL}: MASKL, Left justified mask 230* @code{MASKR}: MASKR, Right justified mask 231* @code{MATMUL}: MATMUL, matrix multiplication 232* @code{MAX}: MAX, Maximum value of an argument list 233* @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind 234* @code{MAXLOC}: MAXLOC, Location of the maximum value within an array 235* @code{MAXVAL}: MAXVAL, Maximum value of an array 236* @code{MCLOCK}: MCLOCK, Time function 237* @code{MCLOCK8}: MCLOCK8, Time function (64-bit) 238* @code{MERGE}: MERGE, Merge arrays 239* @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask 240* @code{MIN}: MIN, Minimum value of an argument list 241* @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind 242* @code{MINLOC}: MINLOC, Location of the minimum value within an array 243* @code{MINVAL}: MINVAL, Minimum value of an array 244* @code{MOD}: MOD, Remainder function 245* @code{MODULO}: MODULO, Modulo function 246* @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another 247* @code{MVBITS}: MVBITS, Move bits from one integer to another 248* @code{NEAREST}: NEAREST, Nearest representable number 249* @code{NEW_LINE}: NEW_LINE, New line character 250* @code{NINT}: NINT, Nearest whole number 251* @code{NORM2}: NORM2, Euclidean vector norm 252* @code{NOT}: NOT, Logical negation 253* @code{NULL}: NULL, Function that returns an disassociated pointer 254* @code{NUM_IMAGES}: NUM_IMAGES, Number of images 255* @code{OR}: OR, Bitwise logical OR 256* @code{PACK}: PACK, Pack an array into an array of rank one 257* @code{PARITY}: PARITY, Reduction with exclusive OR 258* @code{PERROR}: PERROR, Print system error message 259* @code{POPCNT}: POPCNT, Number of bits set 260* @code{POPPAR}: POPPAR, Parity of the number of bits set 261* @code{PRECISION}: PRECISION, Decimal precision of a real kind 262* @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified 263* @code{PRODUCT}: PRODUCT, Product of array elements 264* @code{RADIX}: RADIX, Base of a data model 265* @code{RAN}: RAN, Real pseudo-random number 266* @code{RAND}: RAND, Real pseudo-random number 267* @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator 268* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number 269* @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence 270* @code{RANGE}: RANGE, Decimal exponent range 271* @code{RANK} : RANK, Rank of a data object 272* @code{REAL}: REAL, Convert to real type 273* @code{RENAME}: RENAME, Rename a file 274* @code{REPEAT}: REPEAT, Repeated string concatenation 275* @code{RESHAPE}: RESHAPE, Function to reshape an array 276* @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing 277* @code{RSHIFT}: RSHIFT, Right shift bits 278* @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality 279* @code{SCALE}: SCALE, Scale a real value 280* @code{SCAN}: SCAN, Scan a string for the presence of a set of characters 281* @code{SECNDS}: SECNDS, Time function 282* @code{SECOND}: SECOND, CPU time function 283* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind 284* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind 285* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind 286* @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model 287* @code{SHAPE}: SHAPE, Determine the shape of an array 288* @code{SHIFTA}: SHIFTA, Right shift with fill 289* @code{SHIFTL}: SHIFTL, Left shift 290* @code{SHIFTR}: SHIFTR, Right shift 291* @code{SIGN}: SIGN, Sign copying function 292* @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function) 293* @code{SIN}: SIN, Sine function 294* @code{SIND}: SIND, Sine function, degrees 295* @code{SINH}: SINH, Hyperbolic sine function 296* @code{SIZE}: SIZE, Function to determine the size of an array 297* @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression 298* @code{SLEEP}: SLEEP, Sleep for the specified number of seconds 299* @code{SPACING}: SPACING, Smallest distance between two numbers of a given type 300* @code{SPREAD}: SPREAD, Add a dimension to an array 301* @code{SQRT}: SQRT, Square-root function 302* @code{SRAND}: SRAND, Reinitialize the random number generator 303* @code{STAT}: STAT, Get file status 304* @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits 305* @code{SUM}: SUM, Sum of array elements 306* @code{SYMLNK}: SYMLNK, Create a symbolic link 307* @code{SYSTEM}: SYSTEM, Execute a shell command 308* @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function 309* @code{TAN}: TAN, Tangent function 310* @code{TAND}: TAND, Tangent function, degrees 311* @code{TANH}: TANH, Hyperbolic tangent function 312* @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image 313* @code{TIME}: TIME, Time function 314* @code{TIME8}: TIME8, Time function (64-bit) 315* @code{TINY}: TINY, Smallest positive number of a real kind 316* @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer 317* @code{TRANSFER}: TRANSFER, Transfer bit patterns 318* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two 319* @code{TRIM}: TRIM, Remove trailing blank characters of a string 320* @code{TTYNAM}: TTYNAM, Get the name of a terminal device. 321* @code{UBOUND}: UBOUND, Upper dimension bounds of an array 322* @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array 323* @code{UMASK}: UMASK, Set the file creation mask 324* @code{UNLINK}: UNLINK, Remove a file from the file system 325* @code{UNPACK}: UNPACK, Unpack an array of rank one into an array 326* @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters 327* @code{XOR}: XOR, Bitwise logical exclusive or 328@end menu 329 330@node Introduction to Intrinsics 331@section Introduction to intrinsic procedures 332 333The intrinsic procedures provided by GNU Fortran include all of the 334intrinsic procedures required by the Fortran 95 standard, a set of 335intrinsic procedures for backwards compatibility with G77, and a 336selection of intrinsic procedures from the Fortran 2003 and Fortran 2008 337standards. Any conflict between a description here and a description in 338either the Fortran 95 standard, the Fortran 2003 standard or the Fortran 3392008 standard is unintentional, and the standard(s) should be considered 340authoritative. 341 342The enumeration of the @code{KIND} type parameter is processor defined in 343the Fortran 95 standard. GNU Fortran defines the default integer type and 344default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)}, 345respectively. The standard mandates that both data types shall have 346another kind, which have more precision. On typical target architectures 347supported by @command{gfortran}, this kind type parameter is @code{KIND=8}. 348Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent. 349In the description of generic intrinsic procedures, the kind type parameter 350will be specified by @code{KIND=*}, and in the description of specific 351names for an intrinsic procedure the kind type parameter will be explicitly 352given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for 353brevity the optional @code{KIND=} syntax will be omitted. 354 355Many of the intrinsic procedures take one or more optional arguments. 356This document follows the convention used in the Fortran 95 standard, 357and denotes such arguments by square brackets. 358 359GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options, 360which can be used to restrict the set of intrinsic procedures to a 361given standard. By default, @command{gfortran} sets the @option{-std=gnu} 362option, and so all intrinsic procedures described here are accepted. There 363is one caveat. For a select group of intrinsic procedures, @command{g77} 364implemented both a function and a subroutine. Both classes 365have been implemented in @command{gfortran} for backwards compatibility 366with @command{g77}. It is noted here that these functions and subroutines 367cannot be intermixed in a given subprogram. In the descriptions that follow, 368the applicable standard for each intrinsic procedure is noted. 369 370 371 372@node ABORT 373@section @code{ABORT} --- Abort the program 374@fnindex ABORT 375@cindex program termination, with core dump 376@cindex terminate program, with core dump 377@cindex core, dump 378 379@table @asis 380@item @emph{Description}: 381@code{ABORT} causes immediate termination of the program. On operating 382systems that support a core dump, @code{ABORT} will produce a core dump. 383It will also print a backtrace, unless @code{-fno-backtrace} is given. 384 385@item @emph{Standard}: 386GNU extension 387 388@item @emph{Class}: 389Subroutine 390 391@item @emph{Syntax}: 392@code{CALL ABORT} 393 394@item @emph{Return value}: 395Does not return. 396 397@item @emph{Example}: 398@smallexample 399program test_abort 400 integer :: i = 1, j = 2 401 if (i /= j) call abort 402end program test_abort 403@end smallexample 404 405@item @emph{See also}: 406@ref{EXIT}, @gol 407@ref{KILL}, @gol 408@ref{BACKTRACE} 409@end table 410 411 412 413@node ABS 414@section @code{ABS} --- Absolute value 415@fnindex ABS 416@fnindex CABS 417@fnindex DABS 418@fnindex IABS 419@fnindex ZABS 420@fnindex CDABS 421@fnindex BABS 422@fnindex IIABS 423@fnindex JIABS 424@fnindex KIABS 425@cindex absolute value 426 427@table @asis 428@item @emph{Description}: 429@code{ABS(A)} computes the absolute value of @code{A}. 430 431@item @emph{Standard}: 432Fortran 77 and later, has overloads that are GNU extensions 433 434@item @emph{Class}: 435Elemental function 436 437@item @emph{Syntax}: 438@code{RESULT = ABS(A)} 439 440@item @emph{Arguments}: 441@multitable @columnfractions .15 .70 442@item @var{A} @tab The type of the argument shall be an @code{INTEGER}, 443@code{REAL}, or @code{COMPLEX}. 444@end multitable 445 446@item @emph{Return value}: 447The return value is of the same type and 448kind as the argument except the return value is @code{REAL} for a 449@code{COMPLEX} argument. 450 451@item @emph{Example}: 452@smallexample 453program test_abs 454 integer :: i = -1 455 real :: x = -1.e0 456 complex :: z = (-1.e0,0.e0) 457 i = abs(i) 458 x = abs(x) 459 x = abs(z) 460end program test_abs 461@end smallexample 462 463@item @emph{Specific names}: 464@multitable @columnfractions .20 .20 .20 .25 465@item Name @tab Argument @tab Return type @tab Standard 466@item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 467@item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 468@item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 469@item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later 470@item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 471@item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 472@item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 473@item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 474@item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension 475@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension 476@end multitable 477@end table 478 479 480 481@node ACCESS 482@section @code{ACCESS} --- Checks file access modes 483@fnindex ACCESS 484@cindex file system, access mode 485 486@table @asis 487@item @emph{Description}: 488@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 489exists, is readable, writable or executable. Except for the 490executable check, @code{ACCESS} can be replaced by 491Fortran 95's @code{INQUIRE}. 492 493@item @emph{Standard}: 494GNU extension 495 496@item @emph{Class}: 497Inquiry function 498 499@item @emph{Syntax}: 500@code{RESULT = ACCESS(NAME, MODE)} 501 502@item @emph{Arguments}: 503@multitable @columnfractions .15 .70 504@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 505file name. Tailing blank are ignored unless the character @code{achar(0)} 506is present, then all characters up to and excluding @code{achar(0)} are 507used as file name. 508@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the 509file access mode, may be any concatenation of @code{"r"} (readable), 510@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check 511for existence. 512@end multitable 513 514@item @emph{Return value}: 515Returns a scalar @code{INTEGER}, which is @code{0} if the file is 516accessible in the given mode; otherwise or if an invalid argument 517has been given for @code{MODE} the value @code{1} is returned. 518 519@item @emph{Example}: 520@smallexample 521program access_test 522 implicit none 523 character(len=*), parameter :: file = 'test.dat' 524 character(len=*), parameter :: file2 = 'test.dat '//achar(0) 525 if(access(file,' ') == 0) print *, trim(file),' is exists' 526 if(access(file,'r') == 0) print *, trim(file),' is readable' 527 if(access(file,'w') == 0) print *, trim(file),' is writable' 528 if(access(file,'x') == 0) print *, trim(file),' is executable' 529 if(access(file2,'rwx') == 0) & 530 print *, trim(file2),' is readable, writable and executable' 531end program access_test 532@end smallexample 533@end table 534 535 536 537@node ACHAR 538@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 539@fnindex ACHAR 540@cindex @acronym{ASCII} collating sequence 541@cindex collating sequence, @acronym{ASCII} 542 543@table @asis 544@item @emph{Description}: 545@code{ACHAR(I)} returns the character located at position @code{I} 546in the @acronym{ASCII} collating sequence. 547 548@item @emph{Standard}: 549Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 550 551@item @emph{Class}: 552Elemental function 553 554@item @emph{Syntax}: 555@code{RESULT = ACHAR(I [, KIND])} 556 557@item @emph{Arguments}: 558@multitable @columnfractions .15 .70 559@item @var{I} @tab The type shall be @code{INTEGER}. 560@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 561expression indicating the kind parameter of the result. 562@end multitable 563 564@item @emph{Return value}: 565The return value is of type @code{CHARACTER} with a length of one. 566If the @var{KIND} argument is present, the return value is of the 567specified kind and of the default kind otherwise. 568 569@item @emph{Example}: 570@smallexample 571program test_achar 572 character c 573 c = achar(32) 574end program test_achar 575@end smallexample 576 577@item @emph{Note}: 578See @ref{ICHAR} for a discussion of converting between numerical values 579and formatted string representations. 580 581@item @emph{See also}: 582@ref{CHAR}, @gol 583@ref{IACHAR}, @gol 584@ref{ICHAR} 585@end table 586 587 588 589@node ACOS 590@section @code{ACOS} --- Arccosine function 591@fnindex ACOS 592@fnindex DACOS 593@cindex trigonometric function, cosine, inverse 594@cindex cosine, inverse 595 596@table @asis 597@item @emph{Description}: 598@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}). 599 600@item @emph{Standard}: 601Fortran 77 and later, for a complex argument Fortran 2008 or later 602 603@item @emph{Class}: 604Elemental function 605 606@item @emph{Syntax}: 607@code{RESULT = ACOS(X)} 608 609@item @emph{Arguments}: 610@multitable @columnfractions .15 .70 611@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 612less than or equal to one - or the type shall be @code{COMPLEX}. 613@end multitable 614 615@item @emph{Return value}: 616The return value is of the same type and kind as @var{X}. 617The real part of the result is in radians and lies in the range 618@math{0 \leq \Re \acos(x) \leq \pi}. 619 620@item @emph{Example}: 621@smallexample 622program test_acos 623 real(8) :: x = 0.866_8 624 x = acos(x) 625end program test_acos 626@end smallexample 627 628@item @emph{Specific names}: 629@multitable @columnfractions .20 .20 .20 .25 630@item Name @tab Argument @tab Return type @tab Standard 631@item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 632@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 633@end multitable 634 635@item @emph{See also}: 636Inverse function: @gol 637@ref{COS} @gol 638Degrees function: @gol 639@ref{ACOSD} 640@end table 641 642 643 644@node ACOSD 645@section @code{ACOSD} --- Arccosine function, degrees 646@fnindex ACOSD 647@fnindex DACOSD 648@cindex trigonometric function, cosine, inverse, degrees 649@cindex cosine, inverse, degrees 650 651@table @asis 652@item @emph{Description}: 653@code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of 654@code{COSD(X)}). 655 656This function is for compatibility only and should be avoided in favor of 657standard constructs wherever possible. 658 659@item @emph{Standard}: 660GNU extension, enabled with @option{-fdec-math} 661 662@item @emph{Class}: 663Elemental function 664 665@item @emph{Syntax}: 666@code{RESULT = ACOSD(X)} 667 668@item @emph{Arguments}: 669@multitable @columnfractions .15 .70 670@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 671less than or equal to one - or the type shall be @code{COMPLEX}. 672@end multitable 673 674@item @emph{Return value}: 675The return value is of the same type and kind as @var{X}. 676The real part of the result is in degrees and lies in the range 677@math{0 \leq \Re \acos(x) \leq 180}. 678 679@item @emph{Example}: 680@smallexample 681program test_acosd 682 real(8) :: x = 0.866_8 683 x = acosd(x) 684end program test_acosd 685@end smallexample 686 687@item @emph{Specific names}: 688@multitable @columnfractions .20 .20 .20 .25 689@item Name @tab Argument @tab Return type @tab Standard 690@item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 691@item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 692@end multitable 693 694@item @emph{See also}: 695Inverse function: @gol 696@ref{COSD} @gol 697Radians function: @gol 698@ref{ACOS} @gol 699@end table 700 701 702 703@node ACOSH 704@section @code{ACOSH} --- Inverse hyperbolic cosine function 705@fnindex ACOSH 706@fnindex DACOSH 707@cindex area hyperbolic cosine 708@cindex inverse hyperbolic cosine 709@cindex hyperbolic function, cosine, inverse 710@cindex cosine, hyperbolic, inverse 711 712@table @asis 713@item @emph{Description}: 714@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}. 715 716@item @emph{Standard}: 717Fortran 2008 and later 718 719@item @emph{Class}: 720Elemental function 721 722@item @emph{Syntax}: 723@code{RESULT = ACOSH(X)} 724 725@item @emph{Arguments}: 726@multitable @columnfractions .15 .70 727@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 728@end multitable 729 730@item @emph{Return value}: 731The return value has the same type and kind as @var{X}. If @var{X} is 732complex, the imaginary part of the result is in radians and lies between 733@math{ 0 \leq \Im \acosh(x) \leq \pi}. 734 735@item @emph{Example}: 736@smallexample 737PROGRAM test_acosh 738 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) 739 WRITE (*,*) ACOSH(x) 740END PROGRAM 741@end smallexample 742 743@item @emph{Specific names}: 744@multitable @columnfractions .20 .20 .20 .25 745@item Name @tab Argument @tab Return type @tab Standard 746@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 747@end multitable 748 749@item @emph{See also}: 750Inverse function: @gol 751@ref{COSH} 752@end table 753 754 755 756@node ADJUSTL 757@section @code{ADJUSTL} --- Left adjust a string 758@fnindex ADJUSTL 759@cindex string, adjust left 760@cindex adjust string 761 762@table @asis 763@item @emph{Description}: 764@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces. 765Spaces are inserted at the end of the string as needed. 766 767@item @emph{Standard}: 768Fortran 90 and later 769 770@item @emph{Class}: 771Elemental function 772 773@item @emph{Syntax}: 774@code{RESULT = ADJUSTL(STRING)} 775 776@item @emph{Arguments}: 777@multitable @columnfractions .15 .70 778@item @var{STRING} @tab The type shall be @code{CHARACTER}. 779@end multitable 780 781@item @emph{Return value}: 782The return value is of type @code{CHARACTER} and of the same kind as 783@var{STRING} where leading spaces are removed and the same number of 784spaces are inserted on the end of @var{STRING}. 785 786@item @emph{Example}: 787@smallexample 788program test_adjustl 789 character(len=20) :: str = ' gfortran' 790 str = adjustl(str) 791 print *, str 792end program test_adjustl 793@end smallexample 794 795@item @emph{See also}: 796@ref{ADJUSTR}, @gol 797@ref{TRIM} 798@end table 799 800 801 802@node ADJUSTR 803@section @code{ADJUSTR} --- Right adjust a string 804@fnindex ADJUSTR 805@cindex string, adjust right 806@cindex adjust string 807 808@table @asis 809@item @emph{Description}: 810@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces. 811Spaces are inserted at the start of the string as needed. 812 813@item @emph{Standard}: 814Fortran 90 and later 815 816@item @emph{Class}: 817Elemental function 818 819@item @emph{Syntax}: 820@code{RESULT = ADJUSTR(STRING)} 821 822@item @emph{Arguments}: 823@multitable @columnfractions .15 .70 824@item @var{STR} @tab The type shall be @code{CHARACTER}. 825@end multitable 826 827@item @emph{Return value}: 828The return value is of type @code{CHARACTER} and of the same kind as 829@var{STRING} where trailing spaces are removed and the same number of 830spaces are inserted at the start of @var{STRING}. 831 832@item @emph{Example}: 833@smallexample 834program test_adjustr 835 character(len=20) :: str = 'gfortran' 836 str = adjustr(str) 837 print *, str 838end program test_adjustr 839@end smallexample 840 841@item @emph{See also}: 842@ref{ADJUSTL}, @gol 843@ref{TRIM} 844@end table 845 846 847 848@node AIMAG 849@section @code{AIMAG} --- Imaginary part of complex number 850@fnindex AIMAG 851@fnindex DIMAG 852@fnindex IMAG 853@fnindex IMAGPART 854@cindex complex numbers, imaginary part 855 856@table @asis 857@item @emph{Description}: 858@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}. 859The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided 860for compatibility with @command{g77}, and their use in new code is 861strongly discouraged. 862 863@item @emph{Standard}: 864Fortran 77 and later, has overloads that are GNU extensions 865 866@item @emph{Class}: 867Elemental function 868 869@item @emph{Syntax}: 870@code{RESULT = AIMAG(Z)} 871 872@item @emph{Arguments}: 873@multitable @columnfractions .15 .70 874@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}. 875@end multitable 876 877@item @emph{Return value}: 878The return value is of type @code{REAL} with the 879kind type parameter of the argument. 880 881@item @emph{Example}: 882@smallexample 883program test_aimag 884 complex(4) z4 885 complex(8) z8 886 z4 = cmplx(1.e0_4, 0.e0_4) 887 z8 = cmplx(0.e0_8, 1.e0_8) 888 print *, aimag(z4), dimag(z8) 889end program test_aimag 890@end smallexample 891 892@item @emph{Specific names}: 893@multitable @columnfractions .20 .20 .20 .25 894@item Name @tab Argument @tab Return type @tab Standard 895@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later 896@item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension 897@item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 898@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 899@end multitable 900@end table 901 902 903 904@node AINT 905@section @code{AINT} --- Truncate to a whole number 906@fnindex AINT 907@fnindex DINT 908@cindex floor 909@cindex rounding, floor 910 911@table @asis 912@item @emph{Description}: 913@code{AINT(A [, KIND])} truncates its argument to a whole number. 914 915@item @emph{Standard}: 916Fortran 77 and later 917 918@item @emph{Class}: 919Elemental function 920 921@item @emph{Syntax}: 922@code{RESULT = AINT(A [, KIND])} 923 924@item @emph{Arguments}: 925@multitable @columnfractions .15 .70 926@item @var{A} @tab The type of the argument shall be @code{REAL}. 927@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 928expression indicating the kind parameter of the result. 929@end multitable 930 931@item @emph{Return value}: 932The return value is of type @code{REAL} with the kind type parameter of the 933argument if the optional @var{KIND} is absent; otherwise, the kind 934type parameter will be given by @var{KIND}. If the magnitude of 935@var{X} is less than one, @code{AINT(X)} returns zero. If the 936magnitude is equal to or greater than one then it returns the largest 937whole number that does not exceed its magnitude. The sign is the same 938as the sign of @var{X}. 939 940@item @emph{Example}: 941@smallexample 942program test_aint 943 real(4) x4 944 real(8) x8 945 x4 = 1.234E0_4 946 x8 = 4.321_8 947 print *, aint(x4), dint(x8) 948 x8 = aint(x4,8) 949end program test_aint 950@end smallexample 951 952@item @emph{Specific names}: 953@multitable @columnfractions .20 .20 .20 .25 954@item Name @tab Argument @tab Return type @tab Standard 955@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 956@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 957@end multitable 958@end table 959 960 961 962@node ALARM 963@section @code{ALARM} --- Execute a routine after a given delay 964@fnindex ALARM 965@cindex delayed execution 966 967@table @asis 968@item @emph{Description}: 969@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} 970to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to 971set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is 972supplied, it will be returned with the number of seconds remaining until 973any previously scheduled alarm was due to be delivered, or zero if there 974was no previously scheduled alarm. 975 976@item @emph{Standard}: 977GNU extension 978 979@item @emph{Class}: 980Subroutine 981 982@item @emph{Syntax}: 983@code{CALL ALARM(SECONDS, HANDLER [, STATUS])} 984 985@item @emph{Arguments}: 986@multitable @columnfractions .15 .70 987@item @var{SECONDS} @tab The type of the argument shall be a scalar 988@code{INTEGER}. It is @code{INTENT(IN)}. 989@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or 990@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 991values may be either @code{SIG_IGN=1} to ignore the alarm generated 992or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}. 993@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 994variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}. 995@end multitable 996 997@item @emph{Example}: 998@smallexample 999program test_alarm 1000 external handler_print 1001 integer i 1002 call alarm (3, handler_print, i) 1003 print *, i 1004 call sleep(10) 1005end program test_alarm 1006@end smallexample 1007This will cause the external routine @var{handler_print} to be called 1008after 3 seconds. 1009@end table 1010 1011 1012 1013@node ALL 1014@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 1015@fnindex ALL 1016@cindex array, apply condition 1017@cindex array, condition testing 1018 1019@table @asis 1020@item @emph{Description}: 1021@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK} 1022in the array along dimension @var{DIM}. 1023 1024@item @emph{Standard}: 1025Fortran 90 and later 1026 1027@item @emph{Class}: 1028Transformational function 1029 1030@item @emph{Syntax}: 1031@code{RESULT = ALL(MASK [, DIM])} 1032 1033@item @emph{Arguments}: 1034@multitable @columnfractions .15 .70 1035@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1036it shall not be scalar. 1037@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1038with a value that lies between one and the rank of @var{MASK}. 1039@end multitable 1040 1041@item @emph{Return value}: 1042@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where 1043the kind type parameter is the same as the kind type parameter of 1044@var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns 1045an array with the rank of @var{MASK} minus 1. The shape is determined from 1046the shape of @var{MASK} where the @var{DIM} dimension is elided. 1047 1048@table @asis 1049@item (A) 1050@code{ALL(MASK)} is true if all elements of @var{MASK} are true. 1051It also is true if @var{MASK} has zero size; otherwise, it is false. 1052@item (B) 1053If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent 1054to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)} 1055is determined by applying @code{ALL} to the array sections. 1056@end table 1057 1058@item @emph{Example}: 1059@smallexample 1060program test_all 1061 logical l 1062 l = all((/.true., .true., .true./)) 1063 print *, l 1064 call section 1065 contains 1066 subroutine section 1067 integer a(2,3), b(2,3) 1068 a = 1 1069 b = 1 1070 b(2,2) = 2 1071 print *, all(a .eq. b, 1) 1072 print *, all(a .eq. b, 2) 1073 end subroutine section 1074end program test_all 1075@end smallexample 1076@end table 1077 1078 1079 1080@node ALLOCATED 1081@section @code{ALLOCATED} --- Status of an allocatable entity 1082@fnindex ALLOCATED 1083@cindex allocation, status 1084 1085@table @asis 1086@item @emph{Description}: 1087@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation 1088status of @var{ARRAY} and @var{SCALAR}, respectively. 1089 1090@item @emph{Standard}: 1091Fortran 90 and later. Note, the @code{SCALAR=} keyword and allocatable 1092scalar entities are available in Fortran 2003 and later. 1093 1094@item @emph{Class}: 1095Inquiry function 1096 1097@item @emph{Syntax}: 1098@multitable @columnfractions .80 1099@item @code{RESULT = ALLOCATED(ARRAY)} 1100@item @code{RESULT = ALLOCATED(SCALAR)} 1101@end multitable 1102 1103@item @emph{Arguments}: 1104@multitable @columnfractions .15 .70 1105@item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array. 1106@item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar. 1107@end multitable 1108 1109@item @emph{Return value}: 1110The return value is a scalar @code{LOGICAL} with the default logical 1111kind type parameter. If the argument is allocated, then the result is 1112@code{.TRUE.}; otherwise, it returns @code{.FALSE.} 1113 1114@item @emph{Example}: 1115@smallexample 1116program test_allocated 1117 integer :: i = 4 1118 real(4), allocatable :: x(:) 1119 if (.not. allocated(x)) allocate(x(i)) 1120end program test_allocated 1121@end smallexample 1122@end table 1123 1124 1125 1126@node AND 1127@section @code{AND} --- Bitwise logical AND 1128@fnindex AND 1129@cindex bitwise logical and 1130@cindex logical and, bitwise 1131 1132@table @asis 1133@item @emph{Description}: 1134Bitwise logical @code{AND}. 1135 1136This intrinsic routine is provided for backwards compatibility with 1137GNU Fortran 77. For integer arguments, programmers should consider 1138the use of the @ref{IAND} intrinsic defined by the Fortran standard. 1139 1140@item @emph{Standard}: 1141GNU extension 1142 1143@item @emph{Class}: 1144Function 1145 1146@item @emph{Syntax}: 1147@code{RESULT = AND(I, J)} 1148 1149@item @emph{Arguments}: 1150@multitable @columnfractions .15 .70 1151@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 1152type or a scalar @code{LOGICAL} type or a boz-literal-constant. 1153@item @var{J} @tab The type shall be the same as the type of @var{I} or 1154a boz-literal-constant. @var{I} and @var{J} shall not both be 1155boz-literal-constants. If either @var{I} or @var{J} is a 1156boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 1157@end multitable 1158 1159@item @emph{Return value}: 1160The return type is either a scalar @code{INTEGER} or a scalar 1161@code{LOGICAL}. If the kind type parameters differ, then the 1162smaller kind type is implicitly converted to larger kind, and the 1163return has the larger kind. A boz-literal-constant is 1164converted to an @code{INTEGER} with the kind type parameter of 1165the other argument as-if a call to @ref{INT} occurred. 1166 1167@item @emph{Example}: 1168@smallexample 1169PROGRAM test_and 1170 LOGICAL :: T = .TRUE., F = .FALSE. 1171 INTEGER :: a, b 1172 DATA a / Z'F' /, b / Z'3' / 1173 1174 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F) 1175 WRITE (*,*) AND(a, b) 1176END PROGRAM 1177@end smallexample 1178 1179@item @emph{See also}: 1180Fortran 95 elemental function: @gol 1181@ref{IAND} 1182@end table 1183 1184 1185 1186@node ANINT 1187@section @code{ANINT} --- Nearest whole number 1188@fnindex ANINT 1189@fnindex DNINT 1190@cindex ceiling 1191@cindex rounding, ceiling 1192 1193@table @asis 1194@item @emph{Description}: 1195@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number. 1196 1197@item @emph{Standard}: 1198Fortran 77 and later 1199 1200@item @emph{Class}: 1201Elemental function 1202 1203@item @emph{Syntax}: 1204@code{RESULT = ANINT(A [, KIND])} 1205 1206@item @emph{Arguments}: 1207@multitable @columnfractions .15 .70 1208@item @var{A} @tab The type of the argument shall be @code{REAL}. 1209@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 1210expression indicating the kind parameter of the result. 1211@end multitable 1212 1213@item @emph{Return value}: 1214The return value is of type real with the kind type parameter of the 1215argument if the optional @var{KIND} is absent; otherwise, the kind 1216type parameter will be given by @var{KIND}. If @var{A} is greater than 1217zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is 1218less than or equal to zero then it returns @code{AINT(X-0.5)}. 1219 1220@item @emph{Example}: 1221@smallexample 1222program test_anint 1223 real(4) x4 1224 real(8) x8 1225 x4 = 1.234E0_4 1226 x8 = 4.321_8 1227 print *, anint(x4), dnint(x8) 1228 x8 = anint(x4,8) 1229end program test_anint 1230@end smallexample 1231 1232@item @emph{Specific names}: 1233@multitable @columnfractions .20 .20 .20 .25 1234@item Name @tab Argument @tab Return type @tab Standard 1235@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 1236@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 1237@end multitable 1238@end table 1239 1240 1241 1242@node ANY 1243@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 1244@fnindex ANY 1245@cindex array, apply condition 1246@cindex array, condition testing 1247 1248@table @asis 1249@item @emph{Description}: 1250@code{ANY(MASK [, DIM])} determines if any of the values in the logical array 1251@var{MASK} along dimension @var{DIM} are @code{.TRUE.}. 1252 1253@item @emph{Standard}: 1254Fortran 90 and later 1255 1256@item @emph{Class}: 1257Transformational function 1258 1259@item @emph{Syntax}: 1260@code{RESULT = ANY(MASK [, DIM])} 1261 1262@item @emph{Arguments}: 1263@multitable @columnfractions .15 .70 1264@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1265it shall not be scalar. 1266@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1267with a value that lies between one and the rank of @var{MASK}. 1268@end multitable 1269 1270@item @emph{Return value}: 1271@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where 1272the kind type parameter is the same as the kind type parameter of 1273@var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns 1274an array with the rank of @var{MASK} minus 1. The shape is determined from 1275the shape of @var{MASK} where the @var{DIM} dimension is elided. 1276 1277@table @asis 1278@item (A) 1279@code{ANY(MASK)} is true if any element of @var{MASK} is true; 1280otherwise, it is false. It also is false if @var{MASK} has zero size. 1281@item (B) 1282If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent 1283to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)} 1284is determined by applying @code{ANY} to the array sections. 1285@end table 1286 1287@item @emph{Example}: 1288@smallexample 1289program test_any 1290 logical l 1291 l = any((/.true., .true., .true./)) 1292 print *, l 1293 call section 1294 contains 1295 subroutine section 1296 integer a(2,3), b(2,3) 1297 a = 1 1298 b = 1 1299 b(2,2) = 2 1300 print *, any(a .eq. b, 1) 1301 print *, any(a .eq. b, 2) 1302 end subroutine section 1303end program test_any 1304@end smallexample 1305@end table 1306 1307 1308 1309@node ASIN 1310@section @code{ASIN} --- Arcsine function 1311@fnindex ASIN 1312@fnindex DASIN 1313@cindex trigonometric function, sine, inverse 1314@cindex sine, inverse 1315 1316@table @asis 1317@item @emph{Description}: 1318@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}). 1319 1320@item @emph{Standard}: 1321Fortran 77 and later, for a complex argument Fortran 2008 or later 1322 1323@item @emph{Class}: 1324Elemental function 1325 1326@item @emph{Syntax}: 1327@code{RESULT = ASIN(X)} 1328 1329@item @emph{Arguments}: 1330@multitable @columnfractions .15 .70 1331@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1332less than or equal to one - or be @code{COMPLEX}. 1333@end multitable 1334 1335@item @emph{Return value}: 1336The return value is of the same type and kind as @var{X}. 1337The real part of the result is in radians and lies in the range 1338@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}. 1339 1340@item @emph{Example}: 1341@smallexample 1342program test_asin 1343 real(8) :: x = 0.866_8 1344 x = asin(x) 1345end program test_asin 1346@end smallexample 1347 1348@item @emph{Specific names}: 1349@multitable @columnfractions .20 .20 .20 .25 1350@item Name @tab Argument @tab Return type @tab Standard 1351@item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1352@item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1353@end multitable 1354 1355@item @emph{See also}: 1356Inverse function: @gol 1357@ref{SIN} @gol 1358Degrees function: @gol 1359@ref{ASIND} 1360@end table 1361 1362 1363 1364@node ASIND 1365@section @code{ASIND} --- Arcsine function, degrees 1366@fnindex ASIND 1367@fnindex DASIND 1368@cindex trigonometric function, sine, inverse, degrees 1369@cindex sine, inverse, degrees 1370 1371@table @asis 1372@item @emph{Description}: 1373@code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of 1374@code{SIND(X)}). 1375 1376This function is for compatibility only and should be avoided in favor of 1377standard constructs wherever possible. 1378 1379@item @emph{Standard}: 1380GNU extension, enabled with @option{-fdec-math}. 1381 1382@item @emph{Class}: 1383Elemental function 1384 1385@item @emph{Syntax}: 1386@code{RESULT = ASIND(X)} 1387 1388@item @emph{Arguments}: 1389@multitable @columnfractions .15 .70 1390@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1391less than or equal to one - or be @code{COMPLEX}. 1392@end multitable 1393 1394@item @emph{Return value}: 1395The return value is of the same type and kind as @var{X}. 1396The real part of the result is in degrees and lies in the range 1397@math{-90 \leq \Re \asin(x) \leq 90}. 1398 1399@item @emph{Example}: 1400@smallexample 1401program test_asind 1402 real(8) :: x = 0.866_8 1403 x = asind(x) 1404end program test_asind 1405@end smallexample 1406 1407@item @emph{Specific names}: 1408@multitable @columnfractions .20 .20 .20 .25 1409@item Name @tab Argument @tab Return type @tab Standard 1410@item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 1411@item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1412@end multitable 1413 1414@item @emph{See also}: 1415Inverse function: @gol 1416@ref{SIND} @gol 1417Radians function: @gol 1418@ref{ASIN} 1419@end table 1420 1421 1422 1423@node ASINH 1424@section @code{ASINH} --- Inverse hyperbolic sine function 1425@fnindex ASINH 1426@fnindex DASINH 1427@cindex area hyperbolic sine 1428@cindex inverse hyperbolic sine 1429@cindex hyperbolic function, sine, inverse 1430@cindex sine, hyperbolic, inverse 1431 1432@table @asis 1433@item @emph{Description}: 1434@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}. 1435 1436@item @emph{Standard}: 1437Fortran 2008 and later 1438 1439@item @emph{Class}: 1440Elemental function 1441 1442@item @emph{Syntax}: 1443@code{RESULT = ASINH(X)} 1444 1445@item @emph{Arguments}: 1446@multitable @columnfractions .15 .70 1447@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1448@end multitable 1449 1450@item @emph{Return value}: 1451The return value is of the same type and kind as @var{X}. If @var{X} is 1452complex, the imaginary part of the result is in radians and lies between 1453@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}. 1454 1455@item @emph{Example}: 1456@smallexample 1457PROGRAM test_asinh 1458 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1459 WRITE (*,*) ASINH(x) 1460END PROGRAM 1461@end smallexample 1462 1463@item @emph{Specific names}: 1464@multitable @columnfractions .20 .20 .20 .25 1465@item Name @tab Argument @tab Return type @tab Standard 1466@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension. 1467@end multitable 1468 1469@item @emph{See also}: 1470Inverse function: @gol 1471@ref{SINH} 1472@end table 1473 1474 1475 1476@node ASSOCIATED 1477@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 1478@fnindex ASSOCIATED 1479@cindex pointer, status 1480@cindex association status 1481 1482@table @asis 1483@item @emph{Description}: 1484@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer 1485@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}. 1486 1487@item @emph{Standard}: 1488Fortran 90 and later 1489 1490@item @emph{Class}: 1491Inquiry function 1492 1493@item @emph{Syntax}: 1494@code{RESULT = ASSOCIATED(POINTER [, TARGET])} 1495 1496@item @emph{Arguments}: 1497@multitable @columnfractions .15 .70 1498@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute 1499and it can be of any type. 1500@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or 1501a target. It must have the same type, kind type parameter, and 1502array rank as @var{POINTER}. 1503@end multitable 1504The association status of neither @var{POINTER} nor @var{TARGET} shall be 1505undefined. 1506 1507@item @emph{Return value}: 1508@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}. 1509There are several cases: 1510@table @asis 1511@item (A) When the optional @var{TARGET} is not present then 1512@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false. 1513@item (B) If @var{TARGET} is present and a scalar target, the result is true if 1514@var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is 1515disassociated, the result is false. 1516@item (C) If @var{TARGET} is present and an array target, the result is true if 1517@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays, 1518are arrays whose elements are not zero-sized storage sequences, and 1519@var{TARGET} and @var{POINTER} occupy the same storage units in array element 1520order. 1521As in case(B), the result is false, if @var{POINTER} is disassociated. 1522@item (D) If @var{TARGET} is present and an scalar pointer, the result is true 1523if @var{TARGET} is associated with @var{POINTER}, the target associated with 1524@var{TARGET} are not zero-sized storage sequences and occupy the same storage 1525units. 1526The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1527@item (E) If @var{TARGET} is present and an array pointer, the result is true if 1528target associated with @var{POINTER} and the target associated with @var{TARGET} 1529have the same shape, are not zero-sized arrays, are arrays whose elements are 1530not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy 1531the same storage units in array element order. 1532The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1533@end table 1534 1535@item @emph{Example}: 1536@smallexample 1537program test_associated 1538 implicit none 1539 real, target :: tgt(2) = (/1., 2./) 1540 real, pointer :: ptr(:) 1541 ptr => tgt 1542 if (associated(ptr) .eqv. .false.) call abort 1543 if (associated(ptr,tgt) .eqv. .false.) call abort 1544end program test_associated 1545@end smallexample 1546 1547@item @emph{See also}: 1548@ref{NULL} 1549@end table 1550 1551 1552 1553@node ATAN 1554@section @code{ATAN} --- Arctangent function 1555@fnindex ATAN 1556@fnindex DATAN 1557@cindex trigonometric function, tangent, inverse 1558@cindex tangent, inverse 1559 1560@table @asis 1561@item @emph{Description}: 1562@code{ATAN(X)} computes the arctangent of @var{X}. 1563 1564@item @emph{Standard}: 1565Fortran 77 and later, for a complex argument and for two arguments 1566Fortran 2008 or later 1567 1568@item @emph{Class}: 1569Elemental function 1570 1571@item @emph{Syntax}: 1572@multitable @columnfractions .80 1573@item @code{RESULT = ATAN(X)} 1574@item @code{RESULT = ATAN(Y, X)} 1575@end multitable 1576 1577@item @emph{Arguments}: 1578@multitable @columnfractions .15 .70 1579@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1580if @var{Y} is present, @var{X} shall be REAL. 1581@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. 1582@end multitable 1583 1584@item @emph{Return value}: 1585The return value is of the same type and kind as @var{X}. 1586If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}. 1587Otherwise, it the arcus tangent of @var{X}, where the real part of 1588the result is in radians and lies in the range 1589@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}. 1590 1591@item @emph{Example}: 1592@smallexample 1593program test_atan 1594 real(8) :: x = 2.866_8 1595 x = atan(x) 1596end program test_atan 1597@end smallexample 1598 1599@item @emph{Specific names}: 1600@multitable @columnfractions .20 .20 .20 .25 1601@item Name @tab Argument @tab Return type @tab Standard 1602@item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1603@item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1604@end multitable 1605 1606@item @emph{See also}: 1607Inverse function: @gol 1608@ref{TAN} @gol 1609Degrees function: @gol 1610@ref{ATAND} 1611@end table 1612 1613 1614 1615@node ATAND 1616@section @code{ATAND} --- Arctangent function, degrees 1617@fnindex ATAND 1618@fnindex DATAND 1619@cindex trigonometric function, tangent, inverse, degrees 1620@cindex tangent, inverse, degrees 1621 1622@table @asis 1623@item @emph{Description}: 1624@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of 1625@ref{TAND}). 1626 1627This function is for compatibility only and should be avoided in favor of 1628standard constructs wherever possible. 1629 1630@item @emph{Standard}: 1631GNU extension, enabled with @option{-fdec-math}. 1632 1633@item @emph{Class}: 1634Elemental function 1635 1636@item @emph{Syntax}: 1637@multitable @columnfractions .80 1638@item @code{RESULT = ATAND(X)} 1639@item @code{RESULT = ATAND(Y, X)} 1640@end multitable 1641 1642@item @emph{Arguments}: 1643@multitable @columnfractions .15 .70 1644@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1645if @var{Y} is present, @var{X} shall be REAL. 1646@item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. 1647@end multitable 1648 1649@item @emph{Return value}: 1650The return value is of the same type and kind as @var{X}. 1651If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}. 1652Otherwise, it is the arcus tangent of @var{X}, where the real part of 1653the result is in degrees and lies in the range 1654@math{-90 \leq \Re \atand(x) \leq 90}. 1655 1656@item @emph{Example}: 1657@smallexample 1658program test_atand 1659 real(8) :: x = 2.866_8 1660 x = atand(x) 1661end program test_atand 1662@end smallexample 1663 1664@item @emph{Specific names}: 1665@multitable @columnfractions .20 .20 .20 .25 1666@item Name @tab Argument @tab Return type @tab Standard 1667@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 1668@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1669@end multitable 1670 1671@item @emph{See also}: 1672Inverse function: @gol 1673@ref{TAND} @gol 1674Radians function: @gol 1675@ref{ATAN} 1676@end table 1677 1678 1679 1680@node ATAN2 1681@section @code{ATAN2} --- Arctangent function 1682@fnindex ATAN2 1683@fnindex DATAN2 1684@cindex trigonometric function, tangent, inverse 1685@cindex tangent, inverse 1686 1687@table @asis 1688@item @emph{Description}: 1689@code{ATAN2(Y, X)} computes the principal value of the argument 1690function of the complex number @math{X + i Y}. This function can 1691be used to transform from Cartesian into polar coordinates and 1692allows to determine the angle in the correct quadrant. 1693 1694@item @emph{Standard}: 1695Fortran 77 and later 1696 1697@item @emph{Class}: 1698Elemental function 1699 1700@item @emph{Syntax}: 1701@code{RESULT = ATAN2(Y, X)} 1702 1703@item @emph{Arguments}: 1704@multitable @columnfractions .15 .70 1705@item @var{Y} @tab The type shall be @code{REAL}. 1706@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1707If @var{Y} is zero, then @var{X} must be nonzero. 1708@end multitable 1709 1710@item @emph{Return value}: 1711The return value has the same type and kind type parameter as @var{Y}. It 1712is the principal value of the complex number @math{X + i Y}. If @var{X} 1713is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}. 1714The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1715the return value is zero if @var{X} is strictly positive, @math{\pi} if 1716@var{X} is negative and @var{Y} is positive zero (or the processor does 1717not handle signed zeros), and @math{-\pi} if @var{X} is negative and 1718@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1719magnitude of the result is @math{\pi/2}. 1720 1721@item @emph{Example}: 1722@smallexample 1723program test_atan2 1724 real(4) :: x = 1.e0_4, y = 0.5e0_4 1725 x = atan2(y,x) 1726end program test_atan2 1727@end smallexample 1728 1729@item @emph{Specific names}: 1730@multitable @columnfractions .20 .20 .20 .25 1731@item Name @tab Argument @tab Return type @tab Standard 1732@item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 1733@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 1734@end multitable 1735 1736@item @emph{See also}: 1737Alias: @gol 1738@ref{ATAN} @gol 1739Degrees function: @gol 1740@ref{ATAN2D} 1741@end table 1742 1743 1744 1745@node ATAN2D 1746@section @code{ATAN2D} --- Arctangent function, degrees 1747@fnindex ATAN2D 1748@fnindex DATAN2D 1749@cindex trigonometric function, tangent, inverse, degrees 1750@cindex tangent, inverse, degrees 1751 1752@table @asis 1753@item @emph{Description}: 1754@code{ATAN2D(Y, X)} computes the principal value of the argument 1755function of the complex number @math{X + i Y} in degrees. This function can 1756be used to transform from Cartesian into polar coordinates and 1757allows to determine the angle in the correct quadrant. 1758 1759This function is for compatibility only and should be avoided in favor of 1760standard constructs wherever possible. 1761 1762@item @emph{Standard}: 1763GNU extension, enabled with @option{-fdec-math}. 1764 1765@item @emph{Class}: 1766Elemental function 1767 1768@item @emph{Syntax}: 1769@code{RESULT = ATAN2D(Y, X)} 1770 1771@item @emph{Arguments}: 1772@multitable @columnfractions .15 .70 1773@item @var{Y} @tab The type shall be @code{REAL}. 1774@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1775If @var{Y} is zero, then @var{X} must be nonzero. 1776@end multitable 1777 1778@item @emph{Return value}: 1779The return value has the same type and kind type parameter as @var{Y}. It 1780is the principal value of the complex number @math{X + i Y}. If @var{X} 1781is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}. 1782The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1783the return value is zero if @var{X} is strictly positive, @math{180} if 1784@var{X} is negative and @var{Y} is positive zero (or the processor does 1785not handle signed zeros), and @math{-180} if @var{X} is negative and 1786@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1787magnitude of the result is @math{90}. 1788 1789@item @emph{Example}: 1790@smallexample 1791program test_atan2d 1792 real(4) :: x = 1.e0_4, y = 0.5e0_4 1793 x = atan2d(y,x) 1794end program test_atan2d 1795@end smallexample 1796 1797@item @emph{Specific names}: 1798@multitable @columnfractions .20 .20 .20 .25 1799@item Name @tab Argument @tab Return type @tab Standard 1800@item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU extension 1801@item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension 1802@end multitable 1803 1804@item @emph{See also}: 1805Alias: @gol 1806@ref{ATAND} @gol 1807Radians function: @gol 1808@ref{ATAN2} 1809@end table 1810 1811 1812 1813@node ATANH 1814@section @code{ATANH} --- Inverse hyperbolic tangent function 1815@fnindex ATANH 1816@fnindex DATANH 1817@cindex area hyperbolic tangent 1818@cindex inverse hyperbolic tangent 1819@cindex hyperbolic function, tangent, inverse 1820@cindex tangent, hyperbolic, inverse 1821 1822@table @asis 1823@item @emph{Description}: 1824@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}. 1825 1826@item @emph{Standard}: 1827Fortran 2008 and later 1828 1829@item @emph{Class}: 1830Elemental function 1831 1832@item @emph{Syntax}: 1833@code{RESULT = ATANH(X)} 1834 1835@item @emph{Arguments}: 1836@multitable @columnfractions .15 .70 1837@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1838@end multitable 1839 1840@item @emph{Return value}: 1841The return value has same type and kind as @var{X}. If @var{X} is 1842complex, the imaginary part of the result is in radians and lies between 1843@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}. 1844 1845@item @emph{Example}: 1846@smallexample 1847PROGRAM test_atanh 1848 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1849 WRITE (*,*) ATANH(x) 1850END PROGRAM 1851@end smallexample 1852 1853@item @emph{Specific names}: 1854@multitable @columnfractions .20 .20 .20 .25 1855@item Name @tab Argument @tab Return type @tab Standard 1856@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1857@end multitable 1858 1859@item @emph{See also}: 1860Inverse function: @gol 1861@ref{TANH} 1862@end table 1863 1864 1865 1866@node ATOMIC_ADD 1867@section @code{ATOMIC_ADD} --- Atomic ADD operation 1868@fnindex ATOMIC_ADD 1869@cindex Atomic subroutine, add 1870 1871@table @asis 1872@item @emph{Description}: 1873@code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the 1874variable @var{ATOM}. When @var{STAT} is present and the invocation was 1875successful, it is assigned the value 0. If it is present and the invocation 1876has failed, it is assigned a positive value; in particular, for a coindexed 1877@var{ATOM}, if the remote image has stopped, it is assigned the value of 1878@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1879failed, the value @code{STAT_FAILED_IMAGE}. 1880 1881@item @emph{Standard}: 1882TS 18508 or later 1883 1884@item @emph{Class}: 1885Atomic subroutine 1886 1887@item @emph{Syntax}: 1888@code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])} 1889 1890@item @emph{Arguments}: 1891@multitable @columnfractions .15 .70 1892@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1893type with @code{ATOMIC_INT_KIND} kind. 1894@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1895is different, the value is converted to the kind of @var{ATOM}. 1896@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1897@end multitable 1898 1899@item @emph{Example}: 1900@smallexample 1901program atomic 1902 use iso_fortran_env 1903 integer(atomic_int_kind) :: atom[*] 1904 call atomic_add (atom[1], this_image()) 1905end program atomic 1906@end smallexample 1907 1908@item @emph{See also}: 1909@ref{ATOMIC_DEFINE}, @gol 1910@ref{ATOMIC_FETCH_ADD}, @gol 1911@ref{ISO_FORTRAN_ENV}, @gol 1912@ref{ATOMIC_AND}, @gol 1913@ref{ATOMIC_OR}, @gol 1914@ref{ATOMIC_XOR} 1915@end table 1916 1917 1918 1919 1920@node ATOMIC_AND 1921@section @code{ATOMIC_AND} --- Atomic bitwise AND operation 1922@fnindex ATOMIC_AND 1923@cindex Atomic subroutine, AND 1924 1925@table @asis 1926@item @emph{Description}: 1927@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 1928AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 1929and the invocation was successful, it is assigned the value 0. If it is present 1930and the invocation has failed, it is assigned a positive value; in particular, 1931for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 1932value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 1933image has failed, the value @code{STAT_FAILED_IMAGE}. 1934 1935@item @emph{Standard}: 1936TS 18508 or later 1937 1938@item @emph{Class}: 1939Atomic subroutine 1940 1941@item @emph{Syntax}: 1942@code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])} 1943 1944@item @emph{Arguments}: 1945@multitable @columnfractions .15 .70 1946@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1947type with @code{ATOMIC_INT_KIND} kind. 1948@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1949is different, the value is converted to the kind of @var{ATOM}. 1950@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1951@end multitable 1952 1953@item @emph{Example}: 1954@smallexample 1955program atomic 1956 use iso_fortran_env 1957 integer(atomic_int_kind) :: atom[*] 1958 call atomic_and (atom[1], int(b'10100011101')) 1959end program atomic 1960@end smallexample 1961 1962@item @emph{See also}: 1963@ref{ATOMIC_DEFINE}, @gol 1964@ref{ATOMIC_FETCH_AND}, @gol 1965@ref{ISO_FORTRAN_ENV}, @gol 1966@ref{ATOMIC_ADD}, @gol 1967@ref{ATOMIC_OR}, @gol 1968@ref{ATOMIC_XOR} 1969@end table 1970 1971 1972 1973@node ATOMIC_CAS 1974@section @code{ATOMIC_CAS} --- Atomic compare and swap 1975@fnindex ATOMIC_DEFINE 1976@cindex Atomic subroutine, compare and swap 1977 1978@table @asis 1979@item @emph{Description}: 1980@code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of 1981@var{COMPARE}; if the value is the same, @var{ATOM} is set to the value 1982of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM} 1983that was used for the comparison. When @var{STAT} is present and the invocation 1984was successful, it is assigned the value 0. If it is present and the invocation 1985has failed, it is assigned a positive value; in particular, for a coindexed 1986@var{ATOM}, if the remote image has stopped, it is assigned the value of 1987@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1988failed, the value @code{STAT_FAILED_IMAGE}. 1989 1990@item @emph{Standard}: 1991TS 18508 or later 1992 1993@item @emph{Class}: 1994Atomic subroutine 1995 1996@item @emph{Syntax}: 1997@code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])} 1998 1999@item @emph{Arguments}: 2000@multitable @columnfractions .15 .70 2001@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2002type with @code{ATOMIC_INT_KIND} kind or logical type with 2003@code{ATOMIC_LOGICAL_KIND} kind. 2004@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2005@item @var{COMPARE} @tab Scalar variable of the same type and kind as 2006@var{ATOM}. 2007@item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind 2008is different, the value is converted to the kind of @var{ATOM}. 2009@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2010@end multitable 2011 2012@item @emph{Example}: 2013@smallexample 2014program atomic 2015 use iso_fortran_env 2016 logical(atomic_logical_kind) :: atom[*], prev 2017 call atomic_cas (atom[1], prev, .false., .true.)) 2018end program atomic 2019@end smallexample 2020 2021@item @emph{See also}: 2022@ref{ATOMIC_DEFINE}, @gol 2023@ref{ATOMIC_REF}, @gol 2024@ref{ISO_FORTRAN_ENV} 2025@end table 2026 2027 2028 2029@node ATOMIC_DEFINE 2030@section @code{ATOMIC_DEFINE} --- Setting a variable atomically 2031@fnindex ATOMIC_DEFINE 2032@cindex Atomic subroutine, define 2033 2034@table @asis 2035@item @emph{Description}: 2036@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value 2037@var{VALUE} atomically. When @var{STAT} is present and the invocation was 2038successful, it is assigned the value 0. If it is present and the invocation 2039has failed, it is assigned a positive value; in particular, for a coindexed 2040@var{ATOM}, if the remote image has stopped, it is assigned the value of 2041@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2042failed, the value @code{STAT_FAILED_IMAGE}. 2043 2044@item @emph{Standard}: 2045Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2046 2047@item @emph{Class}: 2048Atomic subroutine 2049 2050@item @emph{Syntax}: 2051@code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])} 2052 2053@item @emph{Arguments}: 2054@multitable @columnfractions .15 .70 2055@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2056type with @code{ATOMIC_INT_KIND} kind or logical type with 2057@code{ATOMIC_LOGICAL_KIND} kind. 2058 2059@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2060is different, the value is converted to the kind of @var{ATOM}. 2061@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2062@end multitable 2063 2064@item @emph{Example}: 2065@smallexample 2066program atomic 2067 use iso_fortran_env 2068 integer(atomic_int_kind) :: atom[*] 2069 call atomic_define (atom[1], this_image()) 2070end program atomic 2071@end smallexample 2072 2073@item @emph{See also}: 2074@ref{ATOMIC_REF}, @gol 2075@ref{ATOMIC_CAS}, @gol 2076@ref{ISO_FORTRAN_ENV}, @gol 2077@ref{ATOMIC_ADD}, @gol 2078@ref{ATOMIC_AND}, @gol 2079@ref{ATOMIC_OR}, @gol 2080@ref{ATOMIC_XOR} 2081@end table 2082 2083 2084 2085@node ATOMIC_FETCH_ADD 2086@section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch 2087@fnindex ATOMIC_FETCH_ADD 2088@cindex Atomic subroutine, ADD with fetch 2089 2090@table @asis 2091@item @emph{Description}: 2092@code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of 2093@var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the 2094variable @var{ATOM}. When @var{STAT} is present and the invocation was 2095successful, it is assigned the value 0. If it is present and the invocation 2096has failed, it is assigned a positive value; in particular, for a coindexed 2097@var{ATOM}, if the remote image has stopped, it is assigned the value of 2098@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2099failed, the value @code{STAT_FAILED_IMAGE}. 2100 2101@item @emph{Standard}: 2102TS 18508 or later 2103 2104@item @emph{Class}: 2105Atomic subroutine 2106 2107@item @emph{Syntax}: 2108@code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])} 2109 2110@item @emph{Arguments}: 2111@multitable @columnfractions .15 .70 2112@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2113type with @code{ATOMIC_INT_KIND} kind. 2114@code{ATOMIC_LOGICAL_KIND} kind. 2115 2116@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2117is different, the value is converted to the kind of @var{ATOM}. 2118@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2119@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2120@end multitable 2121 2122@item @emph{Example}: 2123@smallexample 2124program atomic 2125 use iso_fortran_env 2126 integer(atomic_int_kind) :: atom[*], old 2127 call atomic_add (atom[1], this_image(), old) 2128end program atomic 2129@end smallexample 2130 2131@item @emph{See also}: 2132@ref{ATOMIC_DEFINE}, @gol 2133@ref{ATOMIC_ADD}, @gol 2134@ref{ISO_FORTRAN_ENV}, @gol 2135@ref{ATOMIC_FETCH_AND}, @gol 2136@ref{ATOMIC_FETCH_OR}, @gol 2137@ref{ATOMIC_FETCH_XOR} 2138@end table 2139 2140 2141 2142@node ATOMIC_FETCH_AND 2143@section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch 2144@fnindex ATOMIC_FETCH_AND 2145@cindex Atomic subroutine, AND with fetch 2146 2147@table @asis 2148@item @emph{Description}: 2149@code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2150@var{OLD} and defines @var{ATOM} with the bitwise AND between the values of 2151@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2152successful, it is assigned the value 0. If it is present and the invocation has 2153failed, it is assigned a positive value; in particular, for a coindexed 2154@var{ATOM}, if the remote image has stopped, it is assigned the value of 2155@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2156failed, the value @code{STAT_FAILED_IMAGE}. 2157 2158@item @emph{Standard}: 2159TS 18508 or later 2160 2161@item @emph{Class}: 2162Atomic subroutine 2163 2164@item @emph{Syntax}: 2165@code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])} 2166 2167@item @emph{Arguments}: 2168@multitable @columnfractions .15 .70 2169@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2170type with @code{ATOMIC_INT_KIND} kind. 2171@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2172is different, the value is converted to the kind of @var{ATOM}. 2173@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2174@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2175@end multitable 2176 2177@item @emph{Example}: 2178@smallexample 2179program atomic 2180 use iso_fortran_env 2181 integer(atomic_int_kind) :: atom[*], old 2182 call atomic_fetch_and (atom[1], int(b'10100011101'), old) 2183end program atomic 2184@end smallexample 2185 2186@item @emph{See also}: 2187@ref{ATOMIC_DEFINE}, @gol 2188@ref{ATOMIC_AND}, @gol 2189@ref{ISO_FORTRAN_ENV}, @gol 2190@ref{ATOMIC_FETCH_ADD}, @gol 2191@ref{ATOMIC_FETCH_OR}, @gol 2192@ref{ATOMIC_FETCH_XOR} 2193@end table 2194 2195 2196 2197@node ATOMIC_FETCH_OR 2198@section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch 2199@fnindex ATOMIC_FETCH_OR 2200@cindex Atomic subroutine, OR with fetch 2201 2202@table @asis 2203@item @emph{Description}: 2204@code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2205@var{OLD} and defines @var{ATOM} with the bitwise OR between the values of 2206@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2207successful, it is assigned the value 0. If it is present and the invocation has 2208failed, it is assigned a positive value; in particular, for a coindexed 2209@var{ATOM}, if the remote image has stopped, it is assigned the value of 2210@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2211failed, the value @code{STAT_FAILED_IMAGE}. 2212 2213@item @emph{Standard}: 2214TS 18508 or later 2215 2216@item @emph{Class}: 2217Atomic subroutine 2218 2219@item @emph{Syntax}: 2220@code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])} 2221 2222@item @emph{Arguments}: 2223@multitable @columnfractions .15 .70 2224@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2225type with @code{ATOMIC_INT_KIND} kind. 2226@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2227is different, the value is converted to the kind of @var{ATOM}. 2228@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2229@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2230@end multitable 2231 2232@item @emph{Example}: 2233@smallexample 2234program atomic 2235 use iso_fortran_env 2236 integer(atomic_int_kind) :: atom[*], old 2237 call atomic_fetch_or (atom[1], int(b'10100011101'), old) 2238end program atomic 2239@end smallexample 2240 2241@item @emph{See also}: 2242@ref{ATOMIC_DEFINE}, @gol 2243@ref{ATOMIC_OR}, @gol 2244@ref{ISO_FORTRAN_ENV}, @gol 2245@ref{ATOMIC_FETCH_ADD}, @gol 2246@ref{ATOMIC_FETCH_AND}, @gol 2247@ref{ATOMIC_FETCH_XOR} 2248@end table 2249 2250 2251 2252@node ATOMIC_FETCH_XOR 2253@section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch 2254@fnindex ATOMIC_FETCH_XOR 2255@cindex Atomic subroutine, XOR with fetch 2256 2257@table @asis 2258@item @emph{Description}: 2259@code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2260@var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of 2261@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2262successful, it is assigned the value 0. If it is present and the invocation has 2263failed, it is assigned a positive value; in particular, for a coindexed 2264@var{ATOM}, if the remote image has stopped, it is assigned the value of 2265@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2266failed, the value @code{STAT_FAILED_IMAGE}. 2267 2268@item @emph{Standard}: 2269TS 18508 or later 2270 2271@item @emph{Class}: 2272Atomic subroutine 2273 2274@item @emph{Syntax}: 2275@code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])} 2276 2277@item @emph{Arguments}: 2278@multitable @columnfractions .15 .70 2279@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2280type with @code{ATOMIC_INT_KIND} kind. 2281@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2282is different, the value is converted to the kind of @var{ATOM}. 2283@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2284@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2285@end multitable 2286 2287@item @emph{Example}: 2288@smallexample 2289program atomic 2290 use iso_fortran_env 2291 integer(atomic_int_kind) :: atom[*], old 2292 call atomic_fetch_xor (atom[1], int(b'10100011101'), old) 2293end program atomic 2294@end smallexample 2295 2296@item @emph{See also}: 2297@ref{ATOMIC_DEFINE}, @gol 2298@ref{ATOMIC_XOR}, @gol 2299@ref{ISO_FORTRAN_ENV}, @gol 2300@ref{ATOMIC_FETCH_ADD}, @gol 2301@ref{ATOMIC_FETCH_AND}, @gol 2302@ref{ATOMIC_FETCH_OR} 2303@end table 2304 2305 2306 2307@node ATOMIC_OR 2308@section @code{ATOMIC_OR} --- Atomic bitwise OR operation 2309@fnindex ATOMIC_OR 2310@cindex Atomic subroutine, OR 2311 2312@table @asis 2313@item @emph{Description}: 2314@code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2315AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2316and the invocation was successful, it is assigned the value 0. If it is present 2317and the invocation has failed, it is assigned a positive value; in particular, 2318for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2319value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2320image has failed, the value @code{STAT_FAILED_IMAGE}. 2321 2322@item @emph{Standard}: 2323TS 18508 or later 2324 2325@item @emph{Class}: 2326Atomic subroutine 2327 2328@item @emph{Syntax}: 2329@code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])} 2330 2331@item @emph{Arguments}: 2332@multitable @columnfractions .15 .70 2333@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2334type with @code{ATOMIC_INT_KIND} kind. 2335@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2336is different, the value is converted to the kind of @var{ATOM}. 2337@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2338@end multitable 2339 2340@item @emph{Example}: 2341@smallexample 2342program atomic 2343 use iso_fortran_env 2344 integer(atomic_int_kind) :: atom[*] 2345 call atomic_or (atom[1], int(b'10100011101')) 2346end program atomic 2347@end smallexample 2348 2349@item @emph{See also}: 2350@ref{ATOMIC_DEFINE}, @gol 2351@ref{ATOMIC_FETCH_OR}, @gol 2352@ref{ISO_FORTRAN_ENV}, @gol 2353@ref{ATOMIC_ADD}, @gol 2354@ref{ATOMIC_OR}, @gol 2355@ref{ATOMIC_XOR} 2356@end table 2357 2358 2359 2360@node ATOMIC_REF 2361@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically 2362@fnindex ATOMIC_REF 2363@cindex Atomic subroutine, reference 2364 2365@table @asis 2366@item @emph{Description}: 2367@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the 2368variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the 2369invocation was successful, it is assigned the value 0. If it is present and the 2370invocation has failed, it is assigned a positive value; in particular, for a 2371coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value 2372of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image 2373has failed, the value @code{STAT_FAILED_IMAGE}. 2374 2375 2376@item @emph{Standard}: 2377Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2378 2379@item @emph{Class}: 2380Atomic subroutine 2381 2382@item @emph{Syntax}: 2383@code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])} 2384 2385@item @emph{Arguments}: 2386@multitable @columnfractions .15 .70 2387@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2388is different, the value is converted to the kind of @var{ATOM}. 2389@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2390type with @code{ATOMIC_INT_KIND} kind or logical type with 2391@code{ATOMIC_LOGICAL_KIND} kind. 2392@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2393@end multitable 2394 2395@item @emph{Example}: 2396@smallexample 2397program atomic 2398 use iso_fortran_env 2399 logical(atomic_logical_kind) :: atom[*] 2400 logical :: val 2401 call atomic_ref (atom, .false.) 2402 ! ... 2403 call atomic_ref (atom, val) 2404 if (val) then 2405 print *, "Obtained" 2406 end if 2407end program atomic 2408@end smallexample 2409 2410@item @emph{See also}: 2411@ref{ATOMIC_DEFINE}, @gol 2412@ref{ATOMIC_CAS}, @gol 2413@ref{ISO_FORTRAN_ENV}, @gol 2414@ref{ATOMIC_FETCH_ADD}, @gol 2415@ref{ATOMIC_FETCH_AND}, @gol 2416@ref{ATOMIC_FETCH_OR}, @gol 2417@ref{ATOMIC_FETCH_XOR} 2418@end table 2419 2420 2421@node ATOMIC_XOR 2422@section @code{ATOMIC_XOR} --- Atomic bitwise OR operation 2423@fnindex ATOMIC_XOR 2424@cindex Atomic subroutine, XOR 2425 2426@table @asis 2427@item @emph{Description}: 2428@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2429XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2430and the invocation was successful, it is assigned the value 0. If it is present 2431and the invocation has failed, it is assigned a positive value; in particular, 2432for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2433value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2434image has failed, the value @code{STAT_FAILED_IMAGE}. 2435 2436@item @emph{Standard}: 2437TS 18508 or later 2438 2439@item @emph{Class}: 2440Atomic subroutine 2441 2442@item @emph{Syntax}: 2443@code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])} 2444 2445@item @emph{Arguments}: 2446@multitable @columnfractions .15 .70 2447@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2448type with @code{ATOMIC_INT_KIND} kind. 2449@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2450is different, the value is converted to the kind of @var{ATOM}. 2451@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2452@end multitable 2453 2454@item @emph{Example}: 2455@smallexample 2456program atomic 2457 use iso_fortran_env 2458 integer(atomic_int_kind) :: atom[*] 2459 call atomic_xor (atom[1], int(b'10100011101')) 2460end program atomic 2461@end smallexample 2462 2463@item @emph{See also}: 2464@ref{ATOMIC_DEFINE}, @gol 2465@ref{ATOMIC_FETCH_XOR}, @gol 2466@ref{ISO_FORTRAN_ENV}, @gol 2467@ref{ATOMIC_ADD}, @gol 2468@ref{ATOMIC_OR}, @gol 2469@ref{ATOMIC_XOR} 2470@end table 2471 2472 2473@node BACKTRACE 2474@section @code{BACKTRACE} --- Show a backtrace 2475@fnindex BACKTRACE 2476@cindex backtrace 2477 2478@table @asis 2479@item @emph{Description}: 2480@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program 2481execution continues normally afterwards. The backtrace information is printed 2482to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}. 2483 2484@item @emph{Standard}: 2485GNU extension 2486 2487@item @emph{Class}: 2488Subroutine 2489 2490@item @emph{Syntax}: 2491@code{CALL BACKTRACE} 2492 2493@item @emph{Arguments}: 2494None 2495 2496@item @emph{See also}: 2497@ref{ABORT} 2498@end table 2499 2500 2501 2502@node BESSEL_J0 2503@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0 2504@fnindex BESSEL_J0 2505@fnindex BESJ0 2506@fnindex DBESJ0 2507@cindex Bessel function, first kind 2508 2509@table @asis 2510@item @emph{Description}: 2511@code{BESSEL_J0(X)} computes the Bessel function of the first kind of 2512order 0 of @var{X}. This function is available under the name 2513@code{BESJ0} as a GNU extension. 2514 2515@item @emph{Standard}: 2516Fortran 2008 and later 2517 2518@item @emph{Class}: 2519Elemental function 2520 2521@item @emph{Syntax}: 2522@code{RESULT = BESSEL_J0(X)} 2523 2524@item @emph{Arguments}: 2525@multitable @columnfractions .15 .70 2526@item @var{X} @tab The type shall be @code{REAL}. 2527@end multitable 2528 2529@item @emph{Return value}: 2530The return value is of type @code{REAL} and lies in the 2531range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same 2532kind as @var{X}. 2533 2534@item @emph{Example}: 2535@smallexample 2536program test_besj0 2537 real(8) :: x = 0.0_8 2538 x = bessel_j0(x) 2539end program test_besj0 2540@end smallexample 2541 2542@item @emph{Specific names}: 2543@multitable @columnfractions .20 .20 .20 .25 2544@item Name @tab Argument @tab Return type @tab Standard 2545@item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2546@end multitable 2547@end table 2548 2549 2550 2551@node BESSEL_J1 2552@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1 2553@fnindex BESSEL_J1 2554@fnindex BESJ1 2555@fnindex DBESJ1 2556@cindex Bessel function, first kind 2557 2558@table @asis 2559@item @emph{Description}: 2560@code{BESSEL_J1(X)} computes the Bessel function of the first kind of 2561order 1 of @var{X}. This function is available under the name 2562@code{BESJ1} as a GNU extension. 2563 2564@item @emph{Standard}: 2565Fortran 2008 2566 2567@item @emph{Class}: 2568Elemental function 2569 2570@item @emph{Syntax}: 2571@code{RESULT = BESSEL_J1(X)} 2572 2573@item @emph{Arguments}: 2574@multitable @columnfractions .15 .70 2575@item @var{X} @tab The type shall be @code{REAL}. 2576@end multitable 2577 2578@item @emph{Return value}: 2579The return value is of type @code{REAL} and lies in the 2580range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same 2581kind as @var{X}. 2582 2583@item @emph{Example}: 2584@smallexample 2585program test_besj1 2586 real(8) :: x = 1.0_8 2587 x = bessel_j1(x) 2588end program test_besj1 2589@end smallexample 2590 2591@item @emph{Specific names}: 2592@multitable @columnfractions .20 .20 .20 .25 2593@item Name @tab Argument @tab Return type @tab Standard 2594@item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2595@end multitable 2596@end table 2597 2598 2599 2600@node BESSEL_JN 2601@section @code{BESSEL_JN} --- Bessel function of the first kind 2602@fnindex BESSEL_JN 2603@fnindex BESJN 2604@fnindex DBESJN 2605@cindex Bessel function, first kind 2606 2607@table @asis 2608@item @emph{Description}: 2609@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of 2610order @var{N} of @var{X}. This function is available under the name 2611@code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays, 2612their ranks and shapes shall conform. 2613 2614@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions 2615of the first kind of the orders @var{N1} to @var{N2}. 2616 2617@item @emph{Standard}: 2618Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2619 2620@item @emph{Class}: 2621Elemental function, except for the transformational function 2622@code{BESSEL_JN(N1, N2, X)} 2623 2624@item @emph{Syntax}: 2625@multitable @columnfractions .80 2626@item @code{RESULT = BESSEL_JN(N, X)} 2627@item @code{RESULT = BESSEL_JN(N1, N2, X)} 2628@end multitable 2629 2630@item @emph{Arguments}: 2631@multitable @columnfractions .15 .70 2632@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}. 2633@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2634@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2635@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2636for @code{BESSEL_JN(N1, N2, X)} it shall be scalar. 2637@end multitable 2638 2639@item @emph{Return value}: 2640The return value is a scalar of type @code{REAL}. It has the same 2641kind as @var{X}. 2642 2643@item @emph{Note}: 2644The transformational function uses a recurrence algorithm which might, 2645for some values of @var{X}, lead to different results than calls to 2646the elemental function. 2647 2648@item @emph{Example}: 2649@smallexample 2650program test_besjn 2651 real(8) :: x = 1.0_8 2652 x = bessel_jn(5,x) 2653end program test_besjn 2654@end smallexample 2655 2656@item @emph{Specific names}: 2657@multitable @columnfractions .20 .20 .20 .25 2658@item Name @tab Argument @tab Return type @tab Standard 2659@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2660@item @tab @code{REAL(8) X} @tab @tab 2661@end multitable 2662@end table 2663 2664 2665 2666@node BESSEL_Y0 2667@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0 2668@fnindex BESSEL_Y0 2669@fnindex BESY0 2670@fnindex DBESY0 2671@cindex Bessel function, second kind 2672 2673@table @asis 2674@item @emph{Description}: 2675@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of 2676order 0 of @var{X}. This function is available under the name 2677@code{BESY0} as a GNU extension. 2678 2679@item @emph{Standard}: 2680Fortran 2008 and later 2681 2682@item @emph{Class}: 2683Elemental function 2684 2685@item @emph{Syntax}: 2686@code{RESULT = BESSEL_Y0(X)} 2687 2688@item @emph{Arguments}: 2689@multitable @columnfractions .15 .70 2690@item @var{X} @tab The type shall be @code{REAL}. 2691@end multitable 2692 2693@item @emph{Return value}: 2694The return value is of type @code{REAL}. It has the same kind as @var{X}. 2695 2696@item @emph{Example}: 2697@smallexample 2698program test_besy0 2699 real(8) :: x = 0.0_8 2700 x = bessel_y0(x) 2701end program test_besy0 2702@end smallexample 2703 2704@item @emph{Specific names}: 2705@multitable @columnfractions .20 .20 .20 .25 2706@item Name @tab Argument @tab Return type @tab Standard 2707@item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2708@end multitable 2709@end table 2710 2711 2712 2713@node BESSEL_Y1 2714@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1 2715@fnindex BESSEL_Y1 2716@fnindex BESY1 2717@fnindex DBESY1 2718@cindex Bessel function, second kind 2719 2720@table @asis 2721@item @emph{Description}: 2722@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of 2723order 1 of @var{X}. This function is available under the name 2724@code{BESY1} as a GNU extension. 2725 2726@item @emph{Standard}: 2727Fortran 2008 and later 2728 2729@item @emph{Class}: 2730Elemental function 2731 2732@item @emph{Syntax}: 2733@code{RESULT = BESSEL_Y1(X)} 2734 2735@item @emph{Arguments}: 2736@multitable @columnfractions .15 .70 2737@item @var{X} @tab The type shall be @code{REAL}. 2738@end multitable 2739 2740@item @emph{Return value}: 2741The return value is of type @code{REAL}. It has the same kind as @var{X}. 2742 2743@item @emph{Example}: 2744@smallexample 2745program test_besy1 2746 real(8) :: x = 1.0_8 2747 x = bessel_y1(x) 2748end program test_besy1 2749@end smallexample 2750 2751@item @emph{Specific names}: 2752@multitable @columnfractions .20 .20 .20 .25 2753@item Name @tab Argument @tab Return type @tab Standard 2754@item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2755@end multitable 2756@end table 2757 2758 2759 2760@node BESSEL_YN 2761@section @code{BESSEL_YN} --- Bessel function of the second kind 2762@fnindex BESSEL_YN 2763@fnindex BESYN 2764@fnindex DBESYN 2765@cindex Bessel function, second kind 2766 2767@table @asis 2768@item @emph{Description}: 2769@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of 2770order @var{N} of @var{X}. This function is available under the name 2771@code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays, 2772their ranks and shapes shall conform. 2773 2774@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions 2775of the first kind of the orders @var{N1} to @var{N2}. 2776 2777@item @emph{Standard}: 2778Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2779 2780@item @emph{Class}: 2781Elemental function, except for the transformational function 2782@code{BESSEL_YN(N1, N2, X)} 2783 2784@item @emph{Syntax}: 2785@multitable @columnfractions .80 2786@item @code{RESULT = BESSEL_YN(N, X)} 2787@item @code{RESULT = BESSEL_YN(N1, N2, X)} 2788@end multitable 2789 2790@item @emph{Arguments}: 2791@multitable @columnfractions .15 .70 2792@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} . 2793@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2794@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2795@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2796for @code{BESSEL_YN(N1, N2, X)} it shall be scalar. 2797@end multitable 2798 2799@item @emph{Return value}: 2800The return value is a scalar of type @code{REAL}. It has the same 2801kind as @var{X}. 2802 2803@item @emph{Note}: 2804The transformational function uses a recurrence algorithm which might, 2805for some values of @var{X}, lead to different results than calls to 2806the elemental function. 2807 2808@item @emph{Example}: 2809@smallexample 2810program test_besyn 2811 real(8) :: x = 1.0_8 2812 x = bessel_yn(5,x) 2813end program test_besyn 2814@end smallexample 2815 2816@item @emph{Specific names}: 2817@multitable @columnfractions .20 .20 .20 .25 2818@item Name @tab Argument @tab Return type @tab Standard 2819@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2820@item @tab @code{REAL(8) X} @tab @tab 2821@end multitable 2822@end table 2823 2824 2825 2826@node BGE 2827@section @code{BGE} --- Bitwise greater than or equal to 2828@fnindex BGE 2829@cindex bitwise comparison 2830 2831@table @asis 2832@item @emph{Description}: 2833Determines whether an integral is a bitwise greater than or equal to 2834another. 2835 2836@item @emph{Standard}: 2837Fortran 2008 and later 2838 2839@item @emph{Class}: 2840Elemental function 2841 2842@item @emph{Syntax}: 2843@code{RESULT = BGE(I, J)} 2844 2845@item @emph{Arguments}: 2846@multitable @columnfractions .15 .70 2847@item @var{I} @tab Shall be of @code{INTEGER} type. 2848@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2849as @var{I}. 2850@end multitable 2851 2852@item @emph{Return value}: 2853The return value is of type @code{LOGICAL} and of the default kind. 2854 2855@item @emph{See also}: 2856@ref{BGT}, @gol 2857@ref{BLE}, @gol 2858@ref{BLT} 2859@end table 2860 2861 2862 2863@node BGT 2864@section @code{BGT} --- Bitwise greater than 2865@fnindex BGT 2866@cindex bitwise comparison 2867 2868@table @asis 2869@item @emph{Description}: 2870Determines whether an integral is a bitwise greater than another. 2871 2872@item @emph{Standard}: 2873Fortran 2008 and later 2874 2875@item @emph{Class}: 2876Elemental function 2877 2878@item @emph{Syntax}: 2879@code{RESULT = BGT(I, J)} 2880 2881@item @emph{Arguments}: 2882@multitable @columnfractions .15 .70 2883@item @var{I} @tab Shall be of @code{INTEGER} type. 2884@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2885as @var{I}. 2886@end multitable 2887 2888@item @emph{Return value}: 2889The return value is of type @code{LOGICAL} and of the default kind. 2890 2891@item @emph{See also}: 2892@ref{BGE}, @gol 2893@ref{BLE}, @gol 2894@ref{BLT} 2895@end table 2896 2897 2898 2899@node BIT_SIZE 2900@section @code{BIT_SIZE} --- Bit size inquiry function 2901@fnindex BIT_SIZE 2902@cindex bits, number of 2903@cindex size of a variable, in bits 2904 2905@table @asis 2906@item @emph{Description}: 2907@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) 2908represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is 2909independent of the actual value of @var{I}. 2910 2911@item @emph{Standard}: 2912Fortran 90 and later 2913 2914@item @emph{Class}: 2915Inquiry function 2916 2917@item @emph{Syntax}: 2918@code{RESULT = BIT_SIZE(I)} 2919 2920@item @emph{Arguments}: 2921@multitable @columnfractions .15 .70 2922@item @var{I} @tab The type shall be @code{INTEGER}. 2923@end multitable 2924 2925@item @emph{Return value}: 2926The return value is of type @code{INTEGER} 2927 2928@item @emph{Example}: 2929@smallexample 2930program test_bit_size 2931 integer :: i = 123 2932 integer :: size 2933 size = bit_size(i) 2934 print *, size 2935end program test_bit_size 2936@end smallexample 2937@end table 2938 2939 2940 2941@node BLE 2942@section @code{BLE} --- Bitwise less than or equal to 2943@fnindex BLE 2944@cindex bitwise comparison 2945 2946@table @asis 2947@item @emph{Description}: 2948Determines whether an integral is a bitwise less than or equal to 2949another. 2950 2951@item @emph{Standard}: 2952Fortran 2008 and later 2953 2954@item @emph{Class}: 2955Elemental function 2956 2957@item @emph{Syntax}: 2958@code{RESULT = BLE(I, J)} 2959 2960@item @emph{Arguments}: 2961@multitable @columnfractions .15 .70 2962@item @var{I} @tab Shall be of @code{INTEGER} type. 2963@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2964as @var{I}. 2965@end multitable 2966 2967@item @emph{Return value}: 2968The return value is of type @code{LOGICAL} and of the default kind. 2969 2970@item @emph{See also}: 2971@ref{BGT}, @gol 2972@ref{BGE}, @gol 2973@ref{BLT} 2974@end table 2975 2976 2977 2978@node BLT 2979@section @code{BLT} --- Bitwise less than 2980@fnindex BLT 2981@cindex bitwise comparison 2982 2983@table @asis 2984@item @emph{Description}: 2985Determines whether an integral is a bitwise less than another. 2986 2987@item @emph{Standard}: 2988Fortran 2008 and later 2989 2990@item @emph{Class}: 2991Elemental function 2992 2993@item @emph{Syntax}: 2994@code{RESULT = BLT(I, J)} 2995 2996@item @emph{Arguments}: 2997@multitable @columnfractions .15 .70 2998@item @var{I} @tab Shall be of @code{INTEGER} type. 2999@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 3000as @var{I}. 3001@end multitable 3002 3003@item @emph{Return value}: 3004The return value is of type @code{LOGICAL} and of the default kind. 3005 3006@item @emph{See also}: 3007@ref{BGE}, @gol 3008@ref{BGT}, @gol 3009@ref{BLE} 3010@end table 3011 3012 3013 3014@node BTEST 3015@section @code{BTEST} --- Bit test function 3016@fnindex BTEST 3017@fnindex BBTEST 3018@fnindex BITEST 3019@fnindex BJTEST 3020@fnindex BKTEST 3021@cindex bits, testing 3022 3023@table @asis 3024@item @emph{Description}: 3025@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} 3026in @var{I} is set. The counting of the bits starts at 0. 3027 3028@item @emph{Standard}: 3029Fortran 90 and later, has overloads that are GNU extensions 3030 3031@item @emph{Class}: 3032Elemental function 3033 3034@item @emph{Syntax}: 3035@code{RESULT = BTEST(I, POS)} 3036 3037@item @emph{Arguments}: 3038@multitable @columnfractions .15 .70 3039@item @var{I} @tab The type shall be @code{INTEGER}. 3040@item @var{POS} @tab The type shall be @code{INTEGER}. 3041@end multitable 3042 3043@item @emph{Return value}: 3044The return value is of type @code{LOGICAL} 3045 3046@item @emph{Example}: 3047@smallexample 3048program test_btest 3049 integer :: i = 32768 + 1024 + 64 3050 integer :: pos 3051 logical :: bool 3052 do pos=0,16 3053 bool = btest(i, pos) 3054 print *, pos, bool 3055 end do 3056end program test_btest 3057@end smallexample 3058 3059@item @emph{Specific names}: 3060@multitable @columnfractions .20 .20 .20 .25 3061@item Name @tab Argument @tab Return type @tab Standard 3062@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later 3063@item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension 3064@item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension 3065@item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension 3066@item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension 3067@end multitable 3068@end table 3069 3070@node C_ASSOCIATED 3071@section @code{C_ASSOCIATED} --- Status of a C pointer 3072@fnindex C_ASSOCIATED 3073@cindex association status, C pointer 3074@cindex pointer, C association status 3075 3076@table @asis 3077@item @emph{Description}: 3078@code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer 3079@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}. 3080 3081@item @emph{Standard}: 3082Fortran 2003 and later 3083 3084@item @emph{Class}: 3085Inquiry function 3086 3087@item @emph{Syntax}: 3088@code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])} 3089 3090@item @emph{Arguments}: 3091@multitable @columnfractions .15 .70 3092@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}. 3093@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}. 3094@end multitable 3095 3096@item @emph{Return value}: 3097The return value is of type @code{LOGICAL}; it is @code{.false.} if either 3098@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2} 3099point to different addresses. 3100 3101@item @emph{Example}: 3102@smallexample 3103subroutine association_test(a,b) 3104 use iso_c_binding, only: c_associated, c_loc, c_ptr 3105 implicit none 3106 real, pointer :: a 3107 type(c_ptr) :: b 3108 if(c_associated(b, c_loc(a))) & 3109 stop 'b and a do not point to same target' 3110end subroutine association_test 3111@end smallexample 3112 3113@item @emph{See also}: 3114@ref{C_LOC}, @gol 3115@ref{C_FUNLOC} 3116@end table 3117 3118 3119@node C_F_POINTER 3120@section @code{C_F_POINTER} --- Convert C into Fortran pointer 3121@fnindex C_F_POINTER 3122@cindex pointer, convert C to Fortran 3123 3124@table @asis 3125@item @emph{Description}: 3126@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer 3127@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape. 3128 3129@item @emph{Standard}: 3130Fortran 2003 and later 3131 3132@item @emph{Class}: 3133Subroutine 3134 3135@item @emph{Syntax}: 3136@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])} 3137 3138@item @emph{Arguments}: 3139@multitable @columnfractions .15 .70 3140@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is 3141@code{INTENT(IN)}. 3142@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is 3143@code{INTENT(OUT)}. 3144@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER} 3145with @code{INTENT(IN)}. It shall be present 3146if and only if @var{fptr} is an array. The size 3147must be equal to the rank of @var{fptr}. 3148@end multitable 3149 3150@item @emph{Example}: 3151@smallexample 3152program main 3153 use iso_c_binding 3154 implicit none 3155 interface 3156 subroutine my_routine(p) bind(c,name='myC_func') 3157 import :: c_ptr 3158 type(c_ptr), intent(out) :: p 3159 end subroutine 3160 end interface 3161 type(c_ptr) :: cptr 3162 real,pointer :: a(:) 3163 call my_routine(cptr) 3164 call c_f_pointer(cptr, a, [12]) 3165end program main 3166@end smallexample 3167 3168@item @emph{See also}: 3169@ref{C_LOC}, @gol 3170@ref{C_F_PROCPOINTER} 3171@end table 3172 3173 3174@node C_F_PROCPOINTER 3175@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer 3176@fnindex C_F_PROCPOINTER 3177@cindex pointer, C address of pointers 3178 3179@table @asis 3180@item @emph{Description}: 3181@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer 3182@var{CPTR} to the Fortran procedure pointer @var{FPTR}. 3183 3184@item @emph{Standard}: 3185Fortran 2003 and later 3186 3187@item @emph{Class}: 3188Subroutine 3189 3190@item @emph{Syntax}: 3191@code{CALL C_F_PROCPOINTER(cptr, fptr)} 3192 3193@item @emph{Arguments}: 3194@multitable @columnfractions .15 .70 3195@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is 3196@code{INTENT(IN)}. 3197@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is 3198@code{INTENT(OUT)}. 3199@end multitable 3200 3201@item @emph{Example}: 3202@smallexample 3203program main 3204 use iso_c_binding 3205 implicit none 3206 abstract interface 3207 function func(a) 3208 import :: c_float 3209 real(c_float), intent(in) :: a 3210 real(c_float) :: func 3211 end function 3212 end interface 3213 interface 3214 function getIterFunc() bind(c,name="getIterFunc") 3215 import :: c_funptr 3216 type(c_funptr) :: getIterFunc 3217 end function 3218 end interface 3219 type(c_funptr) :: cfunptr 3220 procedure(func), pointer :: myFunc 3221 cfunptr = getIterFunc() 3222 call c_f_procpointer(cfunptr, myFunc) 3223end program main 3224@end smallexample 3225 3226@item @emph{See also}: 3227@ref{C_LOC}, @gol 3228@ref{C_F_POINTER} 3229@end table 3230 3231 3232@node C_FUNLOC 3233@section @code{C_FUNLOC} --- Obtain the C address of a procedure 3234@fnindex C_FUNLOC 3235@cindex pointer, C address of procedures 3236 3237@table @asis 3238@item @emph{Description}: 3239@code{C_FUNLOC(x)} determines the C address of the argument. 3240 3241@item @emph{Standard}: 3242Fortran 2003 and later 3243 3244@item @emph{Class}: 3245Inquiry function 3246 3247@item @emph{Syntax}: 3248@code{RESULT = C_FUNLOC(x)} 3249 3250@item @emph{Arguments}: 3251@multitable @columnfractions .15 .70 3252@item @var{x} @tab Interoperable function or pointer to such function. 3253@end multitable 3254 3255@item @emph{Return value}: 3256The return value is of type @code{C_FUNPTR} and contains the C address 3257of the argument. 3258 3259@item @emph{Example}: 3260@smallexample 3261module x 3262 use iso_c_binding 3263 implicit none 3264contains 3265 subroutine sub(a) bind(c) 3266 real(c_float) :: a 3267 a = sqrt(a)+5.0 3268 end subroutine sub 3269end module x 3270program main 3271 use iso_c_binding 3272 use x 3273 implicit none 3274 interface 3275 subroutine my_routine(p) bind(c,name='myC_func') 3276 import :: c_funptr 3277 type(c_funptr), intent(in) :: p 3278 end subroutine 3279 end interface 3280 call my_routine(c_funloc(sub)) 3281end program main 3282@end smallexample 3283 3284@item @emph{See also}: 3285@ref{C_ASSOCIATED}, @gol 3286@ref{C_LOC}, @gol 3287@ref{C_F_POINTER}, @gol 3288@ref{C_F_PROCPOINTER} 3289@end table 3290 3291 3292@node C_LOC 3293@section @code{C_LOC} --- Obtain the C address of an object 3294@fnindex C_LOC 3295@cindex procedure pointer, convert C to Fortran 3296 3297@table @asis 3298@item @emph{Description}: 3299@code{C_LOC(X)} determines the C address of the argument. 3300 3301@item @emph{Standard}: 3302Fortran 2003 and later 3303 3304@item @emph{Class}: 3305Inquiry function 3306 3307@item @emph{Syntax}: 3308@code{RESULT = C_LOC(X)} 3309 3310@item @emph{Arguments}: 3311@multitable @columnfractions .10 .75 3312@item @var{X} @tab Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters. 3313 3314@end multitable 3315 3316@item @emph{Return value}: 3317The return value is of type @code{C_PTR} and contains the C address 3318of the argument. 3319 3320@item @emph{Example}: 3321@smallexample 3322subroutine association_test(a,b) 3323 use iso_c_binding, only: c_associated, c_loc, c_ptr 3324 implicit none 3325 real, pointer :: a 3326 type(c_ptr) :: b 3327 if(c_associated(b, c_loc(a))) & 3328 stop 'b and a do not point to same target' 3329end subroutine association_test 3330@end smallexample 3331 3332@item @emph{See also}: 3333@ref{C_ASSOCIATED}, @gol 3334@ref{C_FUNLOC}, @gol 3335@ref{C_F_POINTER}, @gol 3336@ref{C_F_PROCPOINTER} 3337@end table 3338 3339 3340@node C_SIZEOF 3341@section @code{C_SIZEOF} --- Size in bytes of an expression 3342@fnindex C_SIZEOF 3343@cindex expression size 3344@cindex size of an expression 3345 3346@table @asis 3347@item @emph{Description}: 3348@code{C_SIZEOF(X)} calculates the number of bytes of storage the 3349expression @code{X} occupies. 3350 3351@item @emph{Standard}: 3352Fortran 2008 3353 3354@item @emph{Class}: 3355Inquiry function of the module @code{ISO_C_BINDING} 3356 3357@item @emph{Syntax}: 3358@code{N = C_SIZEOF(X)} 3359 3360@item @emph{Arguments}: 3361@multitable @columnfractions .15 .70 3362@item @var{X} @tab The argument shall be an interoperable data entity. 3363@end multitable 3364 3365@item @emph{Return value}: 3366The return value is of type integer and of the system-dependent kind 3367@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the 3368number of bytes occupied by the argument. If the argument has the 3369@code{POINTER} attribute, the number of bytes of the storage area pointed 3370to is returned. If the argument is of a derived type with @code{POINTER} 3371or @code{ALLOCATABLE} components, the return value does not account for 3372the sizes of the data pointed to by these components. 3373 3374@item @emph{Example}: 3375@smallexample 3376 use iso_c_binding 3377 integer(c_int) :: i 3378 real(c_float) :: r, s(5) 3379 print *, (c_sizeof(s)/c_sizeof(r) == 5) 3380 end 3381@end smallexample 3382The example will print @code{T} unless you are using a platform 3383where default @code{REAL} variables are unusually padded. 3384 3385@item @emph{See also}: 3386@ref{SIZEOF}, @gol 3387@ref{STORAGE_SIZE} 3388@end table 3389 3390 3391@node CEILING 3392@section @code{CEILING} --- Integer ceiling function 3393@fnindex CEILING 3394@cindex ceiling 3395@cindex rounding, ceiling 3396 3397@table @asis 3398@item @emph{Description}: 3399@code{CEILING(A)} returns the least integer greater than or equal to @var{A}. 3400 3401@item @emph{Standard}: 3402Fortran 95 and later 3403 3404@item @emph{Class}: 3405Elemental function 3406 3407@item @emph{Syntax}: 3408@code{RESULT = CEILING(A [, KIND])} 3409 3410@item @emph{Arguments}: 3411@multitable @columnfractions .15 .70 3412@item @var{A} @tab The type shall be @code{REAL}. 3413@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3414expression indicating the kind parameter of the result. 3415@end multitable 3416 3417@item @emph{Return value}: 3418The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 3419and a default-kind @code{INTEGER} otherwise. 3420 3421@item @emph{Example}: 3422@smallexample 3423program test_ceiling 3424 real :: x = 63.29 3425 real :: y = -63.59 3426 print *, ceiling(x) ! returns 64 3427 print *, ceiling(y) ! returns -63 3428end program test_ceiling 3429@end smallexample 3430 3431@item @emph{See also}: 3432@ref{FLOOR}, @gol 3433@ref{NINT} 3434@end table 3435 3436 3437 3438@node CHAR 3439@section @code{CHAR} --- Character conversion function 3440@fnindex CHAR 3441@cindex conversion, to character 3442 3443@table @asis 3444@item @emph{Description}: 3445@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}. 3446 3447@item @emph{Standard}: 3448Fortran 77 and later 3449 3450@item @emph{Class}: 3451Elemental function 3452 3453@item @emph{Syntax}: 3454@code{RESULT = CHAR(I [, KIND])} 3455 3456@item @emph{Arguments}: 3457@multitable @columnfractions .15 .70 3458@item @var{I} @tab The type shall be @code{INTEGER}. 3459@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3460expression indicating the kind parameter of the result. 3461@end multitable 3462 3463@item @emph{Return value}: 3464The return value is of type @code{CHARACTER(1)} 3465 3466@item @emph{Example}: 3467@smallexample 3468program test_char 3469 integer :: i = 74 3470 character(1) :: c 3471 c = char(i) 3472 print *, i, c ! returns 'J' 3473end program test_char 3474@end smallexample 3475 3476@item @emph{Specific names}: 3477@multitable @columnfractions .18 .18 .24 .25 3478@item Name @tab Argument @tab Return type @tab Standard 3479@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later 3480@end multitable 3481 3482@item @emph{Note}: 3483See @ref{ICHAR} for a discussion of converting between numerical values 3484and formatted string representations. 3485 3486@item @emph{See also}: 3487@ref{ACHAR}, @gol 3488@ref{IACHAR}, @gol 3489@ref{ICHAR} 3490 3491@end table 3492 3493 3494 3495@node CHDIR 3496@section @code{CHDIR} --- Change working directory 3497@fnindex CHDIR 3498@cindex system, working directory 3499 3500@table @asis 3501@item @emph{Description}: 3502Change current working directory to a specified path. 3503 3504This intrinsic is provided in both subroutine and function forms; however, 3505only one form can be used in any given program unit. 3506 3507@item @emph{Standard}: 3508GNU extension 3509 3510@item @emph{Class}: 3511Subroutine, function 3512 3513@item @emph{Syntax}: 3514@multitable @columnfractions .80 3515@item @code{CALL CHDIR(NAME [, STATUS])} 3516@item @code{STATUS = CHDIR(NAME)} 3517@end multitable 3518 3519@item @emph{Arguments}: 3520@multitable @columnfractions .15 .70 3521@item @var{NAME} @tab The type shall be @code{CHARACTER} of default 3522kind and shall specify a valid path within the file system. 3523@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default 3524kind. Returns 0 on success, and a system specific and nonzero error code 3525otherwise. 3526@end multitable 3527 3528@item @emph{Example}: 3529@smallexample 3530PROGRAM test_chdir 3531 CHARACTER(len=255) :: path 3532 CALL getcwd(path) 3533 WRITE(*,*) TRIM(path) 3534 CALL chdir("/tmp") 3535 CALL getcwd(path) 3536 WRITE(*,*) TRIM(path) 3537END PROGRAM 3538@end smallexample 3539 3540@item @emph{See also}: 3541@ref{GETCWD} 3542@end table 3543 3544 3545 3546@node CHMOD 3547@section @code{CHMOD} --- Change access permissions of files 3548@fnindex CHMOD 3549@cindex file system, change access mode 3550 3551@table @asis 3552@item @emph{Description}: 3553@code{CHMOD} changes the permissions of a file. 3554 3555This intrinsic is provided in both subroutine and function forms; however, 3556only one form can be used in any given program unit. 3557 3558@item @emph{Standard}: 3559GNU extension 3560 3561@item @emph{Class}: 3562Subroutine, function 3563 3564@item @emph{Syntax}: 3565@multitable @columnfractions .80 3566@item @code{CALL CHMOD(NAME, MODE[, STATUS])} 3567@item @code{STATUS = CHMOD(NAME, MODE)} 3568@end multitable 3569 3570@item @emph{Arguments}: 3571@multitable @columnfractions .15 .70 3572 3573@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 3574file name. Trailing blanks are ignored unless the character 3575@code{achar(0)} is present, then all characters up to and excluding 3576@code{achar(0)} are used as the file name. 3577 3578@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the 3579file permission. @var{MODE} uses the same syntax as the @code{chmod} utility 3580as defined by the POSIX standard. The argument shall either be a string of 3581a nonnegative octal number or a symbolic mode. 3582 3583@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is 3584@code{0} on success and nonzero otherwise. 3585@end multitable 3586 3587@item @emph{Return value}: 3588In either syntax, @var{STATUS} is set to @code{0} on success and nonzero 3589otherwise. 3590 3591@item @emph{Example}: 3592@code{CHMOD} as subroutine 3593@smallexample 3594program chmod_test 3595 implicit none 3596 integer :: status 3597 call chmod('test.dat','u+x',status) 3598 print *, 'Status: ', status 3599end program chmod_test 3600@end smallexample 3601@code{CHMOD} as function: 3602@smallexample 3603program chmod_test 3604 implicit none 3605 integer :: status 3606 status = chmod('test.dat','u+x') 3607 print *, 'Status: ', status 3608end program chmod_test 3609@end smallexample 3610 3611@end table 3612 3613 3614 3615@node CMPLX 3616@section @code{CMPLX} --- Complex conversion function 3617@fnindex CMPLX 3618@cindex complex numbers, conversion to 3619@cindex conversion, to complex 3620 3621@table @asis 3622@item @emph{Description}: 3623@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to 3624the real component. If @var{Y} is present it is converted to the imaginary 3625component. If @var{Y} is not present then the imaginary component is set to 36260.0. If @var{X} is complex then @var{Y} must not be present. 3627 3628@item @emph{Standard}: 3629Fortran 77 and later 3630 3631@item @emph{Class}: 3632Elemental function 3633 3634@item @emph{Syntax}: 3635@code{RESULT = CMPLX(X [, Y [, KIND]])} 3636 3637@item @emph{Arguments}: 3638@multitable @columnfractions .15 .70 3639@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 3640or @code{COMPLEX}. 3641@item @var{Y} @tab (Optional; only allowed if @var{X} is not 3642@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. 3643@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3644expression indicating the kind parameter of the result. 3645@end multitable 3646 3647@item @emph{Return value}: 3648The return value is of @code{COMPLEX} type, with a kind equal to 3649@var{KIND} if it is specified. If @var{KIND} is not specified, the 3650result is of the default @code{COMPLEX} kind, regardless of the kinds of 3651@var{X} and @var{Y}. 3652 3653@item @emph{Example}: 3654@smallexample 3655program test_cmplx 3656 integer :: i = 42 3657 real :: x = 3.14 3658 complex :: z 3659 z = cmplx(i, x) 3660 print *, z, cmplx(x) 3661end program test_cmplx 3662@end smallexample 3663 3664@item @emph{See also}: 3665@ref{COMPLEX} 3666@end table 3667 3668 3669 3670@node CO_BROADCAST 3671@section @code{CO_BROADCAST} --- Copy a value to all images the current set of images 3672@fnindex CO_BROADCAST 3673@cindex Collectives, value broadcasting 3674 3675@table @asis 3676@item @emph{Description}: 3677@code{CO_BROADCAST} copies the value of argument @var{A} on the image with 3678image index @code{SOURCE_IMAGE} to all images in the current team. @var{A} 3679becomes defined as if by intrinsic assignment. If the execution was 3680successful and @var{STAT} is present, it is assigned the value zero. If the 3681execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3682@var{ERRMSG} gets assigned a value describing the occurred error. 3683 3684@item @emph{Standard}: 3685Technical Specification (TS) 18508 or later 3686 3687@item @emph{Class}: 3688Collective subroutine 3689 3690@item @emph{Syntax}: 3691@code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])} 3692 3693@item @emph{Arguments}: 3694@multitable @columnfractions .20 .65 3695@item @var{A} @tab INTENT(INOUT) argument; shall have the same 3696dynamic type and type parameters on all images of the current team. If it 3697is an array, it shall have the same shape on all images. 3698@item @var{SOURCE_IMAGE} @tab a scalar integer expression. 3699It shall have the same the same value on all images and refer to an 3700image of the current team. 3701@item @var{STAT} @tab (optional) a scalar integer variable 3702@item @var{ERRMSG} @tab (optional) a scalar character variable 3703@end multitable 3704 3705@item @emph{Example}: 3706@smallexample 3707program test 3708 integer :: val(3) 3709 if (this_image() == 1) then 3710 val = [1, 5, 3] 3711 end if 3712 call co_broadcast (val, source_image=1) 3713 print *, this_image, ":", val 3714end program test 3715@end smallexample 3716 3717@item @emph{See also}: 3718@ref{CO_MAX}, @gol 3719@ref{CO_MIN}, @gol 3720@ref{CO_SUM}, @gol 3721@ref{CO_REDUCE} 3722@end table 3723 3724 3725 3726@node CO_MAX 3727@section @code{CO_MAX} --- Maximal value on the current set of images 3728@fnindex CO_MAX 3729@cindex Collectives, maximal value 3730 3731@table @asis 3732@item @emph{Description}: 3733@code{CO_MAX} determines element-wise the maximal value of @var{A} on all 3734images of the current team. If @var{RESULT_IMAGE} is present, the maximum 3735values are returned in @var{A} on the specified image only and the value 3736of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3737not present, the value is returned on all images. If the execution was 3738successful and @var{STAT} is present, it is assigned the value zero. If the 3739execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3740@var{ERRMSG} gets assigned a value describing the occurred error. 3741 3742@item @emph{Standard}: 3743Technical Specification (TS) 18508 or later 3744 3745@item @emph{Class}: 3746Collective subroutine 3747 3748@item @emph{Syntax}: 3749@code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])} 3750 3751@item @emph{Arguments}: 3752@multitable @columnfractions .20 .65 3753@item @var{A} @tab shall be an integer, real or character variable, 3754which has the same type and type parameters on all images of the team. 3755@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3756present, it shall have the same the same value on all images and refer to an 3757image of the current team. 3758@item @var{STAT} @tab (optional) a scalar integer variable 3759@item @var{ERRMSG} @tab (optional) a scalar character variable 3760@end multitable 3761 3762@item @emph{Example}: 3763@smallexample 3764program test 3765 integer :: val 3766 val = this_image () 3767 call co_max (val, result_image=1) 3768 if (this_image() == 1) then 3769 write(*,*) "Maximal value", val ! prints num_images() 3770 end if 3771end program test 3772@end smallexample 3773 3774@item @emph{See also}: 3775@ref{CO_MIN}, @gol 3776@ref{CO_SUM}, @gol 3777@ref{CO_REDUCE}, @gol 3778@ref{CO_BROADCAST} 3779@end table 3780 3781 3782 3783@node CO_MIN 3784@section @code{CO_MIN} --- Minimal value on the current set of images 3785@fnindex CO_MIN 3786@cindex Collectives, minimal value 3787 3788@table @asis 3789@item @emph{Description}: 3790@code{CO_MIN} determines element-wise the minimal value of @var{A} on all 3791images of the current team. If @var{RESULT_IMAGE} is present, the minimal 3792values are returned in @var{A} on the specified image only and the value 3793of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3794not present, the value is returned on all images. If the execution was 3795successful and @var{STAT} is present, it is assigned the value zero. If the 3796execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3797@var{ERRMSG} gets assigned a value describing the occurred error. 3798 3799@item @emph{Standard}: 3800Technical Specification (TS) 18508 or later 3801 3802@item @emph{Class}: 3803Collective subroutine 3804 3805@item @emph{Syntax}: 3806@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3807 3808@item @emph{Arguments}: 3809@multitable @columnfractions .20 .65 3810@item @var{A} @tab shall be an integer, real or character variable, 3811which has the same type and type parameters on all images of the team. 3812@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3813present, it shall have the same the same value on all images and refer to an 3814image of the current team. 3815@item @var{STAT} @tab (optional) a scalar integer variable 3816@item @var{ERRMSG} @tab (optional) a scalar character variable 3817@end multitable 3818 3819@item @emph{Example}: 3820@smallexample 3821program test 3822 integer :: val 3823 val = this_image () 3824 call co_min (val, result_image=1) 3825 if (this_image() == 1) then 3826 write(*,*) "Minimal value", val ! prints 1 3827 end if 3828end program test 3829@end smallexample 3830 3831@item @emph{See also}: 3832@ref{CO_MAX}, @gol 3833@ref{CO_SUM}, @gol 3834@ref{CO_REDUCE}, @gol 3835@ref{CO_BROADCAST} 3836@end table 3837 3838 3839 3840@node CO_REDUCE 3841@section @code{CO_REDUCE} --- Reduction of values on the current set of images 3842@fnindex CO_REDUCE 3843@cindex Collectives, generic reduction 3844 3845@table @asis 3846@item @emph{Description}: 3847@code{CO_REDUCE} determines element-wise the reduction of the value of @var{A} 3848on all images of the current team. The pure function passed as @var{OPERATOR} 3849is used to pairwise reduce the values of @var{A} by passing either the value 3850of @var{A} of different images or the result values of such a reduction as 3851argument. If @var{A} is an array, the deduction is done element wise. If 3852@var{RESULT_IMAGE} is present, the result values are returned in @var{A} on 3853the specified image only and the value of @var{A} on the other images become 3854undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all 3855images. If the execution was successful and @var{STAT} is present, it is 3856assigned the value zero. If the execution failed, @var{STAT} gets assigned 3857a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing 3858the occurred error. 3859 3860@item @emph{Standard}: 3861Technical Specification (TS) 18508 or later 3862 3863@item @emph{Class}: 3864Collective subroutine 3865 3866@item @emph{Syntax}: 3867@code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])} 3868 3869@item @emph{Arguments}: 3870@multitable @columnfractions .20 .65 3871@item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be 3872nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, 3873it shall be associated. @var{A} shall have the same type and type parameters on 3874all images of the team; if it is an array, it shall have the same shape on all 3875images. 3876@item @var{OPERATOR} @tab pure function with two scalar nonallocatable 3877arguments, which shall be nonpolymorphic and have the same type and type 3878parameters as @var{A}. The function shall return a nonallocatable scalar of 3879the same type and type parameters as @var{A}. The function shall be the same on 3880all images and with regards to the arguments mathematically commutative and 3881associative. Note that @var{OPERATOR} may not be an elemental function, unless 3882it is an intrisic function. 3883@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3884present, it shall have the same the same value on all images and refer to an 3885image of the current team. 3886@item @var{STAT} @tab (optional) a scalar integer variable 3887@item @var{ERRMSG} @tab (optional) a scalar character variable 3888@end multitable 3889 3890@item @emph{Example}: 3891@smallexample 3892program test 3893 integer :: val 3894 val = this_image () 3895 call co_reduce (val, result_image=1, operator=myprod) 3896 if (this_image() == 1) then 3897 write(*,*) "Product value", val ! prints num_images() factorial 3898 end if 3899contains 3900 pure function myprod(a, b) 3901 integer, value :: a, b 3902 integer :: myprod 3903 myprod = a * b 3904 end function myprod 3905end program test 3906@end smallexample 3907 3908@item @emph{Note}: 3909While the rules permit in principle an intrinsic function, none of the 3910intrinsics in the standard fulfill the criteria of having a specific 3911function, which takes two arguments of the same type and returning that 3912type as result. 3913 3914@item @emph{See also}: 3915@ref{CO_MIN}, @gol 3916@ref{CO_MAX}, @gol 3917@ref{CO_SUM}, @gol 3918@ref{CO_BROADCAST} 3919@end table 3920 3921 3922 3923@node CO_SUM 3924@section @code{CO_SUM} --- Sum of values on the current set of images 3925@fnindex CO_SUM 3926@cindex Collectives, sum of values 3927 3928@table @asis 3929@item @emph{Description}: 3930@code{CO_SUM} sums up the values of each element of @var{A} on all 3931images of the current team. If @var{RESULT_IMAGE} is present, the summed-up 3932values are returned in @var{A} on the specified image only and the value 3933of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3934not present, the value is returned on all images. If the execution was 3935successful and @var{STAT} is present, it is assigned the value zero. If the 3936execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3937@var{ERRMSG} gets assigned a value describing the occurred error. 3938 3939@item @emph{Standard}: 3940Technical Specification (TS) 18508 or later 3941 3942@item @emph{Class}: 3943Collective subroutine 3944 3945@item @emph{Syntax}: 3946@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3947 3948@item @emph{Arguments}: 3949@multitable @columnfractions .20 .65 3950@item @var{A} @tab shall be an integer, real or complex variable, 3951which has the same type and type parameters on all images of the team. 3952@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3953present, it shall have the same the same value on all images and refer to an 3954image of the current team. 3955@item @var{STAT} @tab (optional) a scalar integer variable 3956@item @var{ERRMSG} @tab (optional) a scalar character variable 3957@end multitable 3958 3959@item @emph{Example}: 3960@smallexample 3961program test 3962 integer :: val 3963 val = this_image () 3964 call co_sum (val, result_image=1) 3965 if (this_image() == 1) then 3966 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, 3967 ! with n = num_images() 3968 end if 3969end program test 3970@end smallexample 3971 3972@item @emph{See also}: 3973@ref{CO_MAX}, @gol 3974@ref{CO_MIN}, @gol 3975@ref{CO_REDUCE}, @gol 3976@ref{CO_BROADCAST} 3977@end table 3978 3979 3980 3981@node COMMAND_ARGUMENT_COUNT 3982@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments 3983@fnindex COMMAND_ARGUMENT_COUNT 3984@cindex command-line arguments 3985@cindex command-line arguments, number of 3986@cindex arguments, to program 3987 3988@table @asis 3989@item @emph{Description}: 3990@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the 3991command line when the containing program was invoked. 3992 3993@item @emph{Standard}: 3994Fortran 2003 and later 3995 3996@item @emph{Class}: 3997Inquiry function 3998 3999@item @emph{Syntax}: 4000@code{RESULT = COMMAND_ARGUMENT_COUNT()} 4001 4002@item @emph{Arguments}: 4003@multitable @columnfractions .15 .70 4004@item None 4005@end multitable 4006 4007@item @emph{Return value}: 4008The return value is an @code{INTEGER} of default kind. 4009 4010@item @emph{Example}: 4011@smallexample 4012program test_command_argument_count 4013 integer :: count 4014 count = command_argument_count() 4015 print *, count 4016end program test_command_argument_count 4017@end smallexample 4018 4019@item @emph{See also}: 4020@ref{GET_COMMAND}, @gol 4021@ref{GET_COMMAND_ARGUMENT} 4022@end table 4023 4024 4025 4026@node COMPILER_OPTIONS 4027@section @code{COMPILER_OPTIONS} --- Options passed to the compiler 4028@fnindex COMPILER_OPTIONS 4029@cindex flags inquiry function 4030@cindex options inquiry function 4031@cindex compiler flags inquiry function 4032 4033@table @asis 4034@item @emph{Description}: 4035@code{COMPILER_OPTIONS} returns a string with the options used for 4036compiling. 4037 4038@item @emph{Standard}: 4039Fortran 2008 4040 4041@item @emph{Class}: 4042Inquiry function of the module @code{ISO_FORTRAN_ENV} 4043 4044@item @emph{Syntax}: 4045@code{STR = COMPILER_OPTIONS()} 4046 4047@item @emph{Arguments}: 4048None 4049 4050@item @emph{Return value}: 4051The return value is a default-kind string with system-dependent length. 4052It contains the compiler flags used to compile the file, which called 4053the @code{COMPILER_OPTIONS} intrinsic. 4054 4055@item @emph{Example}: 4056@smallexample 4057 use iso_fortran_env 4058 print '(4a)', 'This file was compiled by ', & 4059 compiler_version(), ' using the options ', & 4060 compiler_options() 4061 end 4062@end smallexample 4063 4064@item @emph{See also}: 4065@ref{COMPILER_VERSION}, @gol 4066@ref{ISO_FORTRAN_ENV} 4067@end table 4068 4069 4070 4071@node COMPILER_VERSION 4072@section @code{COMPILER_VERSION} --- Compiler version string 4073@fnindex COMPILER_VERSION 4074@cindex compiler, name and version 4075@cindex version of the compiler 4076 4077@table @asis 4078@item @emph{Description}: 4079@code{COMPILER_VERSION} returns a string with the name and the 4080version of the compiler. 4081 4082@item @emph{Standard}: 4083Fortran 2008 4084 4085@item @emph{Class}: 4086Inquiry function of the module @code{ISO_FORTRAN_ENV} 4087 4088@item @emph{Syntax}: 4089@code{STR = COMPILER_VERSION()} 4090 4091@item @emph{Arguments}: 4092None 4093 4094@item @emph{Return value}: 4095The return value is a default-kind string with system-dependent length. 4096It contains the name of the compiler and its version number. 4097 4098@item @emph{Example}: 4099@smallexample 4100 use iso_fortran_env 4101 print '(4a)', 'This file was compiled by ', & 4102 compiler_version(), ' using the options ', & 4103 compiler_options() 4104 end 4105@end smallexample 4106 4107@item @emph{See also}: 4108@ref{COMPILER_OPTIONS}, @gol 4109@ref{ISO_FORTRAN_ENV} 4110@end table 4111 4112 4113 4114@node COMPLEX 4115@section @code{COMPLEX} --- Complex conversion function 4116@fnindex COMPLEX 4117@cindex complex numbers, conversion to 4118@cindex conversion, to complex 4119 4120@table @asis 4121@item @emph{Description}: 4122@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted 4123to the real component and @var{Y} is converted to the imaginary 4124component. 4125 4126@item @emph{Standard}: 4127GNU extension 4128 4129@item @emph{Class}: 4130Elemental function 4131 4132@item @emph{Syntax}: 4133@code{RESULT = COMPLEX(X, Y)} 4134 4135@item @emph{Arguments}: 4136@multitable @columnfractions .15 .70 4137@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4138@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}. 4139@end multitable 4140 4141@item @emph{Return value}: 4142If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return 4143value is of default @code{COMPLEX} type. 4144 4145If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL} 4146type and one is of @code{INTEGER} type, then the return value is of 4147@code{COMPLEX} type with a kind equal to that of the @code{REAL} 4148argument with the highest precision. 4149 4150@item @emph{Example}: 4151@smallexample 4152program test_complex 4153 integer :: i = 42 4154 real :: x = 3.14 4155 print *, complex(i, x) 4156end program test_complex 4157@end smallexample 4158 4159@item @emph{See also}: 4160@ref{CMPLX} 4161@end table 4162 4163 4164 4165@node CONJG 4166@section @code{CONJG} --- Complex conjugate function 4167@fnindex CONJG 4168@fnindex DCONJG 4169@cindex complex conjugate 4170 4171@table @asis 4172@item @emph{Description}: 4173@code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)} 4174then the result is @code{(x, -y)} 4175 4176@item @emph{Standard}: 4177Fortran 77 and later, has an overload that is a GNU extension 4178 4179@item @emph{Class}: 4180Elemental function 4181 4182@item @emph{Syntax}: 4183@code{Z = CONJG(Z)} 4184 4185@item @emph{Arguments}: 4186@multitable @columnfractions .15 .70 4187@item @var{Z} @tab The type shall be @code{COMPLEX}. 4188@end multitable 4189 4190@item @emph{Return value}: 4191The return value is of type @code{COMPLEX}. 4192 4193@item @emph{Example}: 4194@smallexample 4195program test_conjg 4196 complex :: z = (2.0, 3.0) 4197 complex(8) :: dz = (2.71_8, -3.14_8) 4198 z= conjg(z) 4199 print *, z 4200 dz = dconjg(dz) 4201 print *, dz 4202end program test_conjg 4203@end smallexample 4204 4205@item @emph{Specific names}: 4206@multitable @columnfractions .20 .20 .20 .25 4207@item Name @tab Argument @tab Return type @tab Standard 4208@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension 4209@end multitable 4210@end table 4211 4212 4213 4214@node COS 4215@section @code{COS} --- Cosine function 4216@fnindex COS 4217@fnindex DCOS 4218@fnindex CCOS 4219@fnindex ZCOS 4220@fnindex CDCOS 4221@cindex trigonometric function, cosine 4222@cindex cosine 4223 4224@table @asis 4225@item @emph{Description}: 4226@code{COS(X)} computes the cosine of @var{X}. 4227 4228@item @emph{Standard}: 4229Fortran 77 and later, has overloads that are GNU extensions 4230 4231@item @emph{Class}: 4232Elemental function 4233 4234@item @emph{Syntax}: 4235@code{RESULT = COS(X)} 4236 4237@item @emph{Arguments}: 4238@multitable @columnfractions .15 .70 4239@item @var{X} @tab The type shall be @code{REAL} or 4240@code{COMPLEX}. 4241@end multitable 4242 4243@item @emph{Return value}: 4244The return value is of the same type and kind as @var{X}. The real part 4245of the result is in radians. If @var{X} is of the type @code{REAL}, 4246the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}. 4247 4248@item @emph{Example}: 4249@smallexample 4250program test_cos 4251 real :: x = 0.0 4252 x = cos(x) 4253end program test_cos 4254@end smallexample 4255 4256@item @emph{Specific names}: 4257@multitable @columnfractions .20 .20 .20 .25 4258@item Name @tab Argument @tab Return type @tab Standard 4259@item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4260@item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4261@item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 4262@item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4263@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4264@end multitable 4265 4266@item @emph{See also}: 4267Inverse function: @gol 4268@ref{ACOS} @gol 4269Degrees function: @gol 4270@ref{COSD} 4271@end table 4272 4273 4274 4275@node COSD 4276@section @code{COSD} --- Cosine function, degrees 4277@fnindex COSD 4278@fnindex DCOSD 4279@fnindex CCOSD 4280@fnindex ZCOSD 4281@fnindex CDCOSD 4282@cindex trigonometric function, cosine, degrees 4283@cindex cosine, degrees 4284 4285@table @asis 4286@item @emph{Description}: 4287@code{COSD(X)} computes the cosine of @var{X} in degrees. 4288 4289This function is for compatibility only and should be avoided in favor of 4290standard constructs wherever possible. 4291 4292@item @emph{Standard}: 4293GNU extension, enabled with @option{-fdec-math}. 4294 4295@item @emph{Class}: 4296Elemental function 4297 4298@item @emph{Syntax}: 4299@code{RESULT = COSD(X)} 4300 4301@item @emph{Arguments}: 4302@multitable @columnfractions .15 .70 4303@item @var{X} @tab The type shall be @code{REAL} or 4304@code{COMPLEX}. 4305@end multitable 4306 4307@item @emph{Return value}: 4308The return value is of the same type and kind as @var{X}. The real part 4309of the result is in degrees. If @var{X} is of the type @code{REAL}, 4310the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}. 4311 4312@item @emph{Example}: 4313@smallexample 4314program test_cosd 4315 real :: x = 0.0 4316 x = cosd(x) 4317end program test_cosd 4318@end smallexample 4319 4320@item @emph{Specific names}: 4321@multitable @columnfractions .20 .20 .20 .25 4322@item Name @tab Argument @tab Return type @tab Standard 4323@item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4324@item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4325@item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension 4326@item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4327@item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4328@end multitable 4329 4330@item @emph{See also}: 4331Inverse function: @gol 4332@ref{ACOSD} @gol 4333Radians function: @gol 4334@ref{COS} 4335@end table 4336 4337 4338 4339@node COSH 4340@section @code{COSH} --- Hyperbolic cosine function 4341@fnindex COSH 4342@fnindex DCOSH 4343@cindex hyperbolic cosine 4344@cindex hyperbolic function, cosine 4345@cindex cosine, hyperbolic 4346 4347@table @asis 4348@item @emph{Description}: 4349@code{COSH(X)} computes the hyperbolic cosine of @var{X}. 4350 4351@item @emph{Standard}: 4352Fortran 77 and later, for a complex argument Fortran 2008 or later 4353 4354@item @emph{Class}: 4355Elemental function 4356 4357@item @emph{Syntax}: 4358@code{X = COSH(X)} 4359 4360@item @emph{Arguments}: 4361@multitable @columnfractions .15 .70 4362@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4363@end multitable 4364 4365@item @emph{Return value}: 4366The return value has same type and kind as @var{X}. If @var{X} is 4367complex, the imaginary part of the result is in radians. If @var{X} 4368is @code{REAL}, the return value has a lower bound of one, 4369@math{\cosh (x) \geq 1}. 4370 4371@item @emph{Example}: 4372@smallexample 4373program test_cosh 4374 real(8) :: x = 1.0_8 4375 x = cosh(x) 4376end program test_cosh 4377@end smallexample 4378 4379@item @emph{Specific names}: 4380@multitable @columnfractions .20 .20 .20 .25 4381@item Name @tab Argument @tab Return type @tab Standard 4382@item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4383@item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4384@end multitable 4385 4386@item @emph{See also}: 4387Inverse function: @gol 4388@ref{ACOSH} 4389@end table 4390 4391 4392 4393@node COTAN 4394@section @code{COTAN} --- Cotangent function 4395@fnindex COTAN 4396@fnindex DCOTAN 4397@cindex trigonometric function, cotangent 4398@cindex cotangent 4399 4400@table @asis 4401@item @emph{Description}: 4402@code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)} 4403divided by @code{SIN(x)}, or @code{1 / TAN(x)}. 4404 4405This function is for compatibility only and should be avoided in favor of 4406standard constructs wherever possible. 4407 4408@item @emph{Standard}: 4409GNU extension, enabled with @option{-fdec-math}. 4410 4411@item @emph{Class}: 4412Elemental function 4413 4414@item @emph{Syntax}: 4415@code{RESULT = COTAN(X)} 4416 4417@item @emph{Arguments}: 4418@multitable @columnfractions .15 .70 4419@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4420@end multitable 4421 4422@item @emph{Return value}: 4423The return value has same type and kind as @var{X}, and its value is in radians. 4424 4425@item @emph{Example}: 4426@smallexample 4427program test_cotan 4428 real(8) :: x = 0.165_8 4429 x = cotan(x) 4430end program test_cotan 4431@end smallexample 4432 4433@item @emph{Specific names}: 4434@multitable @columnfractions .20 .20 .20 .25 4435@item Name @tab Argument @tab Return type @tab Standard 4436@item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4437@item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4438@end multitable 4439 4440@item @emph{See also}: 4441Converse function: @gol 4442@ref{TAN} @gol 4443Degrees function: @gol 4444@ref{COTAND} 4445@end table 4446 4447 4448 4449@node COTAND 4450@section @code{COTAND} --- Cotangent function, degrees 4451@fnindex COTAND 4452@fnindex DCOTAND 4453@cindex trigonometric function, cotangent, degrees 4454@cindex cotangent, degrees 4455 4456@table @asis 4457@item @emph{Description}: 4458@code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to 4459@code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}. 4460 4461@item @emph{Standard}: 4462GNU extension, enabled with @option{-fdec-math}. 4463 4464This function is for compatibility only and should be avoided in favor of 4465standard constructs wherever possible. 4466 4467@item @emph{Class}: 4468Elemental function 4469 4470@item @emph{Syntax}: 4471@code{RESULT = COTAND(X)} 4472 4473@item @emph{Arguments}: 4474@multitable @columnfractions .15 .70 4475@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4476@end multitable 4477 4478@item @emph{Return value}: 4479The return value has same type and kind as @var{X}, and its value is in degrees. 4480 4481@item @emph{Example}: 4482@smallexample 4483program test_cotand 4484 real(8) :: x = 0.165_8 4485 x = cotand(x) 4486end program test_cotand 4487@end smallexample 4488 4489@item @emph{Specific names}: 4490@multitable @columnfractions .20 .20 .20 .25 4491@item Name @tab Argument @tab Return type @tab Standard 4492@item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 4493@item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4494@end multitable 4495 4496@item @emph{See also}: 4497Converse function: @gol 4498@ref{TAND} @gol 4499Radians function: @gol 4500@ref{COTAN} 4501@end table 4502 4503 4504 4505@node COUNT 4506@section @code{COUNT} --- Count function 4507@fnindex COUNT 4508@cindex array, conditionally count elements 4509@cindex array, element counting 4510@cindex array, number of elements 4511 4512@table @asis 4513@item @emph{Description}: 4514 4515Counts the number of @code{.TRUE.} elements in a logical @var{MASK}, 4516or, if the @var{DIM} argument is supplied, counts the number of 4517elements along each row of the array in the @var{DIM} direction. 4518If the array has zero size, or all of the elements of @var{MASK} are 4519@code{.FALSE.}, then the result is @code{0}. 4520 4521@item @emph{Standard}: 4522Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 4523 4524@item @emph{Class}: 4525Transformational function 4526 4527@item @emph{Syntax}: 4528@code{RESULT = COUNT(MASK [, DIM, KIND])} 4529 4530@item @emph{Arguments}: 4531@multitable @columnfractions .15 .70 4532@item @var{MASK} @tab The type shall be @code{LOGICAL}. 4533@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}. 4534@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 4535expression indicating the kind parameter of the result. 4536@end multitable 4537 4538@item @emph{Return value}: 4539The return value is of type @code{INTEGER} and of kind @var{KIND}. If 4540@var{KIND} is absent, the return value is of default integer kind. 4541If @var{DIM} is present, the result is an array with a rank one less 4542than the rank of @var{ARRAY}, and a size corresponding to the shape 4543of @var{ARRAY} with the @var{DIM} dimension removed. 4544 4545@item @emph{Example}: 4546@smallexample 4547program test_count 4548 integer, dimension(2,3) :: a, b 4549 logical, dimension(2,3) :: mask 4550 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) 4551 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /)) 4552 print '(3i3)', a(1,:) 4553 print '(3i3)', a(2,:) 4554 print * 4555 print '(3i3)', b(1,:) 4556 print '(3i3)', b(2,:) 4557 print * 4558 mask = a.ne.b 4559 print '(3l3)', mask(1,:) 4560 print '(3l3)', mask(2,:) 4561 print * 4562 print '(3i3)', count(mask) 4563 print * 4564 print '(3i3)', count(mask, 1) 4565 print * 4566 print '(3i3)', count(mask, 2) 4567end program test_count 4568@end smallexample 4569@end table 4570 4571 4572 4573@node CPU_TIME 4574@section @code{CPU_TIME} --- CPU elapsed time in seconds 4575@fnindex CPU_TIME 4576@cindex time, elapsed 4577 4578@table @asis 4579@item @emph{Description}: 4580Returns a @code{REAL} value representing the elapsed CPU time in 4581seconds. This is useful for testing segments of code to determine 4582execution time. 4583 4584If a time source is available, time will be reported with microsecond 4585resolution. If no time source is available, @var{TIME} is set to 4586@code{-1.0}. 4587 4588Note that @var{TIME} may contain a, system dependent, arbitrary offset 4589and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute 4590value is meaningless, only differences between subsequent calls to 4591this subroutine, as shown in the example below, should be used. 4592 4593 4594@item @emph{Standard}: 4595Fortran 95 and later 4596 4597@item @emph{Class}: 4598Subroutine 4599 4600@item @emph{Syntax}: 4601@code{CALL CPU_TIME(TIME)} 4602 4603@item @emph{Arguments}: 4604@multitable @columnfractions .15 .70 4605@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}. 4606@end multitable 4607 4608@item @emph{Return value}: 4609None 4610 4611@item @emph{Example}: 4612@smallexample 4613program test_cpu_time 4614 real :: start, finish 4615 call cpu_time(start) 4616 ! put code to test here 4617 call cpu_time(finish) 4618 print '("Time = ",f6.3," seconds.")',finish-start 4619end program test_cpu_time 4620@end smallexample 4621 4622@item @emph{See also}: 4623@ref{SYSTEM_CLOCK}, @gol 4624@ref{DATE_AND_TIME} 4625@end table 4626 4627 4628 4629@node CSHIFT 4630@section @code{CSHIFT} --- Circular shift elements of an array 4631@fnindex CSHIFT 4632@cindex array, shift circularly 4633@cindex array, permutation 4634@cindex array, rotate 4635 4636@table @asis 4637@item @emph{Description}: 4638@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of 4639@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is 4640taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the 4641range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. 4642If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted 4643by @var{SHIFT} places. If rank is greater than one, then all complete rank one 4644sections of @var{ARRAY} along the given dimension are shifted. Elements 4645shifted out one end of each rank one section are shifted back in the other end. 4646 4647@item @emph{Standard}: 4648Fortran 90 and later 4649 4650@item @emph{Class}: 4651Transformational function 4652 4653@item @emph{Syntax}: 4654@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])} 4655 4656@item @emph{Arguments}: 4657@multitable @columnfractions .15 .70 4658@item @var{ARRAY} @tab Shall be an array of any type. 4659@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 4660@item @var{DIM} @tab The type shall be @code{INTEGER}. 4661@end multitable 4662 4663@item @emph{Return value}: 4664Returns an array of same type and rank as the @var{ARRAY} argument. 4665 4666@item @emph{Example}: 4667@smallexample 4668program test_cshift 4669 integer, dimension(3,3) :: a 4670 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 4671 print '(3i3)', a(1,:) 4672 print '(3i3)', a(2,:) 4673 print '(3i3)', a(3,:) 4674 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2) 4675 print * 4676 print '(3i3)', a(1,:) 4677 print '(3i3)', a(2,:) 4678 print '(3i3)', a(3,:) 4679end program test_cshift 4680@end smallexample 4681@end table 4682 4683 4684 4685@node CTIME 4686@section @code{CTIME} --- Convert a time into a string 4687@fnindex CTIME 4688@cindex time, conversion to string 4689@cindex conversion, to string 4690 4691@table @asis 4692@item @emph{Description}: 4693@code{CTIME} converts a system time value, such as returned by 4694@ref{TIME8}, to a string. The output will be of the form @samp{Sat 4695Aug 19 18:13:14 1995}. 4696 4697This intrinsic is provided in both subroutine and function forms; however, 4698only one form can be used in any given program unit. 4699 4700@item @emph{Standard}: 4701GNU extension 4702 4703@item @emph{Class}: 4704Subroutine, function 4705 4706@item @emph{Syntax}: 4707@multitable @columnfractions .80 4708@item @code{CALL CTIME(TIME, RESULT)}. 4709@item @code{RESULT = CTIME(TIME)}. 4710@end multitable 4711 4712@item @emph{Arguments}: 4713@multitable @columnfractions .15 .70 4714@item @var{TIME} @tab The type shall be of type @code{INTEGER}. 4715@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and 4716of default kind. It is an @code{INTENT(OUT)} argument. If the length 4717of this variable is too short for the time and date string to fit 4718completely, it will be blank on procedure return. 4719@end multitable 4720 4721@item @emph{Return value}: 4722The converted date and time as a string. 4723 4724@item @emph{Example}: 4725@smallexample 4726program test_ctime 4727 integer(8) :: i 4728 character(len=30) :: date 4729 i = time8() 4730 4731 ! Do something, main part of the program 4732 4733 call ctime(i,date) 4734 print *, 'Program was started on ', date 4735end program test_ctime 4736@end smallexample 4737 4738@item @emph{See Also}: 4739@ref{DATE_AND_TIME}, @gol 4740@ref{GMTIME}, @gol 4741@ref{LTIME}, @gol 4742@ref{TIME}, @gol 4743@ref{TIME8} 4744@end table 4745 4746 4747 4748@node DATE_AND_TIME 4749@section @code{DATE_AND_TIME} --- Date and time subroutine 4750@fnindex DATE_AND_TIME 4751@cindex date, current 4752@cindex current date 4753@cindex time, current 4754@cindex current time 4755 4756@table @asis 4757@item @emph{Description}: 4758@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and 4759time information from the real-time system clock. @var{DATE} is 4760@code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and 4761has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, 4762representing the difference with respect to Coordinated Universal Time (UTC). 4763Unavailable time and date parameters return blanks. 4764 4765@var{VALUES} is @code{INTENT(OUT)} and provides the following: 4766 4767@multitable @columnfractions .15 .30 .40 4768@item @tab @code{VALUE(1)}: @tab The year 4769@item @tab @code{VALUE(2)}: @tab The month 4770@item @tab @code{VALUE(3)}: @tab The day of the month 4771@item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes 4772@item @tab @code{VALUE(5)}: @tab The hour of the day 4773@item @tab @code{VALUE(6)}: @tab The minutes of the hour 4774@item @tab @code{VALUE(7)}: @tab The seconds of the minute 4775@item @tab @code{VALUE(8)}: @tab The milliseconds of the second 4776@end multitable 4777 4778@item @emph{Standard}: 4779Fortran 90 and later 4780 4781@item @emph{Class}: 4782Subroutine 4783 4784@item @emph{Syntax}: 4785@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])} 4786 4787@item @emph{Arguments}: 4788@multitable @columnfractions .15 .70 4789@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)} 4790or larger, and of default kind. 4791@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)} 4792or larger, and of default kind. 4793@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)} 4794or larger, and of default kind. 4795@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}. 4796@end multitable 4797 4798@item @emph{Return value}: 4799None 4800 4801@item @emph{Example}: 4802@smallexample 4803program test_time_and_date 4804 character(8) :: date 4805 character(10) :: time 4806 character(5) :: zone 4807 integer,dimension(8) :: values 4808 ! using keyword arguments 4809 call date_and_time(date,time,zone,values) 4810 call date_and_time(DATE=date,ZONE=zone) 4811 call date_and_time(TIME=time) 4812 call date_and_time(VALUES=values) 4813 print '(a,2x,a,2x,a)', date, time, zone 4814 print '(8i5)', values 4815end program test_time_and_date 4816@end smallexample 4817 4818@item @emph{See also}: 4819@ref{CPU_TIME}, @gol 4820@ref{SYSTEM_CLOCK} 4821@end table 4822 4823 4824 4825@node DBLE 4826@section @code{DBLE} --- Double conversion function 4827@fnindex DBLE 4828@cindex conversion, to real 4829 4830@table @asis 4831@item @emph{Description}: 4832@code{DBLE(A)} Converts @var{A} to double precision real type. 4833 4834@item @emph{Standard}: 4835Fortran 77 and later 4836 4837@item @emph{Class}: 4838Elemental function 4839 4840@item @emph{Syntax}: 4841@code{RESULT = DBLE(A)} 4842 4843@item @emph{Arguments}: 4844@multitable @columnfractions .15 .70 4845@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL}, 4846or @code{COMPLEX}. 4847@end multitable 4848 4849@item @emph{Return value}: 4850The return value is of type double precision real. 4851 4852@item @emph{Example}: 4853@smallexample 4854program test_dble 4855 real :: x = 2.18 4856 integer :: i = 5 4857 complex :: z = (2.3,1.14) 4858 print *, dble(x), dble(i), dble(z) 4859end program test_dble 4860@end smallexample 4861 4862@item @emph{See also}: 4863@ref{REAL} 4864@end table 4865 4866 4867 4868@node DCMPLX 4869@section @code{DCMPLX} --- Double complex conversion function 4870@fnindex DCMPLX 4871@cindex complex numbers, conversion to 4872@cindex conversion, to complex 4873 4874@table @asis 4875@item @emph{Description}: 4876@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is 4877converted to the real component. If @var{Y} is present it is converted to the 4878imaginary component. If @var{Y} is not present then the imaginary component is 4879set to 0.0. If @var{X} is complex then @var{Y} must not be present. 4880 4881@item @emph{Standard}: 4882GNU extension 4883 4884@item @emph{Class}: 4885Elemental function 4886 4887@item @emph{Syntax}: 4888@code{RESULT = DCMPLX(X [, Y])} 4889 4890@item @emph{Arguments}: 4891@multitable @columnfractions .15 .70 4892@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 4893or @code{COMPLEX}. 4894@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be 4895@code{INTEGER} or @code{REAL}. 4896@end multitable 4897 4898@item @emph{Return value}: 4899The return value is of type @code{COMPLEX(8)} 4900 4901@item @emph{Example}: 4902@smallexample 4903program test_dcmplx 4904 integer :: i = 42 4905 real :: x = 3.14 4906 complex :: z 4907 z = cmplx(i, x) 4908 print *, dcmplx(i) 4909 print *, dcmplx(x) 4910 print *, dcmplx(z) 4911 print *, dcmplx(x,i) 4912end program test_dcmplx 4913@end smallexample 4914@end table 4915 4916 4917@node DIGITS 4918@section @code{DIGITS} --- Significant binary digits function 4919@fnindex DIGITS 4920@cindex model representation, significant digits 4921 4922@table @asis 4923@item @emph{Description}: 4924@code{DIGITS(X)} returns the number of significant binary digits of the internal 4925model representation of @var{X}. For example, on a system using a 32-bit 4926floating point representation, a default real number would likely return 24. 4927 4928@item @emph{Standard}: 4929Fortran 90 and later 4930 4931@item @emph{Class}: 4932Inquiry function 4933 4934@item @emph{Syntax}: 4935@code{RESULT = DIGITS(X)} 4936 4937@item @emph{Arguments}: 4938@multitable @columnfractions .15 .70 4939@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4940@end multitable 4941 4942@item @emph{Return value}: 4943The return value is of type @code{INTEGER}. 4944 4945@item @emph{Example}: 4946@smallexample 4947program test_digits 4948 integer :: i = 12345 4949 real :: x = 3.143 4950 real(8) :: y = 2.33 4951 print *, digits(i) 4952 print *, digits(x) 4953 print *, digits(y) 4954end program test_digits 4955@end smallexample 4956@end table 4957 4958 4959 4960@node DIM 4961@section @code{DIM} --- Positive difference 4962@fnindex DIM 4963@fnindex IDIM 4964@fnindex DDIM 4965@cindex positive difference 4966 4967@table @asis 4968@item @emph{Description}: 4969@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive; 4970otherwise returns zero. 4971 4972@item @emph{Standard}: 4973Fortran 77 and later 4974 4975@item @emph{Class}: 4976Elemental function 4977 4978@item @emph{Syntax}: 4979@code{RESULT = DIM(X, Y)} 4980 4981@item @emph{Arguments}: 4982@multitable @columnfractions .15 .70 4983@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL} 4984@item @var{Y} @tab The type shall be the same type and kind as @var{X}. (As 4985a GNU extension, arguments of different kinds are permitted.) 4986@end multitable 4987 4988@item @emph{Return value}: 4989The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU 4990extension, kind is the largest kind of the actual arguments.) 4991 4992@item @emph{Example}: 4993@smallexample 4994program test_dim 4995 integer :: i 4996 real(8) :: x 4997 i = dim(4, 15) 4998 x = dim(4.345_8, 2.111_8) 4999 print *, i 5000 print *, x 5001end program test_dim 5002@end smallexample 5003 5004@item @emph{Specific names}: 5005@multitable @columnfractions .20 .20 .20 .25 5006@item Name @tab Argument @tab Return type @tab Standard 5007@item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 5008@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later 5009@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 5010@end multitable 5011@end table 5012 5013 5014 5015@node DOT_PRODUCT 5016@section @code{DOT_PRODUCT} --- Dot product function 5017@fnindex DOT_PRODUCT 5018@cindex dot product 5019@cindex vector product 5020@cindex product, vector 5021 5022@table @asis 5023@item @emph{Description}: 5024@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication 5025of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be 5026either numeric or logical and must be arrays of rank one and of equal size. If 5027the vectors are @code{INTEGER} or @code{REAL}, the result is 5028@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result 5029is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL}, 5030the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}. 5031 5032@item @emph{Standard}: 5033Fortran 90 and later 5034 5035@item @emph{Class}: 5036Transformational function 5037 5038@item @emph{Syntax}: 5039@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)} 5040 5041@item @emph{Arguments}: 5042@multitable @columnfractions .15 .70 5043@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1. 5044@item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array. 5045@end multitable 5046 5047@item @emph{Return value}: 5048If the arguments are numeric, the return value is a scalar of numeric type, 5049@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are 5050@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}. 5051 5052@item @emph{Example}: 5053@smallexample 5054program test_dot_prod 5055 integer, dimension(3) :: a, b 5056 a = (/ 1, 2, 3 /) 5057 b = (/ 4, 5, 6 /) 5058 print '(3i3)', a 5059 print * 5060 print '(3i3)', b 5061 print * 5062 print *, dot_product(a,b) 5063end program test_dot_prod 5064@end smallexample 5065@end table 5066 5067 5068 5069@node DPROD 5070@section @code{DPROD} --- Double product function 5071@fnindex DPROD 5072@cindex product, double-precision 5073 5074@table @asis 5075@item @emph{Description}: 5076@code{DPROD(X,Y)} returns the product @code{X*Y}. 5077 5078@item @emph{Standard}: 5079Fortran 77 and later 5080 5081@item @emph{Class}: 5082Elemental function 5083 5084@item @emph{Syntax}: 5085@code{RESULT = DPROD(X, Y)} 5086 5087@item @emph{Arguments}: 5088@multitable @columnfractions .15 .70 5089@item @var{X} @tab The type shall be @code{REAL}. 5090@item @var{Y} @tab The type shall be @code{REAL}. 5091@end multitable 5092 5093@item @emph{Return value}: 5094The return value is of type @code{REAL(8)}. 5095 5096@item @emph{Example}: 5097@smallexample 5098program test_dprod 5099 real :: x = 5.2 5100 real :: y = 2.3 5101 real(8) :: d 5102 d = dprod(x,y) 5103 print *, d 5104end program test_dprod 5105@end smallexample 5106 5107@item @emph{Specific names}: 5108@multitable @columnfractions .20 .20 .20 .25 5109@item Name @tab Argument @tab Return type @tab Standard 5110@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 5111@end multitable 5112 5113@end table 5114 5115 5116@node DREAL 5117@section @code{DREAL} --- Double real part function 5118@fnindex DREAL 5119@cindex complex numbers, real part 5120 5121@table @asis 5122@item @emph{Description}: 5123@code{DREAL(Z)} returns the real part of complex variable @var{Z}. 5124 5125@item @emph{Standard}: 5126GNU extension 5127 5128@item @emph{Class}: 5129Elemental function 5130 5131@item @emph{Syntax}: 5132@code{RESULT = DREAL(A)} 5133 5134@item @emph{Arguments}: 5135@multitable @columnfractions .15 .70 5136@item @var{A} @tab The type shall be @code{COMPLEX(8)}. 5137@end multitable 5138 5139@item @emph{Return value}: 5140The return value is of type @code{REAL(8)}. 5141 5142@item @emph{Example}: 5143@smallexample 5144program test_dreal 5145 complex(8) :: z = (1.3_8,7.2_8) 5146 print *, dreal(z) 5147end program test_dreal 5148@end smallexample 5149 5150@item @emph{See also}: 5151@ref{AIMAG} 5152 5153@end table 5154 5155 5156 5157@node DSHIFTL 5158@section @code{DSHIFTL} --- Combined left shift 5159@fnindex DSHIFTL 5160@cindex left shift, combined 5161@cindex shift, left 5162 5163@table @asis 5164@item @emph{Description}: 5165@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5166rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT} 5167bits of @var{J}, and the remaining bits are the rightmost bits of 5168@var{I}. 5169 5170@item @emph{Standard}: 5171Fortran 2008 and later 5172 5173@item @emph{Class}: 5174Elemental function 5175 5176@item @emph{Syntax}: 5177@code{RESULT = DSHIFTL(I, J, SHIFT)} 5178 5179@item @emph{Arguments}: 5180@multitable @columnfractions .15 .70 5181@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5182@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5183If both @var{I} and @var{J} have integer type, then they shall have 5184the same kind type parameter. @var{I} and @var{J} shall not both be 5185BOZ constants. 5186@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5187be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5188shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5189@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5190@end multitable 5191 5192@item @emph{Return value}: 5193If either @var{I} or @var{J} is a BOZ constant, it is first converted 5194as if by the intrinsic function @code{INT} to an integer type with the 5195kind type parameter of the other. 5196 5197@item @emph{See also}: 5198@ref{DSHIFTR} 5199@end table 5200 5201 5202@node DSHIFTR 5203@section @code{DSHIFTR} --- Combined right shift 5204@fnindex DSHIFTR 5205@cindex right shift, combined 5206@cindex shift, right 5207 5208@table @asis 5209@item @emph{Description}: 5210@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5211leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT} 5212bits of @var{I}, and the remaining bits are the leftmost bits of 5213@var{J}. 5214 5215@item @emph{Standard}: 5216Fortran 2008 and later 5217 5218@item @emph{Class}: 5219Elemental function 5220 5221@item @emph{Syntax}: 5222@code{RESULT = DSHIFTR(I, J, SHIFT)} 5223 5224@item @emph{Arguments}: 5225@multitable @columnfractions .15 .70 5226@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5227@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5228If both @var{I} and @var{J} have integer type, then they shall have 5229the same kind type parameter. @var{I} and @var{J} shall not both be 5230BOZ constants. 5231@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5232be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5233shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5234@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5235@end multitable 5236 5237@item @emph{Return value}: 5238If either @var{I} or @var{J} is a BOZ constant, it is first converted 5239as if by the intrinsic function @code{INT} to an integer type with the 5240kind type parameter of the other. 5241 5242@item @emph{See also}: 5243@ref{DSHIFTL} 5244@end table 5245 5246 5247@node DTIME 5248@section @code{DTIME} --- Execution time subroutine (or function) 5249@fnindex DTIME 5250@cindex time, elapsed 5251@cindex elapsed time 5252 5253@table @asis 5254@item @emph{Description}: 5255@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime 5256since the start of the process's execution in @var{TIME}. @var{VALUES} 5257returns the user and system components of this time in @code{VALUES(1)} and 5258@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + 5259VALUES(2)}. 5260 5261Subsequent invocations of @code{DTIME} return values accumulated since the 5262previous invocation. 5263 5264On some systems, the underlying timings are represented using types with 5265sufficiently small limits that overflows (wrap around) are possible, such as 526632-bit types. Therefore, the values returned by this intrinsic might be, or 5267become, negative, or numerically less than previous values, during a single 5268run of the compiled program. 5269 5270Please note, that this implementation is thread safe if used within OpenMP 5271directives, i.e., its state will be consistent while called from multiple 5272threads. However, if @code{DTIME} is called from multiple threads, the result 5273is still the time since the last invocation. This may not give the intended 5274results. If possible, use @code{CPU_TIME} instead. 5275 5276This intrinsic is provided in both subroutine and function forms; however, 5277only one form can be used in any given program unit. 5278 5279@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5280 5281@multitable @columnfractions .15 .30 .40 5282@item @tab @code{VALUES(1)}: @tab User time in seconds. 5283@item @tab @code{VALUES(2)}: @tab System time in seconds. 5284@item @tab @code{TIME}: @tab Run time since start in seconds. 5285@end multitable 5286 5287@item @emph{Standard}: 5288GNU extension 5289 5290@item @emph{Class}: 5291Subroutine, function 5292 5293@item @emph{Syntax}: 5294@multitable @columnfractions .80 5295@item @code{CALL DTIME(VALUES, TIME)}. 5296@item @code{TIME = DTIME(VALUES)}, (not recommended). 5297@end multitable 5298 5299@item @emph{Arguments}: 5300@multitable @columnfractions .15 .70 5301@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5302@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5303@end multitable 5304 5305@item @emph{Return value}: 5306Elapsed time in seconds since the last invocation or since the start of program 5307execution if not called before. 5308 5309@item @emph{Example}: 5310@smallexample 5311program test_dtime 5312 integer(8) :: i, j 5313 real, dimension(2) :: tarray 5314 real :: result 5315 call dtime(tarray, result) 5316 print *, result 5317 print *, tarray(1) 5318 print *, tarray(2) 5319 do i=1,100000000 ! Just a delay 5320 j = i * i - i 5321 end do 5322 call dtime(tarray, result) 5323 print *, result 5324 print *, tarray(1) 5325 print *, tarray(2) 5326end program test_dtime 5327@end smallexample 5328 5329@item @emph{See also}: 5330@ref{CPU_TIME} 5331 5332@end table 5333 5334 5335 5336@node EOSHIFT 5337@section @code{EOSHIFT} --- End-off shift elements of an array 5338@fnindex EOSHIFT 5339@cindex array, shift 5340 5341@table @asis 5342@item @emph{Description}: 5343@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on 5344elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is 5345omitted it is taken to be @code{1}. @var{DIM} is a scalar of type 5346@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the 5347rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of 5348@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, 5349then all complete rank one sections of @var{ARRAY} along the given dimension are 5350shifted. Elements shifted out one end of each rank one section are dropped. If 5351@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY} 5352is copied back in the other end. If @var{BOUNDARY} is not present then the 5353following are copied in depending on the type of @var{ARRAY}. 5354 5355@multitable @columnfractions .15 .80 5356@item @emph{Array Type} @tab @emph{Boundary Value} 5357@item Numeric @tab 0 of the type and kind of @var{ARRAY}. 5358@item Logical @tab @code{.FALSE.}. 5359@item Character(@var{len}) @tab @var{len} blanks. 5360@end multitable 5361 5362@item @emph{Standard}: 5363Fortran 90 and later 5364 5365@item @emph{Class}: 5366Transformational function 5367 5368@item @emph{Syntax}: 5369@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])} 5370 5371@item @emph{Arguments}: 5372@multitable @columnfractions .15 .70 5373@item @var{ARRAY} @tab May be any type, not scalar. 5374@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 5375@item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 5376@item @var{DIM} @tab The type shall be @code{INTEGER}. 5377@end multitable 5378 5379@item @emph{Return value}: 5380Returns an array of same type and rank as the @var{ARRAY} argument. 5381 5382@item @emph{Example}: 5383@smallexample 5384program test_eoshift 5385 integer, dimension(3,3) :: a 5386 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 5387 print '(3i3)', a(1,:) 5388 print '(3i3)', a(2,:) 5389 print '(3i3)', a(3,:) 5390 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) 5391 print * 5392 print '(3i3)', a(1,:) 5393 print '(3i3)', a(2,:) 5394 print '(3i3)', a(3,:) 5395end program test_eoshift 5396@end smallexample 5397@end table 5398 5399 5400 5401@node EPSILON 5402@section @code{EPSILON} --- Epsilon function 5403@fnindex EPSILON 5404@cindex model representation, epsilon 5405 5406@table @asis 5407@item @emph{Description}: 5408@code{EPSILON(X)} returns the smallest number @var{E} of the same kind 5409as @var{X} such that @math{1 + E > 1}. 5410 5411@item @emph{Standard}: 5412Fortran 90 and later 5413 5414@item @emph{Class}: 5415Inquiry function 5416 5417@item @emph{Syntax}: 5418@code{RESULT = EPSILON(X)} 5419 5420@item @emph{Arguments}: 5421@multitable @columnfractions .15 .70 5422@item @var{X} @tab The type shall be @code{REAL}. 5423@end multitable 5424 5425@item @emph{Return value}: 5426The return value is of same type as the argument. 5427 5428@item @emph{Example}: 5429@smallexample 5430program test_epsilon 5431 real :: x = 3.143 5432 real(8) :: y = 2.33 5433 print *, EPSILON(x) 5434 print *, EPSILON(y) 5435end program test_epsilon 5436@end smallexample 5437@end table 5438 5439 5440 5441@node ERF 5442@section @code{ERF} --- Error function 5443@fnindex ERF 5444@cindex error function 5445 5446@table @asis 5447@item @emph{Description}: 5448@code{ERF(X)} computes the error function of @var{X}. 5449 5450@item @emph{Standard}: 5451Fortran 2008 and later 5452 5453@item @emph{Class}: 5454Elemental function 5455 5456@item @emph{Syntax}: 5457@code{RESULT = ERF(X)} 5458 5459@item @emph{Arguments}: 5460@multitable @columnfractions .15 .70 5461@item @var{X} @tab The type shall be @code{REAL}. 5462@end multitable 5463 5464@item @emph{Return value}: 5465The return value is of type @code{REAL}, of the same kind as 5466@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }. 5467 5468@item @emph{Example}: 5469@smallexample 5470program test_erf 5471 real(8) :: x = 0.17_8 5472 x = erf(x) 5473end program test_erf 5474@end smallexample 5475 5476@item @emph{Specific names}: 5477@multitable @columnfractions .20 .20 .20 .25 5478@item Name @tab Argument @tab Return type @tab Standard 5479@item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5480@end multitable 5481@end table 5482 5483 5484 5485@node ERFC 5486@section @code{ERFC} --- Error function 5487@fnindex ERFC 5488@cindex error function, complementary 5489 5490@table @asis 5491@item @emph{Description}: 5492@code{ERFC(X)} computes the complementary error function of @var{X}. 5493 5494@item @emph{Standard}: 5495Fortran 2008 and later 5496 5497@item @emph{Class}: 5498Elemental function 5499 5500@item @emph{Syntax}: 5501@code{RESULT = ERFC(X)} 5502 5503@item @emph{Arguments}: 5504@multitable @columnfractions .15 .70 5505@item @var{X} @tab The type shall be @code{REAL}. 5506@end multitable 5507 5508@item @emph{Return value}: 5509The return value is of type @code{REAL} and of the same kind as @var{X}. 5510It lies in the range @math{ 0 \leq erfc (x) \leq 2 }. 5511 5512@item @emph{Example}: 5513@smallexample 5514program test_erfc 5515 real(8) :: x = 0.17_8 5516 x = erfc(x) 5517end program test_erfc 5518@end smallexample 5519 5520@item @emph{Specific names}: 5521@multitable @columnfractions .20 .20 .20 .25 5522@item Name @tab Argument @tab Return type @tab Standard 5523@item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5524@end multitable 5525@end table 5526 5527 5528 5529@node ERFC_SCALED 5530@section @code{ERFC_SCALED} --- Error function 5531@fnindex ERFC_SCALED 5532@cindex error function, complementary, exponentially-scaled 5533 5534@table @asis 5535@item @emph{Description}: 5536@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary 5537error function of @var{X}. 5538 5539@item @emph{Standard}: 5540Fortran 2008 and later 5541 5542@item @emph{Class}: 5543Elemental function 5544 5545@item @emph{Syntax}: 5546@code{RESULT = ERFC_SCALED(X)} 5547 5548@item @emph{Arguments}: 5549@multitable @columnfractions .15 .70 5550@item @var{X} @tab The type shall be @code{REAL}. 5551@end multitable 5552 5553@item @emph{Return value}: 5554The return value is of type @code{REAL} and of the same kind as @var{X}. 5555 5556@item @emph{Example}: 5557@smallexample 5558program test_erfc_scaled 5559 real(8) :: x = 0.17_8 5560 x = erfc_scaled(x) 5561end program test_erfc_scaled 5562@end smallexample 5563@end table 5564 5565 5566 5567@node ETIME 5568@section @code{ETIME} --- Execution time subroutine (or function) 5569@fnindex ETIME 5570@cindex time, elapsed 5571 5572@table @asis 5573@item @emph{Description}: 5574@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime 5575since the start of the process's execution in @var{TIME}. @var{VALUES} 5576returns the user and system components of this time in @code{VALUES(1)} and 5577@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. 5578 5579On some systems, the underlying timings are represented using types with 5580sufficiently small limits that overflows (wrap around) are possible, such as 558132-bit types. Therefore, the values returned by this intrinsic might be, or 5582become, negative, or numerically less than previous values, during a single 5583run of the compiled program. 5584 5585This intrinsic is provided in both subroutine and function forms; however, 5586only one form can be used in any given program unit. 5587 5588@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5589 5590@multitable @columnfractions .15 .30 .60 5591@item @tab @code{VALUES(1)}: @tab User time in seconds. 5592@item @tab @code{VALUES(2)}: @tab System time in seconds. 5593@item @tab @code{TIME}: @tab Run time since start in seconds. 5594@end multitable 5595 5596@item @emph{Standard}: 5597GNU extension 5598 5599@item @emph{Class}: 5600Subroutine, function 5601 5602@item @emph{Syntax}: 5603@multitable @columnfractions .80 5604@item @code{CALL ETIME(VALUES, TIME)}. 5605@item @code{TIME = ETIME(VALUES)}, (not recommended). 5606@end multitable 5607 5608@item @emph{Arguments}: 5609@multitable @columnfractions .15 .70 5610@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5611@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5612@end multitable 5613 5614@item @emph{Return value}: 5615Elapsed time in seconds since the start of program execution. 5616 5617@item @emph{Example}: 5618@smallexample 5619program test_etime 5620 integer(8) :: i, j 5621 real, dimension(2) :: tarray 5622 real :: result 5623 call ETIME(tarray, result) 5624 print *, result 5625 print *, tarray(1) 5626 print *, tarray(2) 5627 do i=1,100000000 ! Just a delay 5628 j = i * i - i 5629 end do 5630 call ETIME(tarray, result) 5631 print *, result 5632 print *, tarray(1) 5633 print *, tarray(2) 5634end program test_etime 5635@end smallexample 5636 5637@item @emph{See also}: 5638@ref{CPU_TIME} 5639 5640@end table 5641 5642 5643 5644@node EVENT_QUERY 5645@section @code{EVENT_QUERY} --- Query whether a coarray event has occurred 5646@fnindex EVENT_QUERY 5647@cindex Events, EVENT_QUERY 5648 5649@table @asis 5650@item @emph{Description}: 5651@code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been 5652posted to the @var{EVENT} variable and not yet been removed by calling 5653@code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful, 5654it is assigned the value 0. If it is present and the invocation has failed, 5655it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}. 5656 5657@item @emph{Standard}: 5658TS 18508 or later 5659 5660@item @emph{Class}: 5661 subroutine 5662 5663@item @emph{Syntax}: 5664@code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])} 5665 5666@item @emph{Arguments}: 5667@multitable @columnfractions .15 .70 5668@item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE}, 5669defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed. 5670@item @var{COUNT} @tab (intent(out))Scalar integer with at least the 5671precision of default integer. 5672@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 5673@end multitable 5674 5675@item @emph{Example}: 5676@smallexample 5677program atomic 5678 use iso_fortran_env 5679 implicit none 5680 type(event_type) :: event_value_has_been_set[*] 5681 integer :: cnt 5682 if (this_image() == 1) then 5683 call event_query (event_value_has_been_set, cnt) 5684 if (cnt > 0) write(*,*) "Value has been set" 5685 elseif (this_image() == 2) then 5686 event post (event_value_has_been_set[1]) 5687 end if 5688end program atomic 5689@end smallexample 5690 5691@end table 5692 5693 5694 5695@node EXECUTE_COMMAND_LINE 5696@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command 5697@fnindex EXECUTE_COMMAND_LINE 5698@cindex system, system call 5699@cindex command line 5700 5701@table @asis 5702@item @emph{Description}: 5703@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or 5704asynchronously. 5705 5706The @code{COMMAND} argument is passed to the shell and executed (The 5707shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.). 5708If @code{WAIT} is present and has the value false, the execution of 5709the command is asynchronous if the system supports it; otherwise, the 5710command is executed synchronously using the C library's @code{system} 5711call. 5712 5713The three last arguments allow the user to get status information. After 5714synchronous execution, @code{EXITSTAT} contains the integer exit code of 5715the command, as returned by @code{system}. @code{CMDSTAT} is set to zero 5716if the command line was executed (whatever its exit status was). 5717@code{CMDMSG} is assigned an error message if an error has occurred. 5718 5719Note that the @code{system} function need not be thread-safe. It is 5720the responsibility of the user to ensure that @code{system} is not 5721called concurrently. 5722 5723For asynchronous execution on supported targets, the POSIX 5724@code{posix_spawn} or @code{fork} functions are used. Also, a signal 5725handler for the @code{SIGCHLD} signal is installed. 5726 5727@item @emph{Standard}: 5728Fortran 2008 and later 5729 5730@item @emph{Class}: 5731Subroutine 5732 5733@item @emph{Syntax}: 5734@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])} 5735 5736@item @emph{Arguments}: 5737@multitable @columnfractions .15 .70 5738@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar. 5739@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar. 5740@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5741default kind. 5742@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5743default kind. 5744@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the 5745default kind. 5746@end multitable 5747 5748@item @emph{Example}: 5749@smallexample 5750program test_exec 5751 integer :: i 5752 5753 call execute_command_line ("external_prog.exe", exitstat=i) 5754 print *, "Exit status of external_prog.exe was ", i 5755 5756 call execute_command_line ("reindex_files.exe", wait=.false.) 5757 print *, "Now reindexing files in the background" 5758 5759end program test_exec 5760@end smallexample 5761 5762 5763@item @emph{Note}: 5764 5765Because this intrinsic is implemented in terms of the @code{system} 5766function call, its behavior with respect to signaling is processor 5767dependent. In particular, on POSIX-compliant systems, the SIGINT and 5768SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As 5769such, if the parent process is terminated, the child process might not be 5770terminated alongside. 5771 5772 5773@item @emph{See also}: 5774@ref{SYSTEM} 5775@end table 5776 5777 5778 5779@node EXIT 5780@section @code{EXIT} --- Exit the program with status. 5781@fnindex EXIT 5782@cindex program termination 5783@cindex terminate program 5784 5785@table @asis 5786@item @emph{Description}: 5787@code{EXIT} causes immediate termination of the program with status. If status 5788is omitted it returns the canonical @emph{success} for the system. All Fortran 5789I/O units are closed. 5790 5791@item @emph{Standard}: 5792GNU extension 5793 5794@item @emph{Class}: 5795Subroutine 5796 5797@item @emph{Syntax}: 5798@code{CALL EXIT([STATUS])} 5799 5800@item @emph{Arguments}: 5801@multitable @columnfractions .15 .70 5802@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind. 5803@end multitable 5804 5805@item @emph{Return value}: 5806@code{STATUS} is passed to the parent process on exit. 5807 5808@item @emph{Example}: 5809@smallexample 5810program test_exit 5811 integer :: STATUS = 0 5812 print *, 'This program is going to exit.' 5813 call EXIT(STATUS) 5814end program test_exit 5815@end smallexample 5816 5817@item @emph{See also}: 5818@ref{ABORT}, @gol 5819@ref{KILL} 5820@end table 5821 5822 5823 5824@node EXP 5825@section @code{EXP} --- Exponential function 5826@fnindex EXP 5827@fnindex DEXP 5828@fnindex CEXP 5829@fnindex ZEXP 5830@fnindex CDEXP 5831@cindex exponential function 5832@cindex logarithm function, inverse 5833 5834@table @asis 5835@item @emph{Description}: 5836@code{EXP(X)} computes the base @math{e} exponential of @var{X}. 5837 5838@item @emph{Standard}: 5839Fortran 77 and later, has overloads that are GNU extensions 5840 5841@item @emph{Class}: 5842Elemental function 5843 5844@item @emph{Syntax}: 5845@code{RESULT = EXP(X)} 5846 5847@item @emph{Arguments}: 5848@multitable @columnfractions .15 .70 5849@item @var{X} @tab The type shall be @code{REAL} or 5850@code{COMPLEX}. 5851@end multitable 5852 5853@item @emph{Return value}: 5854The return value has same type and kind as @var{X}. 5855 5856@item @emph{Example}: 5857@smallexample 5858program test_exp 5859 real :: x = 1.0 5860 x = exp(x) 5861end program test_exp 5862@end smallexample 5863 5864@item @emph{Specific names}: 5865@multitable @columnfractions .20 .20 .20 .25 5866@item Name @tab Argument @tab Return type @tab Standard 5867@item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 5868@item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 5869@item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 5870@item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5871@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5872@end multitable 5873@end table 5874 5875 5876 5877@node EXPONENT 5878@section @code{EXPONENT} --- Exponent function 5879@fnindex EXPONENT 5880@cindex real number, exponent 5881@cindex floating point, exponent 5882 5883@table @asis 5884@item @emph{Description}: 5885@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X} 5886is zero the value returned is zero. 5887 5888@item @emph{Standard}: 5889Fortran 90 and later 5890 5891@item @emph{Class}: 5892Elemental function 5893 5894@item @emph{Syntax}: 5895@code{RESULT = EXPONENT(X)} 5896 5897@item @emph{Arguments}: 5898@multitable @columnfractions .15 .70 5899@item @var{X} @tab The type shall be @code{REAL}. 5900@end multitable 5901 5902@item @emph{Return value}: 5903The return value is of type default @code{INTEGER}. 5904 5905@item @emph{Example}: 5906@smallexample 5907program test_exponent 5908 real :: x = 1.0 5909 integer :: i 5910 i = exponent(x) 5911 print *, i 5912 print *, exponent(0.0) 5913end program test_exponent 5914@end smallexample 5915@end table 5916 5917 5918 5919@node EXTENDS_TYPE_OF 5920@section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension 5921@fnindex EXTENDS_TYPE_OF 5922 5923@table @asis 5924@item @emph{Description}: 5925Query dynamic type for extension. 5926 5927@item @emph{Standard}: 5928Fortran 2003 and later 5929 5930@item @emph{Class}: 5931Inquiry function 5932 5933@item @emph{Syntax}: 5934@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)} 5935 5936@item @emph{Arguments}: 5937@multitable @columnfractions .15 .70 5938@item @var{A} @tab Shall be an object of extensible declared type or 5939unlimited polymorphic. 5940@item @var{MOLD} @tab Shall be an object of extensible declared type or 5941unlimited polymorphic. 5942@end multitable 5943 5944@item @emph{Return value}: 5945The return value is a scalar of type default logical. It is true if and only if 5946the dynamic type of A is an extension type of the dynamic type of MOLD. 5947 5948 5949@item @emph{See also}: 5950@ref{SAME_TYPE_AS} 5951@end table 5952 5953 5954 5955@node FDATE 5956@section @code{FDATE} --- Get the current time as a string 5957@fnindex FDATE 5958@cindex time, current 5959@cindex current time 5960@cindex date, current 5961@cindex current date 5962 5963@table @asis 5964@item @emph{Description}: 5965@code{FDATE(DATE)} returns the current date (using the same format as 5966@ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE, 5967TIME())}. 5968 5969This intrinsic is provided in both subroutine and function forms; however, 5970only one form can be used in any given program unit. 5971 5972@item @emph{Standard}: 5973GNU extension 5974 5975@item @emph{Class}: 5976Subroutine, function 5977 5978@item @emph{Syntax}: 5979@multitable @columnfractions .80 5980@item @code{CALL FDATE(DATE)}. 5981@item @code{DATE = FDATE()}. 5982@end multitable 5983 5984@item @emph{Arguments}: 5985@multitable @columnfractions .15 .70 5986@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the 5987default kind. It is an @code{INTENT(OUT)} argument. If the length of 5988this variable is too short for the date and time string to fit 5989completely, it will be blank on procedure return. 5990@end multitable 5991 5992@item @emph{Return value}: 5993The current date and time as a string. 5994 5995@item @emph{Example}: 5996@smallexample 5997program test_fdate 5998 integer(8) :: i, j 5999 character(len=30) :: date 6000 call fdate(date) 6001 print *, 'Program started on ', date 6002 do i = 1, 100000000 ! Just a delay 6003 j = i * i - i 6004 end do 6005 call fdate(date) 6006 print *, 'Program ended on ', date 6007end program test_fdate 6008@end smallexample 6009 6010@item @emph{See also}: 6011@ref{DATE_AND_TIME}, @gol 6012@ref{CTIME} 6013@end table 6014 6015 6016@node FGET 6017@section @code{FGET} --- Read a single character in stream mode from stdin 6018@fnindex FGET 6019@cindex read character, stream mode 6020@cindex stream mode, read character 6021@cindex file operation, read character 6022 6023@table @asis 6024@item @emph{Description}: 6025Read a single character in stream mode from stdin by bypassing normal 6026formatted output. Stream I/O should not be mixed with normal record-oriented 6027(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6028 6029This intrinsic is provided in both subroutine and function forms; however, 6030only one form can be used in any given program unit. 6031 6032Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6033@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6034Programmers should consider the use of new stream IO feature in new code 6035for future portability. See also @ref{Fortran 2003 status}. 6036 6037@item @emph{Standard}: 6038GNU extension 6039 6040@item @emph{Class}: 6041Subroutine, function 6042 6043@item @emph{Syntax}: 6044@multitable @columnfractions .80 6045@item @code{CALL FGET(C [, STATUS])} 6046@item @code{STATUS = FGET(C)} 6047@end multitable 6048 6049@item @emph{Arguments}: 6050@multitable @columnfractions .15 .70 6051@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6052kind. 6053@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6054Returns 0 on success, -1 on end-of-file, and a system specific positive 6055error code otherwise. 6056@end multitable 6057 6058@item @emph{Example}: 6059@smallexample 6060PROGRAM test_fget 6061 INTEGER, PARAMETER :: strlen = 100 6062 INTEGER :: status, i = 1 6063 CHARACTER(len=strlen) :: str = "" 6064 6065 WRITE (*,*) 'Enter text:' 6066 DO 6067 CALL fget(str(i:i), status) 6068 if (status /= 0 .OR. i > strlen) exit 6069 i = i + 1 6070 END DO 6071 WRITE (*,*) TRIM(str) 6072END PROGRAM 6073@end smallexample 6074 6075@item @emph{See also}: 6076@ref{FGETC}, @gol 6077@ref{FPUT}, @gol 6078@ref{FPUTC} 6079@end table 6080 6081 6082 6083@node FGETC 6084@section @code{FGETC} --- Read a single character in stream mode 6085@fnindex FGETC 6086@cindex read character, stream mode 6087@cindex stream mode, read character 6088@cindex file operation, read character 6089 6090@table @asis 6091@item @emph{Description}: 6092Read a single character in stream mode by bypassing normal formatted output. 6093Stream I/O should not be mixed with normal record-oriented (formatted or 6094unformatted) I/O on the same unit; the results are unpredictable. 6095 6096This intrinsic is provided in both subroutine and function forms; however, 6097only one form can be used in any given program unit. 6098 6099Note that the @code{FGET} intrinsic is provided for backwards compatibility 6100with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6101Programmers should consider the use of new stream IO feature in new code 6102for future portability. See also @ref{Fortran 2003 status}. 6103 6104@item @emph{Standard}: 6105GNU extension 6106 6107@item @emph{Class}: 6108Subroutine, function 6109 6110@item @emph{Syntax}: 6111@multitable @columnfractions .80 6112@item @code{CALL FGETC(UNIT, C [, STATUS])} 6113@item @code{STATUS = FGETC(UNIT, C)} 6114@end multitable 6115 6116@item @emph{Arguments}: 6117@multitable @columnfractions .15 .70 6118@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6119@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6120kind. 6121@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6122Returns 0 on success, -1 on end-of-file and a system specific positive 6123error code otherwise. 6124@end multitable 6125 6126@item @emph{Example}: 6127@smallexample 6128PROGRAM test_fgetc 6129 INTEGER :: fd = 42, status 6130 CHARACTER :: c 6131 6132 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD") 6133 DO 6134 CALL fgetc(fd, c, status) 6135 IF (status /= 0) EXIT 6136 call fput(c) 6137 END DO 6138 CLOSE(UNIT=fd) 6139END PROGRAM 6140@end smallexample 6141 6142@item @emph{See also}: 6143@ref{FGET}, @gol 6144@ref{FPUT}, @gol 6145@ref{FPUTC} 6146@end table 6147 6148@node FINDLOC 6149@section @code{FINDLOC} --- Search an array for a value 6150@fnindex FINDLOC 6151@cindex findloc 6152 6153@table @asis 6154@item @emph{Description}: 6155Determines the location of the element in the array with the value 6156given in the @var{VALUE} argument, or, if the @var{DIM} argument is 6157supplied, determines the locations of the elements equal to the 6158@var{VALUE} argument element along each 6159row of the array in the @var{DIM} direction. If @var{MASK} is 6160present, only the elements for which @var{MASK} is @code{.TRUE.} are 6161considered. If more than one element in the array has the value 6162@var{VALUE}, the location returned is that of the first such element 6163in array element order if the @var{BACK} is not present or if it is 6164@code{.FALSE.}. If @var{BACK} is true, the location returned is that 6165of the last such element. If the array has zero size, or all of the 6166elements of @var{MASK} are @code{.FALSE.}, then the result is an array 6167of zeroes. Similarly, if @var{DIM} is supplied and all of the 6168elements of @var{MASK} along a given row are zero, the result value 6169for that row is zero. 6170 6171@item @emph{Standard}: 6172Fortran 2008 and later. 6173 6174@item @emph{Class}: 6175Transformational function 6176 6177@item @emph{Syntax}: 6178@multitable @columnfractions .80 6179@item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])} 6180@item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])} 6181@end multitable 6182 6183@item @emph{Arguments}: 6184@multitable @columnfractions .15 .70 6185@item @var{ARRAY} @tab Shall be an array of intrinsic type. 6186@item @var{VALUE} @tab A scalar of intrinsic type which is in type 6187conformance with @var{ARRAY}. 6188@item @var{DIM} @tab (Optional) Shall be a scalar of type 6189@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 6190inclusive. It may not be an optional dummy argument. 6191@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6192expression indicating the kind parameter of the result. 6193@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 6194@end multitable 6195 6196@item @emph{Return value}: 6197If @var{DIM} is absent, the result is a rank-one array with a length 6198equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 6199is an array with a rank one less than the rank of @var{ARRAY}, and a 6200size corresponding to the size of @var{ARRAY} with the @var{DIM} 6201dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 6202of one, the result is a scalar. If the optional argument @var{KIND} 6203is present, the result is an integer of kind @var{KIND}, otherwise it 6204is of default kind. 6205 6206@item @emph{See also}: 6207@ref{MAXLOC}, @gol 6208@ref{MINLOC} 6209 6210@end table 6211 6212@node FLOOR 6213@section @code{FLOOR} --- Integer floor function 6214@fnindex FLOOR 6215@cindex floor 6216@cindex rounding, floor 6217 6218@table @asis 6219@item @emph{Description}: 6220@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}. 6221 6222@item @emph{Standard}: 6223Fortran 95 and later 6224 6225@item @emph{Class}: 6226Elemental function 6227 6228@item @emph{Syntax}: 6229@code{RESULT = FLOOR(A [, KIND])} 6230 6231@item @emph{Arguments}: 6232@multitable @columnfractions .15 .70 6233@item @var{A} @tab The type shall be @code{REAL}. 6234@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6235expression indicating the kind parameter of the result. 6236@end multitable 6237 6238@item @emph{Return value}: 6239The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 6240and of default-kind @code{INTEGER} otherwise. 6241 6242@item @emph{Example}: 6243@smallexample 6244program test_floor 6245 real :: x = 63.29 6246 real :: y = -63.59 6247 print *, floor(x) ! returns 63 6248 print *, floor(y) ! returns -64 6249end program test_floor 6250@end smallexample 6251 6252@item @emph{See also}: 6253@ref{CEILING}, @gol 6254@ref{NINT} 6255@end table 6256 6257 6258 6259@node FLUSH 6260@section @code{FLUSH} --- Flush I/O unit(s) 6261@fnindex FLUSH 6262@cindex file operation, flush 6263 6264@table @asis 6265@item @emph{Description}: 6266Flushes Fortran unit(s) currently open for output. Without the optional 6267argument, all units are flushed, otherwise just the unit specified. 6268 6269@item @emph{Standard}: 6270GNU extension 6271 6272@item @emph{Class}: 6273Subroutine 6274 6275@item @emph{Syntax}: 6276@code{CALL FLUSH(UNIT)} 6277 6278@item @emph{Arguments}: 6279@multitable @columnfractions .15 .70 6280@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}. 6281@end multitable 6282 6283@item @emph{Note}: 6284Beginning with the Fortran 2003 standard, there is a @code{FLUSH} 6285statement that should be preferred over the @code{FLUSH} intrinsic. 6286 6287The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement 6288have identical effect: they flush the runtime library's I/O buffer so 6289that the data becomes visible to other processes. This does not guarantee 6290that the data is committed to disk. 6291 6292On POSIX systems, you can request that all data is transferred to the 6293storage device by calling the @code{fsync} function, with the POSIX file 6294descriptor of the I/O unit as argument (retrieved with GNU intrinsic 6295@code{FNUM}). The following example shows how: 6296 6297@smallexample 6298 ! Declare the interface for POSIX fsync function 6299 interface 6300 function fsync (fd) bind(c,name="fsync") 6301 use iso_c_binding, only: c_int 6302 integer(c_int), value :: fd 6303 integer(c_int) :: fsync 6304 end function fsync 6305 end interface 6306 6307 ! Variable declaration 6308 integer :: ret 6309 6310 ! Opening unit 10 6311 open (10,file="foo") 6312 6313 ! ... 6314 ! Perform I/O on unit 10 6315 ! ... 6316 6317 ! Flush and sync 6318 flush(10) 6319 ret = fsync(fnum(10)) 6320 6321 ! Handle possible error 6322 if (ret /= 0) stop "Error calling FSYNC" 6323@end smallexample 6324 6325@end table 6326 6327 6328 6329@node FNUM 6330@section @code{FNUM} --- File number function 6331@fnindex FNUM 6332@cindex file operation, file number 6333 6334@table @asis 6335@item @emph{Description}: 6336@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the 6337open Fortran I/O unit @code{UNIT}. 6338 6339@item @emph{Standard}: 6340GNU extension 6341 6342@item @emph{Class}: 6343Function 6344 6345@item @emph{Syntax}: 6346@code{RESULT = FNUM(UNIT)} 6347 6348@item @emph{Arguments}: 6349@multitable @columnfractions .15 .70 6350@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6351@end multitable 6352 6353@item @emph{Return value}: 6354The return value is of type @code{INTEGER} 6355 6356@item @emph{Example}: 6357@smallexample 6358program test_fnum 6359 integer :: i 6360 open (unit=10, status = "scratch") 6361 i = fnum(10) 6362 print *, i 6363 close (10) 6364end program test_fnum 6365@end smallexample 6366@end table 6367 6368 6369 6370@node FPUT 6371@section @code{FPUT} --- Write a single character in stream mode to stdout 6372@fnindex FPUT 6373@cindex write character, stream mode 6374@cindex stream mode, write character 6375@cindex file operation, write character 6376 6377@table @asis 6378@item @emph{Description}: 6379Write a single character in stream mode to stdout by bypassing normal 6380formatted output. Stream I/O should not be mixed with normal record-oriented 6381(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6382 6383This intrinsic is provided in both subroutine and function forms; however, 6384only one form can be used in any given program unit. 6385 6386Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6387@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6388Programmers should consider the use of new stream IO feature in new code 6389for future portability. See also @ref{Fortran 2003 status}. 6390 6391@item @emph{Standard}: 6392GNU extension 6393 6394@item @emph{Class}: 6395Subroutine, function 6396 6397@item @emph{Syntax}: 6398@multitable @columnfractions .80 6399@item @code{CALL FPUT(C [, STATUS])} 6400@item @code{STATUS = FPUT(C)} 6401@end multitable 6402 6403@item @emph{Arguments}: 6404@multitable @columnfractions .15 .70 6405@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6406kind. 6407@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6408Returns 0 on success, -1 on end-of-file and a system specific positive 6409error code otherwise. 6410@end multitable 6411 6412@item @emph{Example}: 6413@smallexample 6414PROGRAM test_fput 6415 CHARACTER(len=10) :: str = "gfortran" 6416 INTEGER :: i 6417 DO i = 1, len_trim(str) 6418 CALL fput(str(i:i)) 6419 END DO 6420END PROGRAM 6421@end smallexample 6422 6423@item @emph{See also}: 6424@ref{FPUTC}, @gol 6425@ref{FGET}, @gol 6426@ref{FGETC} 6427@end table 6428 6429 6430 6431@node FPUTC 6432@section @code{FPUTC} --- Write a single character in stream mode 6433@fnindex FPUTC 6434@cindex write character, stream mode 6435@cindex stream mode, write character 6436@cindex file operation, write character 6437 6438@table @asis 6439@item @emph{Description}: 6440Write a single character in stream mode by bypassing normal formatted 6441output. Stream I/O should not be mixed with normal record-oriented 6442(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6443 6444This intrinsic is provided in both subroutine and function forms; however, 6445only one form can be used in any given program unit. 6446 6447Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6448@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6449Programmers should consider the use of new stream IO feature in new code 6450for future portability. See also @ref{Fortran 2003 status}. 6451 6452@item @emph{Standard}: 6453GNU extension 6454 6455@item @emph{Class}: 6456Subroutine, function 6457 6458@item @emph{Syntax}: 6459@multitable @columnfractions .80 6460@item @code{CALL FPUTC(UNIT, C [, STATUS])} 6461@item @code{STATUS = FPUTC(UNIT, C)} 6462@end multitable 6463 6464@item @emph{Arguments}: 6465@multitable @columnfractions .15 .70 6466@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6467@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6468kind. 6469@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6470Returns 0 on success, -1 on end-of-file and a system specific positive 6471error code otherwise. 6472@end multitable 6473 6474@item @emph{Example}: 6475@smallexample 6476PROGRAM test_fputc 6477 CHARACTER(len=10) :: str = "gfortran" 6478 INTEGER :: fd = 42, i 6479 6480 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW") 6481 DO i = 1, len_trim(str) 6482 CALL fputc(fd, str(i:i)) 6483 END DO 6484 CLOSE(fd) 6485END PROGRAM 6486@end smallexample 6487 6488@item @emph{See also}: 6489@ref{FPUT}, @gol 6490@ref{FGET}, @gol 6491@ref{FGETC} 6492@end table 6493 6494 6495 6496@node FRACTION 6497@section @code{FRACTION} --- Fractional part of the model representation 6498@fnindex FRACTION 6499@cindex real number, fraction 6500@cindex floating point, fraction 6501 6502@table @asis 6503@item @emph{Description}: 6504@code{FRACTION(X)} returns the fractional part of the model 6505representation of @code{X}. 6506 6507@item @emph{Standard}: 6508Fortran 90 and later 6509 6510@item @emph{Class}: 6511Elemental function 6512 6513@item @emph{Syntax}: 6514@code{Y = FRACTION(X)} 6515 6516@item @emph{Arguments}: 6517@multitable @columnfractions .15 .70 6518@item @var{X} @tab The type of the argument shall be a @code{REAL}. 6519@end multitable 6520 6521@item @emph{Return value}: 6522The return value is of the same type and kind as the argument. 6523The fractional part of the model representation of @code{X} is returned; 6524it is @code{X * RADIX(X)**(-EXPONENT(X))}. 6525 6526@item @emph{Example}: 6527@smallexample 6528program test_fraction 6529 real :: x 6530 x = 178.1387e-4 6531 print *, fraction(x), x * radix(x)**(-exponent(x)) 6532end program test_fraction 6533@end smallexample 6534 6535@end table 6536 6537 6538 6539@node FREE 6540@section @code{FREE} --- Frees memory 6541@fnindex FREE 6542@cindex pointer, cray 6543 6544@table @asis 6545@item @emph{Description}: 6546Frees memory previously allocated by @code{MALLOC}. The @code{FREE} 6547intrinsic is an extension intended to be used with Cray pointers, and is 6548provided in GNU Fortran to allow user to compile legacy code. For 6549new code using Fortran 95 pointers, the memory de-allocation intrinsic is 6550@code{DEALLOCATE}. 6551 6552@item @emph{Standard}: 6553GNU extension 6554 6555@item @emph{Class}: 6556Subroutine 6557 6558@item @emph{Syntax}: 6559@code{CALL FREE(PTR)} 6560 6561@item @emph{Arguments}: 6562@multitable @columnfractions .15 .70 6563@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the 6564location of the memory that should be de-allocated. 6565@end multitable 6566 6567@item @emph{Return value}: 6568None 6569 6570@item @emph{Example}: 6571See @code{MALLOC} for an example. 6572 6573@item @emph{See also}: 6574@ref{MALLOC} 6575@end table 6576 6577 6578 6579@node FSEEK 6580@section @code{FSEEK} --- Low level file positioning subroutine 6581@fnindex FSEEK 6582@cindex file operation, seek 6583@cindex file operation, position 6584 6585@table @asis 6586@item @emph{Description}: 6587Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} 6588is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET}, 6589if set to 1, @var{OFFSET} is taken to be relative to the current position 6590@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}. 6591On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek 6592fails silently. 6593 6594This intrinsic routine is not fully backwards compatible with @command{g77}. 6595In @command{g77}, the @code{FSEEK} takes a statement label instead of a 6596@var{STATUS} variable. If FSEEK is used in old code, change 6597@smallexample 6598 CALL FSEEK(UNIT, OFFSET, WHENCE, *label) 6599@end smallexample 6600to 6601@smallexample 6602 INTEGER :: status 6603 CALL FSEEK(UNIT, OFFSET, WHENCE, status) 6604 IF (status /= 0) GOTO label 6605@end smallexample 6606 6607Please note that GNU Fortran provides the Fortran 2003 Stream facility. 6608Programmers should consider the use of new stream IO feature in new code 6609for future portability. See also @ref{Fortran 2003 status}. 6610 6611@item @emph{Standard}: 6612GNU extension 6613 6614@item @emph{Class}: 6615Subroutine 6616 6617@item @emph{Syntax}: 6618@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])} 6619 6620@item @emph{Arguments}: 6621@multitable @columnfractions .15 .70 6622@item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}. 6623@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}. 6624@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}. 6625Its value shall be either 0, 1 or 2. 6626@item @var{STATUS} @tab (Optional) shall be a scalar of type 6627@code{INTEGER(4)}. 6628@end multitable 6629 6630@item @emph{Example}: 6631@smallexample 6632PROGRAM test_fseek 6633 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2 6634 INTEGER :: fd, offset, ierr 6635 6636 ierr = 0 6637 offset = 5 6638 fd = 10 6639 6640 OPEN(UNIT=fd, FILE="fseek.test") 6641 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET 6642 print *, FTELL(fd), ierr 6643 6644 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end 6645 print *, FTELL(fd), ierr 6646 6647 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning 6648 print *, FTELL(fd), ierr 6649 6650 CLOSE(UNIT=fd) 6651END PROGRAM 6652@end smallexample 6653 6654@item @emph{See also}: 6655@ref{FTELL} 6656@end table 6657 6658 6659 6660@node FSTAT 6661@section @code{FSTAT} --- Get file status 6662@fnindex FSTAT 6663@cindex file system, file status 6664 6665@table @asis 6666@item @emph{Description}: 6667@code{FSTAT} is identical to @ref{STAT}, except that information about an 6668already opened file is obtained. 6669 6670The elements in @code{VALUES} are the same as described by @ref{STAT}. 6671 6672This intrinsic is provided in both subroutine and function forms; however, 6673only one form can be used in any given program unit. 6674 6675@item @emph{Standard}: 6676GNU extension 6677 6678@item @emph{Class}: 6679Subroutine, function 6680 6681@item @emph{Syntax}: 6682@multitable @columnfractions .80 6683@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])} 6684@item @code{STATUS = FSTAT(UNIT, VALUES)} 6685@end multitable 6686 6687@item @emph{Arguments}: 6688@multitable @columnfractions .15 .70 6689@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. 6690@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 6691@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 6692on success and a system specific error code otherwise. 6693@end multitable 6694 6695@item @emph{Example}: 6696See @ref{STAT} for an example. 6697 6698@item @emph{See also}: 6699To stat a link: @gol 6700@ref{LSTAT} @gol 6701To stat a file: @gol 6702@ref{STAT} 6703@end table 6704 6705 6706 6707@node FTELL 6708@section @code{FTELL} --- Current stream position 6709@fnindex FTELL 6710@cindex file operation, position 6711 6712@table @asis 6713@item @emph{Description}: 6714Retrieves the current position within an open file. 6715 6716This intrinsic is provided in both subroutine and function forms; however, 6717only one form can be used in any given program unit. 6718 6719@item @emph{Standard}: 6720GNU extension 6721 6722@item @emph{Class}: 6723Subroutine, function 6724 6725@item @emph{Syntax}: 6726@multitable @columnfractions .80 6727@item @code{CALL FTELL(UNIT, OFFSET)} 6728@item @code{OFFSET = FTELL(UNIT)} 6729@end multitable 6730 6731@item @emph{Arguments}: 6732@multitable @columnfractions .15 .70 6733@item @var{OFFSET} @tab Shall of type @code{INTEGER}. 6734@item @var{UNIT} @tab Shall of type @code{INTEGER}. 6735@end multitable 6736 6737@item @emph{Return value}: 6738In either syntax, @var{OFFSET} is set to the current offset of unit 6739number @var{UNIT}, or to @math{-1} if the unit is not currently open. 6740 6741@item @emph{Example}: 6742@smallexample 6743PROGRAM test_ftell 6744 INTEGER :: i 6745 OPEN(10, FILE="temp.dat") 6746 CALL ftell(10,i) 6747 WRITE(*,*) i 6748END PROGRAM 6749@end smallexample 6750 6751@item @emph{See also}: 6752@ref{FSEEK} 6753@end table 6754 6755 6756 6757@node GAMMA 6758@section @code{GAMMA} --- Gamma function 6759@fnindex GAMMA 6760@fnindex DGAMMA 6761@cindex Gamma function 6762@cindex Factorial function 6763 6764@table @asis 6765@item @emph{Description}: 6766@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive, 6767integer values of @var{X} the Gamma function simplifies to the factorial 6768function @math{\Gamma(x)=(x-1)!}. 6769 6770@tex 6771$$ 6772\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t 6773$$ 6774@end tex 6775 6776@item @emph{Standard}: 6777Fortran 2008 and later 6778 6779@item @emph{Class}: 6780Elemental function 6781 6782@item @emph{Syntax}: 6783@code{X = GAMMA(X)} 6784 6785@item @emph{Arguments}: 6786@multitable @columnfractions .15 .70 6787@item @var{X} @tab Shall be of type @code{REAL} and neither zero 6788nor a negative integer. 6789@end multitable 6790 6791@item @emph{Return value}: 6792The return value is of type @code{REAL} of the same kind as @var{X}. 6793 6794@item @emph{Example}: 6795@smallexample 6796program test_gamma 6797 real :: x = 1.0 6798 x = gamma(x) ! returns 1.0 6799end program test_gamma 6800@end smallexample 6801 6802@item @emph{Specific names}: 6803@multitable @columnfractions .20 .20 .20 .25 6804@item Name @tab Argument @tab Return type @tab Standard 6805@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 6806@end multitable 6807 6808@item @emph{See also}: 6809Logarithm of the Gamma function: @gol 6810@ref{LOG_GAMMA} 6811@end table 6812 6813 6814 6815@node GERROR 6816@section @code{GERROR} --- Get last system error message 6817@fnindex GERROR 6818@cindex system, error handling 6819 6820@table @asis 6821@item @emph{Description}: 6822Returns the system error message corresponding to the last system error. 6823This resembles the functionality of @code{strerror(3)} in C. 6824 6825@item @emph{Standard}: 6826GNU extension 6827 6828@item @emph{Class}: 6829Subroutine 6830 6831@item @emph{Syntax}: 6832@code{CALL GERROR(RESULT)} 6833 6834@item @emph{Arguments}: 6835@multitable @columnfractions .15 .70 6836@item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default 6837@end multitable 6838 6839@item @emph{Example}: 6840@smallexample 6841PROGRAM test_gerror 6842 CHARACTER(len=100) :: msg 6843 CALL gerror(msg) 6844 WRITE(*,*) msg 6845END PROGRAM 6846@end smallexample 6847 6848@item @emph{See also}: 6849@ref{IERRNO}, @gol 6850@ref{PERROR} 6851@end table 6852 6853 6854 6855@node GETARG 6856@section @code{GETARG} --- Get command line arguments 6857@fnindex GETARG 6858@cindex command-line arguments 6859@cindex arguments, to program 6860 6861@table @asis 6862@item @emph{Description}: 6863Retrieve the @var{POS}-th argument that was passed on the 6864command line when the containing program was invoked. 6865 6866This intrinsic routine is provided for backwards compatibility with 6867GNU Fortran 77. In new code, programmers should consider the use of 6868the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 6869standard. 6870 6871@item @emph{Standard}: 6872GNU extension 6873 6874@item @emph{Class}: 6875Subroutine 6876 6877@item @emph{Syntax}: 6878@code{CALL GETARG(POS, VALUE)} 6879 6880@item @emph{Arguments}: 6881@multitable @columnfractions .15 .70 6882@item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than 6883the default integer kind; @math{@var{POS} \geq 0} 6884@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default 6885kind. 6886@item @var{VALUE} @tab Shall be of type @code{CHARACTER}. 6887@end multitable 6888 6889@item @emph{Return value}: 6890After @code{GETARG} returns, the @var{VALUE} argument holds the 6891@var{POS}th command line argument. If @var{VALUE} cannot hold the 6892argument, it is truncated to fit the length of @var{VALUE}. If there are 6893less than @var{POS} arguments specified at the command line, @var{VALUE} 6894will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set 6895to the name of the program (on systems that support this feature). 6896 6897@item @emph{Example}: 6898@smallexample 6899PROGRAM test_getarg 6900 INTEGER :: i 6901 CHARACTER(len=32) :: arg 6902 6903 DO i = 1, iargc() 6904 CALL getarg(i, arg) 6905 WRITE (*,*) arg 6906 END DO 6907END PROGRAM 6908@end smallexample 6909 6910@item @emph{See also}: 6911GNU Fortran 77 compatibility function: @gol 6912@ref{IARGC} @gol 6913Fortran 2003 functions and subroutines: @gol 6914@ref{GET_COMMAND}, @gol 6915@ref{GET_COMMAND_ARGUMENT}, @gol 6916@ref{COMMAND_ARGUMENT_COUNT} 6917@end table 6918 6919 6920 6921@node GET_COMMAND 6922@section @code{GET_COMMAND} --- Get the entire command line 6923@fnindex GET_COMMAND 6924@cindex command-line arguments 6925@cindex arguments, to program 6926 6927@table @asis 6928@item @emph{Description}: 6929Retrieve the entire command line that was used to invoke the program. 6930 6931@item @emph{Standard}: 6932Fortran 2003 and later 6933 6934@item @emph{Class}: 6935Subroutine 6936 6937@item @emph{Syntax}: 6938@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])} 6939 6940@item @emph{Arguments}: 6941@multitable @columnfractions .15 .70 6942@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and 6943of default kind. 6944@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of 6945default kind. 6946@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of 6947default kind. 6948@end multitable 6949 6950@item @emph{Return value}: 6951If @var{COMMAND} is present, stores the entire command line that was used 6952to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is 6953assigned the length of the command line. If @var{STATUS} is present, it 6954is assigned 0 upon success of the command, -1 if @var{COMMAND} is too 6955short to store the command line, or a positive value in case of an error. 6956 6957@item @emph{Example}: 6958@smallexample 6959PROGRAM test_get_command 6960 CHARACTER(len=255) :: cmd 6961 CALL get_command(cmd) 6962 WRITE (*,*) TRIM(cmd) 6963END PROGRAM 6964@end smallexample 6965 6966@item @emph{See also}: 6967@ref{GET_COMMAND_ARGUMENT}, @gol 6968@ref{COMMAND_ARGUMENT_COUNT} 6969@end table 6970 6971 6972 6973@node GET_COMMAND_ARGUMENT 6974@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments 6975@fnindex GET_COMMAND_ARGUMENT 6976@cindex command-line arguments 6977@cindex arguments, to program 6978 6979@table @asis 6980@item @emph{Description}: 6981Retrieve the @var{NUMBER}-th argument that was passed on the 6982command line when the containing program was invoked. 6983 6984@item @emph{Standard}: 6985Fortran 2003 and later 6986 6987@item @emph{Class}: 6988Subroutine 6989 6990@item @emph{Syntax}: 6991@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])} 6992 6993@item @emph{Arguments}: 6994@multitable @columnfractions .15 .70 6995@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of 6996default kind, @math{@var{NUMBER} \geq 0} 6997@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 6998and of default kind. 6999@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7000and of default kind. 7001@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7002and of default kind. 7003@end multitable 7004 7005@item @emph{Return value}: 7006After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the 7007@var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is 7008truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER} 7009arguments specified at the command line, @var{VALUE} will be filled with blanks. 7010If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on 7011systems that support this feature). The @var{LENGTH} argument contains the 7012length of the @var{NUMBER}-th command line argument. If the argument retrieval 7013fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated 7014command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is 7015zero. 7016 7017@item @emph{Example}: 7018@smallexample 7019PROGRAM test_get_command_argument 7020 INTEGER :: i 7021 CHARACTER(len=32) :: arg 7022 7023 i = 0 7024 DO 7025 CALL get_command_argument(i, arg) 7026 IF (LEN_TRIM(arg) == 0) EXIT 7027 7028 WRITE (*,*) TRIM(arg) 7029 i = i+1 7030 END DO 7031END PROGRAM 7032@end smallexample 7033 7034@item @emph{See also}: 7035@ref{GET_COMMAND}, @gol 7036@ref{COMMAND_ARGUMENT_COUNT} 7037@end table 7038 7039 7040 7041@node GETCWD 7042@section @code{GETCWD} --- Get current working directory 7043@fnindex GETCWD 7044@cindex system, working directory 7045 7046@table @asis 7047@item @emph{Description}: 7048Get current working directory. 7049 7050This intrinsic is provided in both subroutine and function forms; however, 7051only one form can be used in any given program unit. 7052 7053@item @emph{Standard}: 7054GNU extension 7055 7056@item @emph{Class}: 7057Subroutine, function 7058 7059@item @emph{Syntax}: 7060@multitable @columnfractions .80 7061@item @code{CALL GETCWD(C [, STATUS])} 7062@item @code{STATUS = GETCWD(C)} 7063@end multitable 7064 7065@item @emph{Arguments}: 7066@multitable @columnfractions .15 .70 7067@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. 7068@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, 7069a system specific and nonzero error code otherwise. 7070@end multitable 7071 7072@item @emph{Example}: 7073@smallexample 7074PROGRAM test_getcwd 7075 CHARACTER(len=255) :: cwd 7076 CALL getcwd(cwd) 7077 WRITE(*,*) TRIM(cwd) 7078END PROGRAM 7079@end smallexample 7080 7081@item @emph{See also}: 7082@ref{CHDIR} 7083@end table 7084 7085 7086 7087@node GETENV 7088@section @code{GETENV} --- Get an environmental variable 7089@fnindex GETENV 7090@cindex environment variable 7091 7092@table @asis 7093@item @emph{Description}: 7094Get the @var{VALUE} of the environmental variable @var{NAME}. 7095 7096This intrinsic routine is provided for backwards compatibility with 7097GNU Fortran 77. In new code, programmers should consider the use of 7098the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran 70992003 standard. 7100 7101Note that @code{GETENV} need not be thread-safe. It is the 7102responsibility of the user to ensure that the environment is not being 7103updated concurrently with a call to the @code{GETENV} intrinsic. 7104 7105@item @emph{Standard}: 7106GNU extension 7107 7108@item @emph{Class}: 7109Subroutine 7110 7111@item @emph{Syntax}: 7112@code{CALL GETENV(NAME, VALUE)} 7113 7114@item @emph{Arguments}: 7115@multitable @columnfractions .15 .70 7116@item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind. 7117@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. 7118@end multitable 7119 7120@item @emph{Return value}: 7121Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 7122not large enough to hold the data, it is truncated. If @var{NAME} 7123is not set, @var{VALUE} will be filled with blanks. 7124 7125@item @emph{Example}: 7126@smallexample 7127PROGRAM test_getenv 7128 CHARACTER(len=255) :: homedir 7129 CALL getenv("HOME", homedir) 7130 WRITE (*,*) TRIM(homedir) 7131END PROGRAM 7132@end smallexample 7133 7134@item @emph{See also}: 7135@ref{GET_ENVIRONMENT_VARIABLE} 7136@end table 7137 7138 7139 7140@node GET_ENVIRONMENT_VARIABLE 7141@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable 7142@fnindex GET_ENVIRONMENT_VARIABLE 7143@cindex environment variable 7144 7145@table @asis 7146@item @emph{Description}: 7147Get the @var{VALUE} of the environmental variable @var{NAME}. 7148 7149Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It 7150is the responsibility of the user to ensure that the environment is 7151not being updated concurrently with a call to the 7152@code{GET_ENVIRONMENT_VARIABLE} intrinsic. 7153 7154@item @emph{Standard}: 7155Fortran 2003 and later 7156 7157@item @emph{Class}: 7158Subroutine 7159 7160@item @emph{Syntax}: 7161@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)} 7162 7163@item @emph{Arguments}: 7164@multitable @columnfractions .15 .70 7165@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER} 7166and of default kind. 7167@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 7168and of default kind. 7169@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7170and of default kind. 7171@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7172and of default kind. 7173@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL} 7174and of default kind. 7175@end multitable 7176 7177@item @emph{Return value}: 7178Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 7179not large enough to hold the data, it is truncated. If @var{NAME} 7180is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH} 7181contains the length needed for storing the environment variable @var{NAME} 7182or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present 7183but too short for the environment variable; it is 1 if the environment 7184variable does not exist and 2 if the processor does not support environment 7185variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is 7186present with the value @code{.FALSE.}, the trailing blanks in @var{NAME} 7187are significant; otherwise they are not part of the environment variable 7188name. 7189 7190@item @emph{Example}: 7191@smallexample 7192PROGRAM test_getenv 7193 CHARACTER(len=255) :: homedir 7194 CALL get_environment_variable("HOME", homedir) 7195 WRITE (*,*) TRIM(homedir) 7196END PROGRAM 7197@end smallexample 7198@end table 7199 7200 7201 7202@node GETGID 7203@section @code{GETGID} --- Group ID function 7204@fnindex GETGID 7205@cindex system, group ID 7206 7207@table @asis 7208@item @emph{Description}: 7209Returns the numerical group ID of the current process. 7210 7211@item @emph{Standard}: 7212GNU extension 7213 7214@item @emph{Class}: 7215Function 7216 7217@item @emph{Syntax}: 7218@code{RESULT = GETGID()} 7219 7220@item @emph{Return value}: 7221The return value of @code{GETGID} is an @code{INTEGER} of the default 7222kind. 7223 7224 7225@item @emph{Example}: 7226See @code{GETPID} for an example. 7227 7228@item @emph{See also}: 7229@ref{GETPID}, @gol 7230@ref{GETUID} 7231@end table 7232 7233 7234 7235@node GETLOG 7236@section @code{GETLOG} --- Get login name 7237@fnindex GETLOG 7238@cindex system, login name 7239@cindex login name 7240 7241@table @asis 7242@item @emph{Description}: 7243Gets the username under which the program is running. 7244 7245@item @emph{Standard}: 7246GNU extension 7247 7248@item @emph{Class}: 7249Subroutine 7250 7251@item @emph{Syntax}: 7252@code{CALL GETLOG(C)} 7253 7254@item @emph{Arguments}: 7255@multitable @columnfractions .15 .70 7256@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind. 7257@end multitable 7258 7259@item @emph{Return value}: 7260Stores the current user name in @var{LOGIN}. (On systems where POSIX 7261functions @code{geteuid} and @code{getpwuid} are not available, and 7262the @code{getlogin} function is not implemented either, this will 7263return a blank string.) 7264 7265@item @emph{Example}: 7266@smallexample 7267PROGRAM TEST_GETLOG 7268 CHARACTER(32) :: login 7269 CALL GETLOG(login) 7270 WRITE(*,*) login 7271END PROGRAM 7272@end smallexample 7273 7274@item @emph{See also}: 7275@ref{GETUID} 7276@end table 7277 7278 7279 7280@node GETPID 7281@section @code{GETPID} --- Process ID function 7282@fnindex GETPID 7283@cindex system, process ID 7284@cindex process ID 7285 7286@table @asis 7287@item @emph{Description}: 7288Returns the numerical process identifier of the current process. 7289 7290@item @emph{Standard}: 7291GNU extension 7292 7293@item @emph{Class}: 7294Function 7295 7296@item @emph{Syntax}: 7297@code{RESULT = GETPID()} 7298 7299@item @emph{Return value}: 7300The return value of @code{GETPID} is an @code{INTEGER} of the default 7301kind. 7302 7303 7304@item @emph{Example}: 7305@smallexample 7306program info 7307 print *, "The current process ID is ", getpid() 7308 print *, "Your numerical user ID is ", getuid() 7309 print *, "Your numerical group ID is ", getgid() 7310end program info 7311@end smallexample 7312 7313@item @emph{See also}: 7314@ref{GETGID}, @gol 7315@ref{GETUID} 7316@end table 7317 7318 7319 7320@node GETUID 7321@section @code{GETUID} --- User ID function 7322@fnindex GETUID 7323@cindex system, user ID 7324@cindex user id 7325 7326@table @asis 7327@item @emph{Description}: 7328Returns the numerical user ID of the current process. 7329 7330@item @emph{Standard}: 7331GNU extension 7332 7333@item @emph{Class}: 7334Function 7335 7336@item @emph{Syntax}: 7337@code{RESULT = GETUID()} 7338 7339@item @emph{Return value}: 7340The return value of @code{GETUID} is an @code{INTEGER} of the default 7341kind. 7342 7343 7344@item @emph{Example}: 7345See @code{GETPID} for an example. 7346 7347@item @emph{See also}: 7348@ref{GETPID}, @gol 7349@ref{GETLOG} 7350@end table 7351 7352 7353 7354@node GMTIME 7355@section @code{GMTIME} --- Convert time to GMT info 7356@fnindex GMTIME 7357@cindex time, conversion to GMT info 7358 7359@table @asis 7360@item @emph{Description}: 7361Given a system time value @var{TIME} (as provided by the @ref{TIME} 7362intrinsic), fills @var{VALUES} with values extracted from it appropriate 7363to the UTC time zone (Universal Coordinated Time, also known in some 7364countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}. 7365 7366This intrinsic routine is provided for backwards compatibility with 7367GNU Fortran 77. In new code, programmers should consider the use of 7368the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 7369standard. 7370 7371@item @emph{Standard}: 7372GNU extension 7373 7374@item @emph{Class}: 7375Subroutine 7376 7377@item @emph{Syntax}: 7378@code{CALL GMTIME(TIME, VALUES)} 7379 7380@item @emph{Arguments}: 7381@multitable @columnfractions .15 .70 7382@item @var{TIME} @tab An @code{INTEGER} scalar expression 7383corresponding to a system time, with @code{INTENT(IN)}. 7384@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 7385with @code{INTENT(OUT)}. 7386@end multitable 7387 7388@item @emph{Return value}: 7389The elements of @var{VALUES} are assigned as follows: 7390@enumerate 7391@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 7392seconds 7393@item Minutes after the hour, range 0--59 7394@item Hours past midnight, range 0--23 7395@item Day of month, range 1--31 7396@item Number of months since January, range 0--11 7397@item Years since 1900 7398@item Number of days since Sunday, range 0--6 7399@item Days since January 1, range 0--365 7400@item Daylight savings indicator: positive if daylight savings is in 7401effect, zero if not, and negative if the information is not available. 7402@end enumerate 7403 7404@item @emph{See also}: 7405@ref{DATE_AND_TIME}, @gol 7406@ref{CTIME}, @gol 7407@ref{LTIME}, @gol 7408@ref{TIME}, @gol 7409@ref{TIME8} 7410@end table 7411 7412 7413 7414@node HOSTNM 7415@section @code{HOSTNM} --- Get system host name 7416@fnindex HOSTNM 7417@cindex system, host name 7418 7419@table @asis 7420@item @emph{Description}: 7421Retrieves the host name of the system on which the program is running. 7422 7423This intrinsic is provided in both subroutine and function forms; however, 7424only one form can be used in any given program unit. 7425 7426@item @emph{Standard}: 7427GNU extension 7428 7429@item @emph{Class}: 7430Subroutine, function 7431 7432@item @emph{Syntax}: 7433@multitable @columnfractions .80 7434@item @code{CALL HOSTNM(C [, STATUS])} 7435@item @code{STATUS = HOSTNM(NAME)} 7436@end multitable 7437 7438@item @emph{Arguments}: 7439@multitable @columnfractions .15 .70 7440@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind. 7441@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 7442Returns 0 on success, or a system specific error code otherwise. 7443@end multitable 7444 7445@item @emph{Return value}: 7446In either syntax, @var{NAME} is set to the current hostname if it can 7447be obtained, or to a blank string otherwise. 7448 7449@end table 7450 7451 7452 7453@node HUGE 7454@section @code{HUGE} --- Largest number of a kind 7455@fnindex HUGE 7456@cindex limits, largest number 7457@cindex model representation, largest number 7458 7459@table @asis 7460@item @emph{Description}: 7461@code{HUGE(X)} returns the largest number that is not an infinity in 7462the model of the type of @code{X}. 7463 7464@item @emph{Standard}: 7465Fortran 90 and later 7466 7467@item @emph{Class}: 7468Inquiry function 7469 7470@item @emph{Syntax}: 7471@code{RESULT = HUGE(X)} 7472 7473@item @emph{Arguments}: 7474@multitable @columnfractions .15 .70 7475@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}. 7476@end multitable 7477 7478@item @emph{Return value}: 7479The return value is of the same type and kind as @var{X} 7480 7481@item @emph{Example}: 7482@smallexample 7483program test_huge_tiny 7484 print *, huge(0), huge(0.0), huge(0.0d0) 7485 print *, tiny(0.0), tiny(0.0d0) 7486end program test_huge_tiny 7487@end smallexample 7488@end table 7489 7490 7491 7492@node HYPOT 7493@section @code{HYPOT} --- Euclidean distance function 7494@fnindex HYPOT 7495@cindex Euclidean distance 7496 7497@table @asis 7498@item @emph{Description}: 7499@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to 7500@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow. 7501 7502@item @emph{Standard}: 7503Fortran 2008 and later 7504 7505@item @emph{Class}: 7506Elemental function 7507 7508@item @emph{Syntax}: 7509@code{RESULT = HYPOT(X, Y)} 7510 7511@item @emph{Arguments}: 7512@multitable @columnfractions .15 .70 7513@item @var{X} @tab The type shall be @code{REAL}. 7514@item @var{Y} @tab The type and kind type parameter shall be the same as 7515@var{X}. 7516@end multitable 7517 7518@item @emph{Return value}: 7519The return value has the same type and kind type parameter as @var{X}. 7520 7521@item @emph{Example}: 7522@smallexample 7523program test_hypot 7524 real(4) :: x = 1.e0_4, y = 0.5e0_4 7525 x = hypot(x,y) 7526end program test_hypot 7527@end smallexample 7528@end table 7529 7530 7531 7532@node IACHAR 7533@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence 7534@fnindex IACHAR 7535@cindex @acronym{ASCII} collating sequence 7536@cindex collating sequence, @acronym{ASCII} 7537@cindex conversion, to integer 7538 7539@table @asis 7540@item @emph{Description}: 7541@code{IACHAR(C)} returns the code for the @acronym{ASCII} character 7542in the first character position of @code{C}. 7543 7544@item @emph{Standard}: 7545Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 7546 7547@item @emph{Class}: 7548Elemental function 7549 7550@item @emph{Syntax}: 7551@code{RESULT = IACHAR(C [, KIND])} 7552 7553@item @emph{Arguments}: 7554@multitable @columnfractions .15 .70 7555@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 7556@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7557expression indicating the kind parameter of the result. 7558@end multitable 7559 7560@item @emph{Return value}: 7561The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7562@var{KIND} is absent, the return value is of default integer kind. 7563 7564@item @emph{Example}: 7565@smallexample 7566program test_iachar 7567 integer i 7568 i = iachar(' ') 7569end program test_iachar 7570@end smallexample 7571 7572@item @emph{Note}: 7573See @ref{ICHAR} for a discussion of converting between numerical values 7574and formatted string representations. 7575 7576@item @emph{See also}: 7577@ref{ACHAR}, @gol 7578@ref{CHAR}, @gol 7579@ref{ICHAR} 7580@end table 7581 7582 7583 7584@node IALL 7585@section @code{IALL} --- Bitwise AND of array elements 7586@fnindex IALL 7587@cindex array, AND 7588@cindex bits, AND of array elements 7589 7590@table @asis 7591@item @emph{Description}: 7592Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM} 7593if the corresponding element in @var{MASK} is @code{TRUE}. 7594 7595@item @emph{Standard}: 7596Fortran 2008 and later 7597 7598@item @emph{Class}: 7599Transformational function 7600 7601@item @emph{Syntax}: 7602@multitable @columnfractions .80 7603@item @code{RESULT = IALL(ARRAY[, MASK])} 7604@item @code{RESULT = IALL(ARRAY, DIM[, MASK])} 7605@end multitable 7606 7607@item @emph{Arguments}: 7608@multitable @columnfractions .15 .70 7609@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7610@item @var{DIM} @tab (Optional) shall be a scalar of type 7611@code{INTEGER} with a value in the range from 1 to n, where n 7612equals the rank of @var{ARRAY}. 7613@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7614and either be a scalar or an array of the same shape as @var{ARRAY}. 7615@end multitable 7616 7617@item @emph{Return value}: 7618The result is of the same type as @var{ARRAY}. 7619 7620If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in 7621@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7622the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7623dimension @var{DIM} dropped is returned. 7624 7625@item @emph{Example}: 7626@smallexample 7627PROGRAM test_iall 7628 INTEGER(1) :: a(2) 7629 7630 a(1) = b'00100100' 7631 a(2) = b'01101010' 7632 7633 ! prints 00100000 7634 PRINT '(b8.8)', IALL(a) 7635END PROGRAM 7636@end smallexample 7637 7638@item @emph{See also}: 7639@ref{IANY}, @gol 7640@ref{IPARITY}, @gol 7641@ref{IAND} 7642@end table 7643 7644 7645 7646@node IAND 7647@section @code{IAND} --- Bitwise logical and 7648@fnindex IAND 7649@fnindex BIAND 7650@fnindex IIAND 7651@fnindex JIAND 7652@fnindex KIAND 7653@cindex bitwise logical and 7654@cindex logical and, bitwise 7655 7656@table @asis 7657@item @emph{Description}: 7658Bitwise logical @code{AND}. 7659 7660@item @emph{Standard}: 7661Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 7662 7663@item @emph{Class}: 7664Elemental function 7665 7666@item @emph{Syntax}: 7667@code{RESULT = IAND(I, J)} 7668 7669@item @emph{Arguments}: 7670@multitable @columnfractions .15 .70 7671@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 7672@item @var{J} @tab The type shall be @code{INTEGER} with the same 7673kind type parameter as @var{I} or a boz-literal-constant. 7674@var{I} and @var{J} shall not both be boz-literal-constants. 7675@end multitable 7676 7677@item @emph{Return value}: 7678The return type is @code{INTEGER} with the kind type parameter of the 7679arguments. 7680A boz-literal-constant is converted to an @code{INTEGER} with the kind 7681type parameter of the other argument as-if a call to @ref{INT} occurred. 7682 7683@item @emph{Example}: 7684@smallexample 7685PROGRAM test_iand 7686 INTEGER :: a, b 7687 DATA a / Z'F' /, b / Z'3' / 7688 WRITE (*,*) IAND(a, b) 7689END PROGRAM 7690@end smallexample 7691 7692@item @emph{Specific names}: 7693@multitable @columnfractions .20 .20 .20 .25 7694@item Name @tab Argument @tab Return type @tab Standard 7695@item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7696@item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7697@item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7698@item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7699@item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7700@end multitable 7701 7702@item @emph{See also}: 7703@ref{IOR}, @gol 7704@ref{IEOR}, @gol 7705@ref{IBITS}, @gol 7706@ref{IBSET}, @gol 7707@ref{IBCLR}, @gol 7708@ref{NOT} 7709@end table 7710 7711 7712 7713@node IANY 7714@section @code{IANY} --- Bitwise OR of array elements 7715@fnindex IANY 7716@cindex array, OR 7717@cindex bits, OR of array elements 7718 7719@table @asis 7720@item @emph{Description}: 7721Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along 7722dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 7723 7724@item @emph{Standard}: 7725Fortran 2008 and later 7726 7727@item @emph{Class}: 7728Transformational function 7729 7730@item @emph{Syntax}: 7731@multitable @columnfractions .80 7732@item @code{RESULT = IANY(ARRAY[, MASK])} 7733@item @code{RESULT = IANY(ARRAY, DIM[, MASK])} 7734@end multitable 7735 7736@item @emph{Arguments}: 7737@multitable @columnfractions .15 .70 7738@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7739@item @var{DIM} @tab (Optional) shall be a scalar of type 7740@code{INTEGER} with a value in the range from 1 to n, where n 7741equals the rank of @var{ARRAY}. 7742@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7743and either be a scalar or an array of the same shape as @var{ARRAY}. 7744@end multitable 7745 7746@item @emph{Return value}: 7747The result is of the same type as @var{ARRAY}. 7748 7749If @var{DIM} is absent, a scalar with the bitwise OR of all elements in 7750@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7751the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7752dimension @var{DIM} dropped is returned. 7753 7754@item @emph{Example}: 7755@smallexample 7756PROGRAM test_iany 7757 INTEGER(1) :: a(2) 7758 7759 a(1) = b'00100100' 7760 a(2) = b'01101010' 7761 7762 ! prints 01101110 7763 PRINT '(b8.8)', IANY(a) 7764END PROGRAM 7765@end smallexample 7766 7767@item @emph{See also}: 7768@ref{IPARITY}, @gol 7769@ref{IALL}, @gol 7770@ref{IOR} 7771@end table 7772 7773 7774 7775@node IARGC 7776@section @code{IARGC} --- Get the number of command line arguments 7777@fnindex IARGC 7778@cindex command-line arguments 7779@cindex command-line arguments, number of 7780@cindex arguments, to program 7781 7782@table @asis 7783@item @emph{Description}: 7784@code{IARGC} returns the number of arguments passed on the 7785command line when the containing program was invoked. 7786 7787This intrinsic routine is provided for backwards compatibility with 7788GNU Fortran 77. In new code, programmers should consider the use of 7789the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 7790standard. 7791 7792@item @emph{Standard}: 7793GNU extension 7794 7795@item @emph{Class}: 7796Function 7797 7798@item @emph{Syntax}: 7799@code{RESULT = IARGC()} 7800 7801@item @emph{Arguments}: 7802None 7803 7804@item @emph{Return value}: 7805The number of command line arguments, type @code{INTEGER(4)}. 7806 7807@item @emph{Example}: 7808See @ref{GETARG} 7809 7810@item @emph{See also}: 7811GNU Fortran 77 compatibility subroutine: @gol 7812@ref{GETARG} @gol 7813Fortran 2003 functions and subroutines: @gol 7814@ref{GET_COMMAND}, @gol 7815@ref{GET_COMMAND_ARGUMENT}, @gol 7816@ref{COMMAND_ARGUMENT_COUNT} 7817@end table 7818 7819 7820 7821@node IBCLR 7822@section @code{IBCLR} --- Clear bit 7823@fnindex IBCLR 7824@fnindex BBCLR 7825@fnindex IIBCLR 7826@fnindex JIBCLR 7827@fnindex KIBCLR 7828@cindex bits, unset 7829@cindex bits, clear 7830 7831@table @asis 7832@item @emph{Description}: 7833@code{IBCLR} returns the value of @var{I} with the bit at position 7834@var{POS} set to zero. 7835 7836@item @emph{Standard}: 7837Fortran 90 and later, has overloads that are GNU extensions 7838 7839@item @emph{Class}: 7840Elemental function 7841 7842@item @emph{Syntax}: 7843@code{RESULT = IBCLR(I, POS)} 7844 7845@item @emph{Arguments}: 7846@multitable @columnfractions .15 .70 7847@item @var{I} @tab The type shall be @code{INTEGER}. 7848@item @var{POS} @tab The type shall be @code{INTEGER}. 7849@end multitable 7850 7851@item @emph{Return value}: 7852The return value is of type @code{INTEGER} and of the same kind as 7853@var{I}. 7854 7855@item @emph{Specific names}: 7856@multitable @columnfractions .20 .20 .20 .25 7857@item Name @tab Argument @tab Return type @tab Standard 7858@item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7859@item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7860@item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7861@item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7862@item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7863@end multitable 7864 7865@item @emph{See also}: 7866@ref{IBITS}, @gol 7867@ref{IBSET}, @gol 7868@ref{IAND}, @gol 7869@ref{IOR}, @gol 7870@ref{IEOR}, @gol 7871@ref{MVBITS} 7872@end table 7873 7874 7875 7876@node IBITS 7877@section @code{IBITS} --- Bit extraction 7878@fnindex IBITS 7879@fnindex BBITS 7880@fnindex IIBITS 7881@fnindex JIBITS 7882@fnindex KIBITS 7883@cindex bits, get 7884@cindex bits, extract 7885 7886@table @asis 7887@item @emph{Description}: 7888@code{IBITS} extracts a field of length @var{LEN} from @var{I}, 7889starting from bit position @var{POS} and extending left for @var{LEN} 7890bits. The result is right-justified and the remaining bits are 7891zeroed. The value of @code{POS+LEN} must be less than or equal to the 7892value @code{BIT_SIZE(I)}. 7893 7894@item @emph{Standard}: 7895Fortran 90 and later, has overloads that are GNU extensions 7896 7897@item @emph{Class}: 7898Elemental function 7899 7900@item @emph{Syntax}: 7901@code{RESULT = IBITS(I, POS, LEN)} 7902 7903@item @emph{Arguments}: 7904@multitable @columnfractions .15 .70 7905@item @var{I} @tab The type shall be @code{INTEGER}. 7906@item @var{POS} @tab The type shall be @code{INTEGER}. 7907@item @var{LEN} @tab The type shall be @code{INTEGER}. 7908@end multitable 7909 7910@item @emph{Return value}: 7911The return value is of type @code{INTEGER} and of the same kind as 7912@var{I}. 7913 7914@item @emph{Specific names}: 7915@multitable @columnfractions .20 .20 .20 .25 7916@item Name @tab Argument @tab Return type @tab Standard 7917@item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7918@item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7919@item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7920@item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7921@item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7922@end multitable 7923 7924@item @emph{See also}: 7925@ref{BIT_SIZE}, @gol 7926@ref{IBCLR}, @gol 7927@ref{IBSET}, @gol 7928@ref{IAND}, @gol 7929@ref{IOR}, @gol 7930@ref{IEOR} 7931@end table 7932 7933 7934 7935@node IBSET 7936@section @code{IBSET} --- Set bit 7937@fnindex IBSET 7938@fnindex BBSET 7939@fnindex IIBSET 7940@fnindex JIBSET 7941@fnindex KIBSET 7942@cindex bits, set 7943 7944@table @asis 7945@item @emph{Description}: 7946@code{IBSET} returns the value of @var{I} with the bit at position 7947@var{POS} set to one. 7948 7949@item @emph{Standard}: 7950Fortran 90 and later, has overloads that are GNU extensions 7951 7952@item @emph{Class}: 7953Elemental function 7954 7955@item @emph{Syntax}: 7956@code{RESULT = IBSET(I, POS)} 7957 7958@item @emph{Arguments}: 7959@multitable @columnfractions .15 .70 7960@item @var{I} @tab The type shall be @code{INTEGER}. 7961@item @var{POS} @tab The type shall be @code{INTEGER}. 7962@end multitable 7963 7964@item @emph{Return value}: 7965The return value is of type @code{INTEGER} and of the same kind as 7966@var{I}. 7967 7968@item @emph{Specific names}: 7969@multitable @columnfractions .20 .20 .20 .25 7970@item Name @tab Argument @tab Return type @tab Standard 7971@item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 7972@item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7973@item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7974@item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7975@item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7976@end multitable 7977 7978@item @emph{See also}: 7979@ref{IBCLR}, @gol 7980@ref{IBITS}, @gol 7981@ref{IAND}, @gol 7982@ref{IOR}, @gol 7983@ref{IEOR}, @gol 7984@ref{MVBITS} 7985@end table 7986 7987 7988 7989@node ICHAR 7990@section @code{ICHAR} --- Character-to-integer conversion function 7991@fnindex ICHAR 7992@cindex conversion, to integer 7993 7994@table @asis 7995@item @emph{Description}: 7996@code{ICHAR(C)} returns the code for the character in the first character 7997position of @code{C} in the system's native character set. 7998The correspondence between characters and their codes is not necessarily 7999the same across different GNU Fortran implementations. 8000 8001@item @emph{Standard}: 8002Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8003 8004@item @emph{Class}: 8005Elemental function 8006 8007@item @emph{Syntax}: 8008@code{RESULT = ICHAR(C [, KIND])} 8009 8010@item @emph{Arguments}: 8011@multitable @columnfractions .15 .70 8012@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 8013@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8014expression indicating the kind parameter of the result. 8015@end multitable 8016 8017@item @emph{Return value}: 8018The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8019@var{KIND} is absent, the return value is of default integer kind. 8020 8021@item @emph{Example}: 8022@smallexample 8023program test_ichar 8024 integer i 8025 i = ichar(' ') 8026end program test_ichar 8027@end smallexample 8028 8029@item @emph{Specific names}: 8030@multitable @columnfractions .20 .20 .20 .25 8031@item Name @tab Argument @tab Return type @tab Standard 8032@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later 8033@end multitable 8034 8035@item @emph{Note}: 8036No intrinsic exists to convert between a numeric value and a formatted 8037character string representation -- for instance, given the 8038@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or 8039@code{REAL} value with the value 154, or vice versa. Instead, this 8040functionality is provided by internal-file I/O, as in the following 8041example: 8042@smallexample 8043program read_val 8044 integer value 8045 character(len=10) string, string2 8046 string = '154' 8047 8048 ! Convert a string to a numeric value 8049 read (string,'(I10)') value 8050 print *, value 8051 8052 ! Convert a value to a formatted string 8053 write (string2,'(I10)') value 8054 print *, string2 8055end program read_val 8056@end smallexample 8057 8058@item @emph{See also}: 8059@ref{ACHAR}, @gol 8060@ref{CHAR}, @gol 8061@ref{IACHAR} 8062@end table 8063 8064 8065 8066@node IDATE 8067@section @code{IDATE} --- Get current local time subroutine (day/month/year) 8068@fnindex IDATE 8069@cindex date, current 8070@cindex current date 8071 8072@table @asis 8073@item @emph{Description}: 8074@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the 8075current local time. The day (in the range 1-31), month (in the range 1-12), 8076and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively. 8077The year has four significant digits. 8078 8079This intrinsic routine is provided for backwards compatibility with 8080GNU Fortran 77. In new code, programmers should consider the use of 8081the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 8082standard. 8083 8084@item @emph{Standard}: 8085GNU extension 8086 8087@item @emph{Class}: 8088Subroutine 8089 8090@item @emph{Syntax}: 8091@code{CALL IDATE(VALUES)} 8092 8093@item @emph{Arguments}: 8094@multitable @columnfractions .15 .70 8095@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and 8096the kind shall be the default integer kind. 8097@end multitable 8098 8099@item @emph{Return value}: 8100Does not return anything. 8101 8102@item @emph{Example}: 8103@smallexample 8104program test_idate 8105 integer, dimension(3) :: tarray 8106 call idate(tarray) 8107 print *, tarray(1) 8108 print *, tarray(2) 8109 print *, tarray(3) 8110end program test_idate 8111@end smallexample 8112 8113@item @emph{See also}: 8114@ref{DATE_AND_TIME} 8115@end table 8116 8117 8118@node IEOR 8119@section @code{IEOR} --- Bitwise logical exclusive or 8120@fnindex IEOR 8121@fnindex BIEOR 8122@fnindex IIEOR 8123@fnindex JIEOR 8124@fnindex KIEOR 8125@cindex bitwise logical exclusive or 8126@cindex logical exclusive or, bitwise 8127 8128@table @asis 8129@item @emph{Description}: 8130@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and 8131@var{J}. 8132 8133@item @emph{Standard}: 8134Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 8135 8136@item @emph{Class}: 8137Elemental function 8138 8139@item @emph{Syntax}: 8140@code{RESULT = IEOR(I, J)} 8141 8142@item @emph{Arguments}: 8143@multitable @columnfractions .15 .70 8144@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 8145@item @var{J} @tab The type shall be @code{INTEGER} with the same 8146kind type parameter as @var{I} or a boz-literal-constant. 8147@var{I} and @var{J} shall not both be boz-literal-constants. 8148@end multitable 8149 8150@item @emph{Return value}: 8151The return type is @code{INTEGER} with the kind type parameter of the 8152arguments. 8153A boz-literal-constant is converted to an @code{INTEGER} with the kind 8154type parameter of the other argument as-if a call to @ref{INT} occurred. 8155 8156@item @emph{Specific names}: 8157@multitable @columnfractions .20 .20 .20 .25 8158@item Name @tab Argument @tab Return type @tab Standard 8159@item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8160@item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8161@item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8162@item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8163@item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8164@end multitable 8165 8166@item @emph{See also}: 8167@ref{IOR}, @gol 8168@ref{IAND}, @gol 8169@ref{IBITS}, @gol 8170@ref{IBSET}, @gol 8171@ref{IBCLR}, @gol 8172@ref{NOT} 8173@end table 8174 8175 8176 8177@node IERRNO 8178@section @code{IERRNO} --- Get the last system error number 8179@fnindex IERRNO 8180@cindex system, error handling 8181 8182@table @asis 8183@item @emph{Description}: 8184Returns the last system error number, as given by the C @code{errno} 8185variable. 8186 8187@item @emph{Standard}: 8188GNU extension 8189 8190@item @emph{Class}: 8191Function 8192 8193@item @emph{Syntax}: 8194@code{RESULT = IERRNO()} 8195 8196@item @emph{Arguments}: 8197None 8198 8199@item @emph{Return value}: 8200The return value is of type @code{INTEGER} and of the default integer 8201kind. 8202 8203@item @emph{See also}: 8204@ref{PERROR} 8205@end table 8206 8207 8208 8209@node IMAGE_INDEX 8210@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index 8211@fnindex IMAGE_INDEX 8212@cindex coarray, @code{IMAGE_INDEX} 8213@cindex images, cosubscript to image index conversion 8214 8215@table @asis 8216@item @emph{Description}: 8217Returns the image index belonging to a cosubscript. 8218 8219@item @emph{Standard}: 8220Fortran 2008 and later 8221 8222@item @emph{Class}: 8223Inquiry function. 8224 8225@item @emph{Syntax}: 8226@code{RESULT = IMAGE_INDEX(COARRAY, SUB)} 8227 8228@item @emph{Arguments}: 8229@multitable @columnfractions .15 .70 8230@item @var{COARRAY} @tab Coarray of any type. 8231@item @var{SUB} @tab default integer rank-1 array of a size equal to 8232the corank of @var{COARRAY}. 8233@end multitable 8234 8235 8236@item @emph{Return value}: 8237Scalar default integer with the value of the image index which corresponds 8238to the cosubscripts. For invalid cosubscripts the result is zero. 8239 8240@item @emph{Example}: 8241@smallexample 8242INTEGER :: array[2,-1:4,8,*] 8243! Writes 28 (or 0 if there are fewer than 28 images) 8244WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1]) 8245@end smallexample 8246 8247@item @emph{See also}: 8248@ref{THIS_IMAGE}, @gol 8249@ref{NUM_IMAGES} 8250@end table 8251 8252 8253 8254@node INDEX intrinsic 8255@section @code{INDEX} --- Position of a substring within a string 8256@fnindex INDEX 8257@cindex substring position 8258@cindex string, find substring 8259 8260@table @asis 8261@item @emph{Description}: 8262Returns the position of the start of the first occurrence of string 8263@var{SUBSTRING} as a substring in @var{STRING}, counting from one. If 8264@var{SUBSTRING} is not present in @var{STRING}, zero is returned. If 8265the @var{BACK} argument is present and true, the return value is the 8266start of the last occurrence rather than the first. 8267 8268@item @emph{Standard}: 8269Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8270 8271@item @emph{Class}: 8272Elemental function 8273 8274@item @emph{Syntax}: 8275@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])} 8276 8277@item @emph{Arguments}: 8278@multitable @columnfractions .15 .70 8279@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with 8280@code{INTENT(IN)} 8281@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with 8282@code{INTENT(IN)} 8283@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with 8284@code{INTENT(IN)} 8285@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8286expression indicating the kind parameter of the result. 8287@end multitable 8288 8289@item @emph{Return value}: 8290The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8291@var{KIND} is absent, the return value is of default integer kind. 8292 8293@item @emph{Specific names}: 8294@multitable @columnfractions .20 .20 .20 .25 8295@item Name @tab Argument @tab Return type @tab Standard 8296@item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later 8297@end multitable 8298 8299@item @emph{See also}: 8300@ref{SCAN}, @gol 8301@ref{VERIFY} 8302@end table 8303 8304 8305 8306@node INT 8307@section @code{INT} --- Convert to integer type 8308@fnindex INT 8309@fnindex IFIX 8310@fnindex IDINT 8311@cindex conversion, to integer 8312 8313@table @asis 8314@item @emph{Description}: 8315Convert to integer type 8316 8317@item @emph{Standard}: 8318Fortran 77 and later, with boz-literal-constant Fortran 2008 and later. 8319 8320@item @emph{Class}: 8321Elemental function 8322 8323@item @emph{Syntax}: 8324@code{RESULT = INT(A [, KIND))} 8325 8326@item @emph{Arguments}: 8327@multitable @columnfractions .15 .70 8328@item @var{A} @tab Shall be of type @code{INTEGER}, 8329@code{REAL}, or @code{COMPLEX} or or a boz-literal-constant. 8330@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8331expression indicating the kind parameter of the result. 8332@end multitable 8333 8334@item @emph{Return value}: 8335These functions return a @code{INTEGER} variable or array under 8336the following rules: 8337 8338@table @asis 8339@item (A) 8340If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 8341@item (B) 8342If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} 8343equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer 8344whose magnitude is the largest integer that does not exceed the magnitude 8345of @var{A} and whose sign is the same as the sign of @var{A}. 8346@item (C) 8347If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}. 8348@end table 8349 8350@item @emph{Example}: 8351@smallexample 8352program test_int 8353 integer :: i = 42 8354 complex :: z = (-3.7, 1.0) 8355 print *, int(i) 8356 print *, int(z), int(z,8) 8357end program 8358@end smallexample 8359 8360@item @emph{Specific names}: 8361@multitable @columnfractions .20 .20 .20 .25 8362@item Name @tab Argument @tab Return type @tab Standard 8363@item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8364@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8365@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 8366@end multitable 8367 8368@end table 8369 8370 8371@node INT2 8372@section @code{INT2} --- Convert to 16-bit integer type 8373@fnindex INT2 8374@fnindex SHORT 8375@cindex conversion, to integer 8376 8377@table @asis 8378@item @emph{Description}: 8379Convert to a @code{KIND=2} integer type. This is equivalent to the 8380standard @code{INT} intrinsic with an optional argument of 8381@code{KIND=2}, and is only included for backwards compatibility. 8382 8383The @code{SHORT} intrinsic is equivalent to @code{INT2}. 8384 8385@item @emph{Standard}: 8386GNU extension 8387 8388@item @emph{Class}: 8389Elemental function 8390 8391@item @emph{Syntax}: 8392@code{RESULT = INT2(A)} 8393 8394@item @emph{Arguments}: 8395@multitable @columnfractions .15 .70 8396@item @var{A} @tab Shall be of type @code{INTEGER}, 8397@code{REAL}, or @code{COMPLEX}. 8398@end multitable 8399 8400@item @emph{Return value}: 8401The return value is a @code{INTEGER(2)} variable. 8402 8403@item @emph{See also}: 8404@ref{INT}, @gol 8405@ref{INT8}, @gol 8406@ref{LONG} 8407@end table 8408 8409 8410 8411@node INT8 8412@section @code{INT8} --- Convert to 64-bit integer type 8413@fnindex INT8 8414@cindex conversion, to integer 8415 8416@table @asis 8417@item @emph{Description}: 8418Convert to a @code{KIND=8} integer type. This is equivalent to the 8419standard @code{INT} intrinsic with an optional argument of 8420@code{KIND=8}, and is only included for backwards compatibility. 8421 8422@item @emph{Standard}: 8423GNU extension 8424 8425@item @emph{Class}: 8426Elemental function 8427 8428@item @emph{Syntax}: 8429@code{RESULT = INT8(A)} 8430 8431@item @emph{Arguments}: 8432@multitable @columnfractions .15 .70 8433@item @var{A} @tab Shall be of type @code{INTEGER}, 8434@code{REAL}, or @code{COMPLEX}. 8435@end multitable 8436 8437@item @emph{Return value}: 8438The return value is a @code{INTEGER(8)} variable. 8439 8440@item @emph{See also}: 8441@ref{INT}, @gol 8442@ref{INT2}, @gol 8443@ref{LONG} 8444@end table 8445 8446 8447 8448@node IOR 8449@section @code{IOR} --- Bitwise logical or 8450@fnindex IOR 8451@fnindex BIOR 8452@fnindex IIOR 8453@fnindex JIOR 8454@fnindex KIOR 8455@cindex bitwise logical or 8456@cindex logical or, bitwise 8457 8458@table @asis 8459@item @emph{Description}: 8460@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and 8461@var{J}. 8462 8463@item @emph{Standard}: 8464Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions 8465 8466@item @emph{Class}: 8467Elemental function 8468 8469@item @emph{Syntax}: 8470@code{RESULT = IOR(I, J)} 8471 8472@item @emph{Arguments}: 8473@multitable @columnfractions .15 .70 8474@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 8475@item @var{J} @tab The type shall be @code{INTEGER} with the same 8476kind type parameter as @var{I} or a boz-literal-constant. 8477@var{I} and @var{J} shall not both be boz-literal-constants. 8478@end multitable 8479 8480@item @emph{Return value}: 8481The return type is @code{INTEGER} with the kind type parameter of the 8482arguments. 8483A boz-literal-constant is converted to an @code{INTEGER} with the kind 8484type parameter of the other argument as-if a call to @ref{INT} occurred. 8485 8486@item @emph{Specific names}: 8487@multitable @columnfractions .20 .20 .20 .25 8488@item Name @tab Argument @tab Return type @tab Standard 8489@item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8490@item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8491@item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8492@item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8493@item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8494@end multitable 8495 8496@item @emph{See also}: 8497@ref{IEOR}, @gol 8498@ref{IAND}, @gol 8499@ref{IBITS}, @gol 8500@ref{IBSET}, @gol 8501@ref{IBCLR}, @gol 8502@ref{NOT} 8503@end table 8504 8505 8506 8507@node IPARITY 8508@section @code{IPARITY} --- Bitwise XOR of array elements 8509@fnindex IPARITY 8510@cindex array, parity 8511@cindex array, XOR 8512@cindex bits, XOR of array elements 8513 8514@table @asis 8515@item @emph{Description}: 8516Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along 8517dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 8518 8519@item @emph{Standard}: 8520Fortran 2008 and later 8521 8522@item @emph{Class}: 8523Transformational function 8524 8525@item @emph{Syntax}: 8526@multitable @columnfractions .80 8527@item @code{RESULT = IPARITY(ARRAY[, MASK])} 8528@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])} 8529@end multitable 8530 8531@item @emph{Arguments}: 8532@multitable @columnfractions .15 .70 8533@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 8534@item @var{DIM} @tab (Optional) shall be a scalar of type 8535@code{INTEGER} with a value in the range from 1 to n, where n 8536equals the rank of @var{ARRAY}. 8537@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 8538and either be a scalar or an array of the same shape as @var{ARRAY}. 8539@end multitable 8540 8541@item @emph{Return value}: 8542The result is of the same type as @var{ARRAY}. 8543 8544If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in 8545@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 8546the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 8547dimension @var{DIM} dropped is returned. 8548 8549@item @emph{Example}: 8550@smallexample 8551PROGRAM test_iparity 8552 INTEGER(1) :: a(2) 8553 8554 a(1) = int(b'00100100', 1) 8555 a(2) = int(b'01101010', 1) 8556 8557 ! prints 01001110 8558 PRINT '(b8.8)', IPARITY(a) 8559END PROGRAM 8560@end smallexample 8561 8562@item @emph{See also}: 8563@ref{IANY}, @gol 8564@ref{IALL}, @gol 8565@ref{IEOR}, @gol 8566@ref{PARITY} 8567@end table 8568 8569 8570 8571@node IRAND 8572@section @code{IRAND} --- Integer pseudo-random number 8573@fnindex IRAND 8574@cindex random number generation 8575 8576@table @asis 8577@item @emph{Description}: 8578@code{IRAND(FLAG)} returns a pseudo-random number from a uniform 8579distribution between 0 and a system-dependent limit (which is in most 8580cases 2147483647). If @var{FLAG} is 0, the next number 8581in the current sequence is returned; if @var{FLAG} is 1, the generator 8582is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 8583it is used as a new seed with @code{SRAND}. 8584 8585This intrinsic routine is provided for backwards compatibility with 8586GNU Fortran 77. It implements a simple modulo generator as provided 8587by @command{g77}. For new code, one should consider the use of 8588@ref{RANDOM_NUMBER} as it implements a superior algorithm. 8589 8590@item @emph{Standard}: 8591GNU extension 8592 8593@item @emph{Class}: 8594Function 8595 8596@item @emph{Syntax}: 8597@code{RESULT = IRAND(I)} 8598 8599@item @emph{Arguments}: 8600@multitable @columnfractions .15 .70 8601@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 8602@end multitable 8603 8604@item @emph{Return value}: 8605The return value is of @code{INTEGER(kind=4)} type. 8606 8607@item @emph{Example}: 8608@smallexample 8609program test_irand 8610 integer,parameter :: seed = 86456 8611 8612 call srand(seed) 8613 print *, irand(), irand(), irand(), irand() 8614 print *, irand(seed), irand(), irand(), irand() 8615end program test_irand 8616@end smallexample 8617 8618@end table 8619 8620 8621 8622@node IS_CONTIGUOUS 8623@section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous 8624@fnindex IS_IOSTAT_EOR 8625@cindex array, contiguity 8626 8627@table @asis 8628@item @emph{Description}: 8629@code{IS_CONTIGUOUS} tests whether an array is contiguous. 8630 8631@item @emph{Standard}: 8632Fortran 2008 and later 8633 8634@item @emph{Class}: 8635Inquiry function 8636 8637@item @emph{Syntax}: 8638@code{RESULT = IS_CONTIGUOUS(ARRAY)} 8639 8640@item @emph{Arguments}: 8641@multitable @columnfractions .15 .70 8642@item @var{ARRAY} @tab Shall be an array of any type. 8643@end multitable 8644 8645@item @emph{Return value}: 8646Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8647@var{ARRAY} is contiguous and false otherwise. 8648 8649@item @emph{Example}: 8650@smallexample 8651program test 8652 integer :: a(10) 8653 a = [1,2,3,4,5,6,7,8,9,10] 8654 call sub (a) ! every element, is contiguous 8655 call sub (a(::2)) ! every other element, is noncontiguous 8656contains 8657 subroutine sub (x) 8658 integer :: x(:) 8659 if (is_contiguous (x)) then 8660 write (*,*) 'X is contiguous' 8661 else 8662 write (*,*) 'X is not contiguous' 8663 end if 8664 end subroutine sub 8665end program test 8666@end smallexample 8667@end table 8668 8669 8670 8671@node IS_IOSTAT_END 8672@section @code{IS_IOSTAT_END} --- Test for end-of-file value 8673@fnindex IS_IOSTAT_END 8674@cindex @code{IOSTAT}, end of file 8675 8676@table @asis 8677@item @emph{Description}: 8678@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O 8679status ``end of file''. The function is equivalent to comparing the variable 8680with the @code{IOSTAT_END} parameter of the intrinsic module 8681@code{ISO_FORTRAN_ENV}. 8682 8683@item @emph{Standard}: 8684Fortran 2003 and later 8685 8686@item @emph{Class}: 8687Elemental function 8688 8689@item @emph{Syntax}: 8690@code{RESULT = IS_IOSTAT_END(I)} 8691 8692@item @emph{Arguments}: 8693@multitable @columnfractions .15 .70 8694@item @var{I} @tab Shall be of the type @code{INTEGER}. 8695@end multitable 8696 8697@item @emph{Return value}: 8698Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8699@var{I} has the value which indicates an end of file condition for 8700@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8701 8702@item @emph{Example}: 8703@smallexample 8704PROGRAM iostat 8705 IMPLICIT NONE 8706 INTEGER :: stat, i 8707 OPEN(88, FILE='test.dat') 8708 READ(88, *, IOSTAT=stat) i 8709 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE' 8710END PROGRAM 8711@end smallexample 8712@end table 8713 8714 8715 8716@node IS_IOSTAT_EOR 8717@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value 8718@fnindex IS_IOSTAT_EOR 8719@cindex @code{IOSTAT}, end of record 8720 8721@table @asis 8722@item @emph{Description}: 8723@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O 8724status ``end of record''. The function is equivalent to comparing the 8725variable with the @code{IOSTAT_EOR} parameter of the intrinsic module 8726@code{ISO_FORTRAN_ENV}. 8727 8728@item @emph{Standard}: 8729Fortran 2003 and later 8730 8731@item @emph{Class}: 8732Elemental function 8733 8734@item @emph{Syntax}: 8735@code{RESULT = IS_IOSTAT_EOR(I)} 8736 8737@item @emph{Arguments}: 8738@multitable @columnfractions .15 .70 8739@item @var{I} @tab Shall be of the type @code{INTEGER}. 8740@end multitable 8741 8742@item @emph{Return value}: 8743Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8744@var{I} has the value which indicates an end of file condition for 8745@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8746 8747@item @emph{Example}: 8748@smallexample 8749PROGRAM iostat 8750 IMPLICIT NONE 8751 INTEGER :: stat, i(50) 8752 OPEN(88, FILE='test.dat', FORM='UNFORMATTED') 8753 READ(88, IOSTAT=stat) i 8754 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD' 8755END PROGRAM 8756@end smallexample 8757@end table 8758 8759 8760@node ISATTY 8761@section @code{ISATTY} --- Whether a unit is a terminal device. 8762@fnindex ISATTY 8763@cindex system, terminal 8764 8765@table @asis 8766@item @emph{Description}: 8767Determine whether a unit is connected to a terminal device. 8768 8769@item @emph{Standard}: 8770GNU extension 8771 8772@item @emph{Class}: 8773Function 8774 8775@item @emph{Syntax}: 8776@code{RESULT = ISATTY(UNIT)} 8777 8778@item @emph{Arguments}: 8779@multitable @columnfractions .15 .70 8780@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 8781@end multitable 8782 8783@item @emph{Return value}: 8784Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal 8785device, @code{.FALSE.} otherwise. 8786 8787@item @emph{Example}: 8788@smallexample 8789PROGRAM test_isatty 8790 INTEGER(kind=1) :: unit 8791 DO unit = 1, 10 8792 write(*,*) isatty(unit=unit) 8793 END DO 8794END PROGRAM 8795@end smallexample 8796@item @emph{See also}: 8797@ref{TTYNAM} 8798@end table 8799 8800 8801 8802@node ISHFT 8803@section @code{ISHFT} --- Shift bits 8804@fnindex ISHFT 8805@fnindex BSHFT 8806@fnindex IISHFT 8807@fnindex JISHFT 8808@fnindex KISHFT 8809@cindex bits, shift 8810 8811@table @asis 8812@item @emph{Description}: 8813@code{ISHFT} returns a value corresponding to @var{I} with all of the 8814bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than 8815zero corresponds to a left shift, a value of zero corresponds to no 8816shift, and a value less than zero corresponds to a right shift. If the 8817absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the 8818value is undefined. Bits shifted out from the left end or right end are 8819lost; zeros are shifted in from the opposite end. 8820 8821@item @emph{Standard}: 8822Fortran 90 and later, has overloads that are GNU extensions 8823 8824@item @emph{Class}: 8825Elemental function 8826 8827@item @emph{Syntax}: 8828@code{RESULT = ISHFT(I, SHIFT)} 8829 8830@item @emph{Arguments}: 8831@multitable @columnfractions .15 .70 8832@item @var{I} @tab The type shall be @code{INTEGER}. 8833@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8834@end multitable 8835 8836@item @emph{Return value}: 8837The return value is of type @code{INTEGER} and of the same kind as 8838@var{I}. 8839 8840@item @emph{Specific names}: 8841@multitable @columnfractions .20 .20 .20 .25 8842@item Name @tab Argument @tab Return type @tab Standard 8843@item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8844@item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8845@item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8846@item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8847@item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8848@end multitable 8849 8850@item @emph{See also}: 8851@ref{ISHFTC} 8852@end table 8853 8854 8855 8856@node ISHFTC 8857@section @code{ISHFTC} --- Shift bits circularly 8858@fnindex ISHFTC 8859@fnindex BSHFTC 8860@fnindex IISHFTC 8861@fnindex JISHFTC 8862@fnindex KISHFTC 8863@cindex bits, shift circular 8864 8865@table @asis 8866@item @emph{Description}: 8867@code{ISHFTC} returns a value corresponding to @var{I} with the 8868rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that 8869is, bits shifted out one end are shifted into the opposite end. A value 8870of @var{SHIFT} greater than zero corresponds to a left shift, a value of 8871zero corresponds to no shift, and a value less than zero corresponds to 8872a right shift. The absolute value of @var{SHIFT} must be less than 8873@var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be 8874equivalent to @code{BIT_SIZE(I)}. 8875 8876@item @emph{Standard}: 8877Fortran 90 and later, has overloads that are GNU extensions 8878 8879@item @emph{Class}: 8880Elemental function 8881 8882@item @emph{Syntax}: 8883@code{RESULT = ISHFTC(I, SHIFT [, SIZE])} 8884 8885@item @emph{Arguments}: 8886@multitable @columnfractions .15 .70 8887@item @var{I} @tab The type shall be @code{INTEGER}. 8888@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8889@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER}; 8890the value must be greater than zero and less than or equal to 8891@code{BIT_SIZE(I)}. 8892@end multitable 8893 8894@item @emph{Return value}: 8895The return value is of type @code{INTEGER} and of the same kind as 8896@var{I}. 8897 8898@item @emph{Specific names}: 8899@multitable @columnfractions .20 .20 .20 .25 8900@item Name @tab Argument @tab Return type @tab Standard 8901@item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 8902@item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8903@item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8904@item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8905@item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8906@end multitable 8907 8908@item @emph{See also}: 8909@ref{ISHFT} 8910@end table 8911 8912 8913 8914@node ISNAN 8915@section @code{ISNAN} --- Test for a NaN 8916@fnindex ISNAN 8917@cindex IEEE, ISNAN 8918 8919@table @asis 8920@item @emph{Description}: 8921@code{ISNAN} tests whether a floating-point value is an IEEE 8922Not-a-Number (NaN). 8923@item @emph{Standard}: 8924GNU extension 8925 8926@item @emph{Class}: 8927Elemental function 8928 8929@item @emph{Syntax}: 8930@code{ISNAN(X)} 8931 8932@item @emph{Arguments}: 8933@multitable @columnfractions .15 .70 8934@item @var{X} @tab Variable of the type @code{REAL}. 8935 8936@end multitable 8937 8938@item @emph{Return value}: 8939Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE} 8940if @var{X} is a NaN and @code{FALSE} otherwise. 8941 8942@item @emph{Example}: 8943@smallexample 8944program test_nan 8945 implicit none 8946 real :: x 8947 x = -1.0 8948 x = sqrt(x) 8949 if (isnan(x)) stop '"x" is a NaN' 8950end program test_nan 8951@end smallexample 8952@end table 8953 8954 8955 8956@node ITIME 8957@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) 8958@fnindex ITIME 8959@cindex time, current 8960@cindex current time 8961 8962@table @asis 8963@item @emph{Description}: 8964@code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the 8965current local time. The hour (in the range 1-24), minute (in the range 1-60), 8966and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES}, 8967respectively. 8968 8969This intrinsic routine is provided for backwards compatibility with 8970GNU Fortran 77. In new code, programmers should consider the use of 8971the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 8972standard. 8973 8974@item @emph{Standard}: 8975GNU extension 8976 8977@item @emph{Class}: 8978Subroutine 8979 8980@item @emph{Syntax}: 8981@code{CALL ITIME(VALUES)} 8982 8983@item @emph{Arguments}: 8984@multitable @columnfractions .15 .70 8985@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} 8986and the kind shall be the default integer kind. 8987@end multitable 8988 8989@item @emph{Return value}: 8990Does not return anything. 8991 8992 8993@item @emph{Example}: 8994@smallexample 8995program test_itime 8996 integer, dimension(3) :: tarray 8997 call itime(tarray) 8998 print *, tarray(1) 8999 print *, tarray(2) 9000 print *, tarray(3) 9001end program test_itime 9002@end smallexample 9003 9004@item @emph{See also}: 9005@ref{DATE_AND_TIME} 9006@end table 9007 9008 9009 9010@node KILL 9011@section @code{KILL} --- Send a signal to a process 9012@fnindex KILL 9013 9014@table @asis 9015@item @emph{Description}: 9016Sends the signal specified by @var{SIG} to the process @var{PID}. 9017See @code{kill(2)}. 9018 9019This intrinsic is provided in both subroutine and function forms; 9020however, only one form can be used in any given program unit. 9021@item @emph{Standard}: 9022GNU extension 9023 9024@item @emph{Standard}: 9025GNU extension 9026 9027@item @emph{Class}: 9028Subroutine, function 9029 9030@item @emph{Syntax}: 9031@multitable @columnfractions .80 9032@item @code{CALL KILL(PID, SIG [, STATUS])} 9033@item @code{STATUS = KILL(PID, SIG)} 9034@end multitable 9035 9036@item @emph{Arguments}: 9037@multitable @columnfractions .15 .70 9038@item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 9039@item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 9040@item @var{STATUS} @tab [Subroutine](Optional) 9041Shall be a scalar @code{INTEGER}. 9042Returns 0 on success; otherwise a system-specific error code is returned. 9043@item @var{STATUS} @tab [Function] The kind type parameter is that of 9044@code{pid}. 9045Returns 0 on success; otherwise a system-specific error code is returned. 9046@end multitable 9047 9048@item @emph{See also}: 9049@ref{ABORT}, @gol 9050@ref{EXIT} 9051@end table 9052 9053 9054@node KIND 9055@section @code{KIND} --- Kind of an entity 9056@fnindex KIND 9057@cindex kind 9058 9059@table @asis 9060@item @emph{Description}: 9061@code{KIND(X)} returns the kind value of the entity @var{X}. 9062 9063@item @emph{Standard}: 9064Fortran 95 and later 9065 9066@item @emph{Class}: 9067Inquiry function 9068 9069@item @emph{Syntax}: 9070@code{K = KIND(X)} 9071 9072@item @emph{Arguments}: 9073@multitable @columnfractions .15 .70 9074@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER}, 9075@code{REAL}, @code{COMPLEX} or @code{CHARACTER}. It may be scalar or 9076array valued. 9077@end multitable 9078 9079@item @emph{Return value}: 9080The return value is a scalar of type @code{INTEGER} and of the default 9081integer kind. 9082 9083@item @emph{Example}: 9084@smallexample 9085program test_kind 9086 integer,parameter :: kc = kind(' ') 9087 integer,parameter :: kl = kind(.true.) 9088 9089 print *, "The default character kind is ", kc 9090 print *, "The default logical kind is ", kl 9091end program test_kind 9092@end smallexample 9093 9094@end table 9095 9096 9097 9098@node LBOUND 9099@section @code{LBOUND} --- Lower dimension bounds of an array 9100@fnindex LBOUND 9101@cindex array, lower bound 9102 9103@table @asis 9104@item @emph{Description}: 9105Returns the lower bounds of an array, or a single lower bound 9106along the @var{DIM} dimension. 9107@item @emph{Standard}: 9108Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 9109 9110@item @emph{Class}: 9111Inquiry function 9112 9113@item @emph{Syntax}: 9114@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])} 9115 9116@item @emph{Arguments}: 9117@multitable @columnfractions .15 .70 9118@item @var{ARRAY} @tab Shall be an array, of any type. 9119@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 9120@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9121expression indicating the kind parameter of the result. 9122@end multitable 9123 9124@item @emph{Return value}: 9125The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9126@var{KIND} is absent, the return value is of default integer kind. 9127If @var{DIM} is absent, the result is an array of the lower bounds of 9128@var{ARRAY}. If @var{DIM} is present, the result is a scalar 9129corresponding to the lower bound of the array along that dimension. If 9130@var{ARRAY} is an expression rather than a whole array or array 9131structure component, or if it has a zero extent along the relevant 9132dimension, the lower bound is taken to be 1. 9133 9134@item @emph{See also}: 9135@ref{UBOUND}, @gol 9136@ref{LCOBOUND} 9137@end table 9138 9139 9140 9141@node LCOBOUND 9142@section @code{LCOBOUND} --- Lower codimension bounds of an array 9143@fnindex LCOBOUND 9144@cindex coarray, lower bound 9145 9146@table @asis 9147@item @emph{Description}: 9148Returns the lower bounds of a coarray, or a single lower cobound 9149along the @var{DIM} codimension. 9150@item @emph{Standard}: 9151Fortran 2008 and later 9152 9153@item @emph{Class}: 9154Inquiry function 9155 9156@item @emph{Syntax}: 9157@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])} 9158 9159@item @emph{Arguments}: 9160@multitable @columnfractions .15 .70 9161@item @var{ARRAY} @tab Shall be an coarray, of any type. 9162@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 9163@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9164expression indicating the kind parameter of the result. 9165@end multitable 9166 9167@item @emph{Return value}: 9168The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9169@var{KIND} is absent, the return value is of default integer kind. 9170If @var{DIM} is absent, the result is an array of the lower cobounds of 9171@var{COARRAY}. If @var{DIM} is present, the result is a scalar 9172corresponding to the lower cobound of the array along that codimension. 9173 9174@item @emph{See also}: 9175@ref{UCOBOUND}, @gol 9176@ref{LBOUND} 9177@end table 9178 9179 9180 9181@node LEADZ 9182@section @code{LEADZ} --- Number of leading zero bits of an integer 9183@fnindex LEADZ 9184@cindex zero bits 9185 9186@table @asis 9187@item @emph{Description}: 9188@code{LEADZ} returns the number of leading zero bits of an integer. 9189 9190@item @emph{Standard}: 9191Fortran 2008 and later 9192 9193@item @emph{Class}: 9194Elemental function 9195 9196@item @emph{Syntax}: 9197@code{RESULT = LEADZ(I)} 9198 9199@item @emph{Arguments}: 9200@multitable @columnfractions .15 .70 9201@item @var{I} @tab Shall be of type @code{INTEGER}. 9202@end multitable 9203 9204@item @emph{Return value}: 9205The type of the return value is the default @code{INTEGER}. 9206If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 9207 9208@item @emph{Example}: 9209@smallexample 9210PROGRAM test_leadz 9211 WRITE (*,*) BIT_SIZE(1) ! prints 32 9212 WRITE (*,*) LEADZ(1) ! prints 31 9213END PROGRAM 9214@end smallexample 9215 9216@item @emph{See also}: 9217@ref{BIT_SIZE}, @gol 9218@ref{TRAILZ}, @gol 9219@ref{POPCNT}, @gol 9220@ref{POPPAR} 9221@end table 9222 9223 9224 9225@node LEN 9226@section @code{LEN} --- Length of a character entity 9227@fnindex LEN 9228@cindex string, length 9229 9230@table @asis 9231@item @emph{Description}: 9232Returns the length of a character string. If @var{STRING} is an array, 9233the length of an element of @var{STRING} is returned. Note that 9234@var{STRING} need not be defined when this intrinsic is invoked, since 9235only the length, not the content, of @var{STRING} is needed. 9236 9237@item @emph{Standard}: 9238Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 9239 9240@item @emph{Class}: 9241Inquiry function 9242 9243@item @emph{Syntax}: 9244@code{L = LEN(STRING [, KIND])} 9245 9246@item @emph{Arguments}: 9247@multitable @columnfractions .15 .70 9248@item @var{STRING} @tab Shall be a scalar or array of type 9249@code{CHARACTER}, with @code{INTENT(IN)} 9250@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9251expression indicating the kind parameter of the result. 9252@end multitable 9253 9254@item @emph{Return value}: 9255The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9256@var{KIND} is absent, the return value is of default integer kind. 9257 9258 9259@item @emph{Specific names}: 9260@multitable @columnfractions .20 .20 .20 .25 9261@item Name @tab Argument @tab Return type @tab Standard 9262@item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later 9263@end multitable 9264 9265 9266@item @emph{See also}: 9267@ref{LEN_TRIM}, @gol 9268@ref{ADJUSTL}, @gol 9269@ref{ADJUSTR} 9270@end table 9271 9272 9273 9274@node LEN_TRIM 9275@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters 9276@fnindex LEN_TRIM 9277@cindex string, length, without trailing whitespace 9278 9279@table @asis 9280@item @emph{Description}: 9281Returns the length of a character string, ignoring any trailing blanks. 9282 9283@item @emph{Standard}: 9284Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 9285 9286@item @emph{Class}: 9287Elemental function 9288 9289@item @emph{Syntax}: 9290@code{RESULT = LEN_TRIM(STRING [, KIND])} 9291 9292@item @emph{Arguments}: 9293@multitable @columnfractions .15 .70 9294@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9295with @code{INTENT(IN)} 9296@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9297expression indicating the kind parameter of the result. 9298@end multitable 9299 9300@item @emph{Return value}: 9301The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9302@var{KIND} is absent, the return value is of default integer kind. 9303 9304@item @emph{See also}: 9305@ref{LEN}, @gol 9306@ref{ADJUSTL}, @gol 9307@ref{ADJUSTR} 9308@end table 9309 9310 9311 9312@node LGE 9313@section @code{LGE} --- Lexical greater than or equal 9314@fnindex LGE 9315@cindex lexical comparison of strings 9316@cindex string, comparison 9317 9318@table @asis 9319@item @emph{Description}: 9320Determines whether one string is lexically greater than or equal to 9321another string, where the two strings are interpreted as containing 9322ASCII character codes. If the String A and String B are not the same 9323length, the shorter is compared as if spaces were appended to it to form 9324a value that has the same length as the longer. 9325 9326In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9327@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9328operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9329that the latter use the processor's character ordering (which is not 9330ASCII on some targets), whereas the former always use the ASCII 9331ordering. 9332 9333@item @emph{Standard}: 9334Fortran 77 and later 9335 9336@item @emph{Class}: 9337Elemental function 9338 9339@item @emph{Syntax}: 9340@code{RESULT = LGE(STRING_A, STRING_B)} 9341 9342@item @emph{Arguments}: 9343@multitable @columnfractions .15 .70 9344@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9345@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9346@end multitable 9347 9348@item @emph{Return value}: 9349Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.} 9350otherwise, based on the ASCII ordering. 9351 9352@item @emph{Specific names}: 9353@multitable @columnfractions .20 .20 .20 .25 9354@item Name @tab Argument @tab Return type @tab Standard 9355@item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9356@end multitable 9357 9358@item @emph{See also}: 9359@ref{LGT}, @gol 9360@ref{LLE}, @gol 9361@ref{LLT} 9362@end table 9363 9364 9365 9366@node LGT 9367@section @code{LGT} --- Lexical greater than 9368@fnindex LGT 9369@cindex lexical comparison of strings 9370@cindex string, comparison 9371 9372@table @asis 9373@item @emph{Description}: 9374Determines whether one string is lexically greater than another string, 9375where the two strings are interpreted as containing ASCII character 9376codes. If the String A and String B are not the same length, the 9377shorter is compared as if spaces were appended to it to form a value 9378that has the same length as the longer. 9379 9380In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9381@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9382operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9383that the latter use the processor's character ordering (which is not 9384ASCII on some targets), whereas the former always use the ASCII 9385ordering. 9386 9387@item @emph{Standard}: 9388Fortran 77 and later 9389 9390@item @emph{Class}: 9391Elemental function 9392 9393@item @emph{Syntax}: 9394@code{RESULT = LGT(STRING_A, STRING_B)} 9395 9396@item @emph{Arguments}: 9397@multitable @columnfractions .15 .70 9398@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9399@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9400@end multitable 9401 9402@item @emph{Return value}: 9403Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.} 9404otherwise, based on the ASCII ordering. 9405 9406@item @emph{Specific names}: 9407@multitable @columnfractions .20 .20 .20 .25 9408@item Name @tab Argument @tab Return type @tab Standard 9409@item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9410@end multitable 9411 9412@item @emph{See also}: 9413@ref{LGE}, @gol 9414@ref{LLE}, @gol 9415@ref{LLT} 9416@end table 9417 9418 9419 9420@node LINK 9421@section @code{LINK} --- Create a hard link 9422@fnindex LINK 9423@cindex file system, create link 9424@cindex file system, hard link 9425 9426@table @asis 9427@item @emph{Description}: 9428Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null 9429character (@code{CHAR(0)}) can be used to mark the end of the names in 9430@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 9431names are ignored. If the @var{STATUS} argument is supplied, it 9432contains 0 on success or a nonzero error code upon return; see 9433@code{link(2)}. 9434 9435This intrinsic is provided in both subroutine and function forms; 9436however, only one form can be used in any given program unit. 9437 9438@item @emph{Standard}: 9439GNU extension 9440 9441@item @emph{Class}: 9442Subroutine, function 9443 9444@item @emph{Syntax}: 9445@multitable @columnfractions .80 9446@item @code{CALL LINK(PATH1, PATH2 [, STATUS])} 9447@item @code{STATUS = LINK(PATH1, PATH2)} 9448@end multitable 9449 9450@item @emph{Arguments}: 9451@multitable @columnfractions .15 .70 9452@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 9453@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 9454@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 9455@end multitable 9456 9457@item @emph{See also}: 9458@ref{SYMLNK}, @gol 9459@ref{UNLINK} 9460@end table 9461 9462 9463 9464@node LLE 9465@section @code{LLE} --- Lexical less than or equal 9466@fnindex LLE 9467@cindex lexical comparison of strings 9468@cindex string, comparison 9469 9470@table @asis 9471@item @emph{Description}: 9472Determines whether one string is lexically less than or equal to another 9473string, where the two strings are interpreted as containing ASCII 9474character codes. If the String A and String B are not the same length, 9475the shorter is compared as if spaces were appended to it to form a value 9476that has the same length as the longer. 9477 9478In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9479@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9480operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9481that the latter use the processor's character ordering (which is not 9482ASCII on some targets), whereas the former always use the ASCII 9483ordering. 9484 9485@item @emph{Standard}: 9486Fortran 77 and later 9487 9488@item @emph{Class}: 9489Elemental function 9490 9491@item @emph{Syntax}: 9492@code{RESULT = LLE(STRING_A, STRING_B)} 9493 9494@item @emph{Arguments}: 9495@multitable @columnfractions .15 .70 9496@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9497@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9498@end multitable 9499 9500@item @emph{Return value}: 9501Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.} 9502otherwise, based on the ASCII ordering. 9503 9504@item @emph{Specific names}: 9505@multitable @columnfractions .20 .20 .20 .25 9506@item Name @tab Argument @tab Return type @tab Standard 9507@item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9508@end multitable 9509 9510@item @emph{See also}: 9511@ref{LGE}, @gol 9512@ref{LGT}, @gol 9513@ref{LLT} 9514@end table 9515 9516 9517 9518@node LLT 9519@section @code{LLT} --- Lexical less than 9520@fnindex LLT 9521@cindex lexical comparison of strings 9522@cindex string, comparison 9523 9524@table @asis 9525@item @emph{Description}: 9526Determines whether one string is lexically less than another string, 9527where the two strings are interpreted as containing ASCII character 9528codes. If the String A and String B are not the same length, the 9529shorter is compared as if spaces were appended to it to form a value 9530that has the same length as the longer. 9531 9532In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9533@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9534operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9535that the latter use the processor's character ordering (which is not 9536ASCII on some targets), whereas the former always use the ASCII 9537ordering. 9538 9539@item @emph{Standard}: 9540Fortran 77 and later 9541 9542@item @emph{Class}: 9543Elemental function 9544 9545@item @emph{Syntax}: 9546@code{RESULT = LLT(STRING_A, STRING_B)} 9547 9548@item @emph{Arguments}: 9549@multitable @columnfractions .15 .70 9550@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9551@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9552@end multitable 9553 9554@item @emph{Return value}: 9555Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.} 9556otherwise, based on the ASCII ordering. 9557 9558@item @emph{Specific names}: 9559@multitable @columnfractions .20 .20 .20 .25 9560@item Name @tab Argument @tab Return type @tab Standard 9561@item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9562@end multitable 9563 9564@item @emph{See also}: 9565@ref{LGE}, @gol 9566@ref{LGT}, @gol 9567@ref{LLE} 9568@end table 9569 9570 9571 9572@node LNBLNK 9573@section @code{LNBLNK} --- Index of the last non-blank character in a string 9574@fnindex LNBLNK 9575@cindex string, find non-blank character 9576 9577@table @asis 9578@item @emph{Description}: 9579Returns the length of a character string, ignoring any trailing blanks. 9580This is identical to the standard @code{LEN_TRIM} intrinsic, and is only 9581included for backwards compatibility. 9582 9583@item @emph{Standard}: 9584GNU extension 9585 9586@item @emph{Class}: 9587Elemental function 9588 9589@item @emph{Syntax}: 9590@code{RESULT = LNBLNK(STRING)} 9591 9592@item @emph{Arguments}: 9593@multitable @columnfractions .15 .70 9594@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9595with @code{INTENT(IN)} 9596@end multitable 9597 9598@item @emph{Return value}: 9599The return value is of @code{INTEGER(kind=4)} type. 9600 9601@item @emph{See also}: 9602@ref{INDEX intrinsic}, @gol 9603@ref{LEN_TRIM} 9604@end table 9605 9606 9607 9608@node LOC 9609@section @code{LOC} --- Returns the address of a variable 9610@fnindex LOC 9611@cindex location of a variable in memory 9612 9613@table @asis 9614@item @emph{Description}: 9615@code{LOC(X)} returns the address of @var{X} as an integer. 9616 9617@item @emph{Standard}: 9618GNU extension 9619 9620@item @emph{Class}: 9621Inquiry function 9622 9623@item @emph{Syntax}: 9624@code{RESULT = LOC(X)} 9625 9626@item @emph{Arguments}: 9627@multitable @columnfractions .15 .70 9628@item @var{X} @tab Variable of any type. 9629@end multitable 9630 9631@item @emph{Return value}: 9632The return value is of type @code{INTEGER}, with a @code{KIND} 9633corresponding to the size (in bytes) of a memory address on the target 9634machine. 9635 9636@item @emph{Example}: 9637@smallexample 9638program test_loc 9639 integer :: i 9640 real :: r 9641 i = loc(r) 9642 print *, i 9643end program test_loc 9644@end smallexample 9645@end table 9646 9647 9648 9649@node LOG 9650@section @code{LOG} --- Natural logarithm function 9651@fnindex LOG 9652@fnindex ALOG 9653@fnindex DLOG 9654@fnindex CLOG 9655@fnindex ZLOG 9656@fnindex CDLOG 9657@cindex exponential function, inverse 9658@cindex logarithm function 9659@cindex natural logarithm function 9660 9661@table @asis 9662@item @emph{Description}: 9663@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the 9664logarithm to the base @math{e}. 9665 9666@item @emph{Standard}: 9667Fortran 77 and later, has GNU extensions 9668 9669@item @emph{Class}: 9670Elemental function 9671 9672@item @emph{Syntax}: 9673@code{RESULT = LOG(X)} 9674 9675@item @emph{Arguments}: 9676@multitable @columnfractions .15 .70 9677@item @var{X} @tab The type shall be @code{REAL} or 9678@code{COMPLEX}. 9679@end multitable 9680 9681@item @emph{Return value}: 9682The return value is of type @code{REAL} or @code{COMPLEX}. 9683The kind type parameter is the same as @var{X}. 9684If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range 9685@math{-\pi < \omega \leq \pi}. 9686 9687@item @emph{Example}: 9688@smallexample 9689program test_log 9690 real(8) :: x = 2.7182818284590451_8 9691 complex :: z = (1.0, 2.0) 9692 x = log(x) ! will yield (approximately) 1 9693 z = log(z) 9694end program test_log 9695@end smallexample 9696 9697@item @emph{Specific names}: 9698@multitable @columnfractions .20 .20 .20 .25 9699@item Name @tab Argument @tab Return type @tab Standard 9700@item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later 9701@item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later 9702@item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later 9703@item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 9704@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 9705@end multitable 9706@end table 9707 9708 9709 9710@node LOG10 9711@section @code{LOG10} --- Base 10 logarithm function 9712@fnindex LOG10 9713@fnindex ALOG10 9714@fnindex DLOG10 9715@cindex exponential function, inverse 9716@cindex logarithm function with base 10 9717@cindex base 10 logarithm function 9718 9719@table @asis 9720@item @emph{Description}: 9721@code{LOG10(X)} computes the base 10 logarithm of @var{X}. 9722 9723@item @emph{Standard}: 9724Fortran 77 and later 9725 9726@item @emph{Class}: 9727Elemental function 9728 9729@item @emph{Syntax}: 9730@code{RESULT = LOG10(X)} 9731 9732@item @emph{Arguments}: 9733@multitable @columnfractions .15 .70 9734@item @var{X} @tab The type shall be @code{REAL}. 9735@end multitable 9736 9737@item @emph{Return value}: 9738The return value is of type @code{REAL} or @code{COMPLEX}. 9739The kind type parameter is the same as @var{X}. 9740 9741@item @emph{Example}: 9742@smallexample 9743program test_log10 9744 real(8) :: x = 10.0_8 9745 x = log10(x) 9746end program test_log10 9747@end smallexample 9748 9749@item @emph{Specific names}: 9750@multitable @columnfractions .20 .20 .20 .25 9751@item Name @tab Argument @tab Return type @tab Standard 9752@item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 9753@item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 9754@end multitable 9755@end table 9756 9757 9758 9759@node LOG_GAMMA 9760@section @code{LOG_GAMMA} --- Logarithm of the Gamma function 9761@fnindex LOG_GAMMA 9762@fnindex LGAMMA 9763@fnindex ALGAMA 9764@fnindex DLGAMA 9765@cindex Gamma function, logarithm of 9766 9767@table @asis 9768@item @emph{Description}: 9769@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value 9770of the Gamma (@math{\Gamma}) function. 9771 9772@item @emph{Standard}: 9773Fortran 2008 and later 9774 9775@item @emph{Class}: 9776Elemental function 9777 9778@item @emph{Syntax}: 9779@code{X = LOG_GAMMA(X)} 9780 9781@item @emph{Arguments}: 9782@multitable @columnfractions .15 .70 9783@item @var{X} @tab Shall be of type @code{REAL} and neither zero 9784nor a negative integer. 9785@end multitable 9786 9787@item @emph{Return value}: 9788The return value is of type @code{REAL} of the same kind as @var{X}. 9789 9790@item @emph{Example}: 9791@smallexample 9792program test_log_gamma 9793 real :: x = 1.0 9794 x = lgamma(x) ! returns 0.0 9795end program test_log_gamma 9796@end smallexample 9797 9798@item @emph{Specific names}: 9799@multitable @columnfractions .20 .20 .20 .25 9800@item Name @tab Argument @tab Return type @tab Standard 9801@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 9802@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 9803@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 9804@end multitable 9805 9806@item @emph{See also}: 9807Gamma function: @gol 9808@ref{GAMMA} 9809@end table 9810 9811 9812 9813@node LOGICAL 9814@section @code{LOGICAL} --- Convert to logical type 9815@fnindex LOGICAL 9816@cindex conversion, to logical 9817 9818@table @asis 9819@item @emph{Description}: 9820Converts one kind of @code{LOGICAL} variable to another. 9821 9822@item @emph{Standard}: 9823Fortran 90 and later 9824 9825@item @emph{Class}: 9826Elemental function 9827 9828@item @emph{Syntax}: 9829@code{RESULT = LOGICAL(L [, KIND])} 9830 9831@item @emph{Arguments}: 9832@multitable @columnfractions .15 .70 9833@item @var{L} @tab The type shall be @code{LOGICAL}. 9834@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9835expression indicating the kind parameter of the result. 9836@end multitable 9837 9838@item @emph{Return value}: 9839The return value is a @code{LOGICAL} value equal to @var{L}, with a 9840kind corresponding to @var{KIND}, or of the default logical kind if 9841@var{KIND} is not given. 9842 9843@item @emph{See also}: 9844@ref{INT}, @gol 9845@ref{REAL}, @gol 9846@ref{CMPLX} 9847@end table 9848 9849 9850 9851@node LONG 9852@section @code{LONG} --- Convert to integer type 9853@fnindex LONG 9854@cindex conversion, to integer 9855 9856@table @asis 9857@item @emph{Description}: 9858Convert to a @code{KIND=4} integer type, which is the same size as a C 9859@code{long} integer. This is equivalent to the standard @code{INT} 9860intrinsic with an optional argument of @code{KIND=4}, and is only 9861included for backwards compatibility. 9862 9863@item @emph{Standard}: 9864GNU extension 9865 9866@item @emph{Class}: 9867Elemental function 9868 9869@item @emph{Syntax}: 9870@code{RESULT = LONG(A)} 9871 9872@item @emph{Arguments}: 9873@multitable @columnfractions .15 .70 9874@item @var{A} @tab Shall be of type @code{INTEGER}, 9875@code{REAL}, or @code{COMPLEX}. 9876@end multitable 9877 9878@item @emph{Return value}: 9879The return value is a @code{INTEGER(4)} variable. 9880 9881@item @emph{See also}: 9882@ref{INT}, @gol 9883@ref{INT2}, @gol 9884@ref{INT8} 9885@end table 9886 9887 9888 9889@node LSHIFT 9890@section @code{LSHIFT} --- Left shift bits 9891@fnindex LSHIFT 9892@cindex bits, shift left 9893 9894@table @asis 9895@item @emph{Description}: 9896@code{LSHIFT} returns a value corresponding to @var{I} with all of the 9897bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be 9898nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 9899the result value is undefined. Bits shifted out from the left end are 9900lost; zeros are shifted in from the opposite end. 9901 9902This function has been superseded by the @code{ISHFT} intrinsic, which 9903is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic, 9904which is standard in Fortran 2008 and later. 9905 9906@item @emph{Standard}: 9907GNU extension 9908 9909@item @emph{Class}: 9910Elemental function 9911 9912@item @emph{Syntax}: 9913@code{RESULT = LSHIFT(I, SHIFT)} 9914 9915@item @emph{Arguments}: 9916@multitable @columnfractions .15 .70 9917@item @var{I} @tab The type shall be @code{INTEGER}. 9918@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 9919@end multitable 9920 9921@item @emph{Return value}: 9922The return value is of type @code{INTEGER} and of the same kind as 9923@var{I}. 9924 9925@item @emph{See also}: 9926@ref{ISHFT}, @gol 9927@ref{ISHFTC}, @gol 9928@ref{RSHIFT}, @gol 9929@ref{SHIFTA}, @gol 9930@ref{SHIFTL}, @gol 9931@ref{SHIFTR} 9932@end table 9933 9934 9935 9936@node LSTAT 9937@section @code{LSTAT} --- Get file status 9938@fnindex LSTAT 9939@cindex file system, file status 9940 9941@table @asis 9942@item @emph{Description}: 9943@code{LSTAT} is identical to @ref{STAT}, except that if path is a 9944symbolic link, then the link itself is statted, not the file that it 9945refers to. 9946 9947The elements in @code{VALUES} are the same as described by @ref{STAT}. 9948 9949This intrinsic is provided in both subroutine and function forms; 9950however, only one form can be used in any given program unit. 9951 9952@item @emph{Standard}: 9953GNU extension 9954 9955@item @emph{Class}: 9956Subroutine, function 9957 9958@item @emph{Syntax}: 9959@multitable @columnfractions .80 9960@item @code{CALL LSTAT(NAME, VALUES [, STATUS])} 9961@item @code{STATUS = LSTAT(NAME, VALUES)} 9962@end multitable 9963 9964@item @emph{Arguments}: 9965@multitable @columnfractions .15 .70 9966@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default 9967kind, a valid path within the file system. 9968@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 9969@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. 9970Returns 0 on success and a system specific error code otherwise. 9971@end multitable 9972 9973@item @emph{Example}: 9974See @ref{STAT} for an example. 9975 9976@item @emph{See also}: 9977To stat an open file: @gol 9978@ref{FSTAT} @gol 9979To stat a file: @gol 9980@ref{STAT} 9981@end table 9982 9983 9984 9985@node LTIME 9986@section @code{LTIME} --- Convert time to local time info 9987@fnindex LTIME 9988@cindex time, conversion to local time info 9989 9990@table @asis 9991@item @emph{Description}: 9992Given a system time value @var{TIME} (as provided by the @ref{TIME} 9993intrinsic), fills @var{VALUES} with values extracted from it appropriate 9994to the local time zone using @code{localtime(3)}. 9995 9996This intrinsic routine is provided for backwards compatibility with 9997GNU Fortran 77. In new code, programmers should consider the use of 9998the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 9999standard. 10000 10001@item @emph{Standard}: 10002GNU extension 10003 10004@item @emph{Class}: 10005Subroutine 10006 10007@item @emph{Syntax}: 10008@code{CALL LTIME(TIME, VALUES)} 10009 10010@item @emph{Arguments}: 10011@multitable @columnfractions .15 .70 10012@item @var{TIME} @tab An @code{INTEGER} scalar expression 10013corresponding to a system time, with @code{INTENT(IN)}. 10014@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 10015with @code{INTENT(OUT)}. 10016@end multitable 10017 10018@item @emph{Return value}: 10019The elements of @var{VALUES} are assigned as follows: 10020@enumerate 10021@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 10022seconds 10023@item Minutes after the hour, range 0--59 10024@item Hours past midnight, range 0--23 10025@item Day of month, range 1--31 10026@item Number of months since January, range 0--11 10027@item Years since 1900 10028@item Number of days since Sunday, range 0--6 10029@item Days since January 1, range 0--365 10030@item Daylight savings indicator: positive if daylight savings is in 10031effect, zero if not, and negative if the information is not available. 10032@end enumerate 10033 10034@item @emph{See also}: 10035@ref{DATE_AND_TIME}, @gol 10036@ref{CTIME}, @gol 10037@ref{GMTIME}, @gol 10038@ref{TIME}, @gol 10039@ref{TIME8} 10040@end table 10041 10042 10043 10044@node MALLOC 10045@section @code{MALLOC} --- Allocate dynamic memory 10046@fnindex MALLOC 10047@cindex pointer, cray 10048 10049@table @asis 10050@item @emph{Description}: 10051@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and 10052returns the address of the allocated memory. The @code{MALLOC} intrinsic 10053is an extension intended to be used with Cray pointers, and is provided 10054in GNU Fortran to allow the user to compile legacy code. For new code 10055using Fortran 95 pointers, the memory allocation intrinsic is 10056@code{ALLOCATE}. 10057 10058@item @emph{Standard}: 10059GNU extension 10060 10061@item @emph{Class}: 10062Function 10063 10064@item @emph{Syntax}: 10065@code{PTR = MALLOC(SIZE)} 10066 10067@item @emph{Arguments}: 10068@multitable @columnfractions .15 .70 10069@item @var{SIZE} @tab The type shall be @code{INTEGER}. 10070@end multitable 10071 10072@item @emph{Return value}: 10073The return value is of type @code{INTEGER(K)}, with @var{K} such that 10074variables of type @code{INTEGER(K)} have the same size as 10075C pointers (@code{sizeof(void *)}). 10076 10077@item @emph{Example}: 10078The following example demonstrates the use of @code{MALLOC} and 10079@code{FREE} with Cray pointers. 10080 10081@smallexample 10082program test_malloc 10083 implicit none 10084 integer i 10085 real*8 x(*), z 10086 pointer(ptr_x,x) 10087 10088 ptr_x = malloc(20*8) 10089 do i = 1, 20 10090 x(i) = sqrt(1.0d0 / i) 10091 end do 10092 z = 0 10093 do i = 1, 20 10094 z = z + x(i) 10095 print *, z 10096 end do 10097 call free(ptr_x) 10098end program test_malloc 10099@end smallexample 10100 10101@item @emph{See also}: 10102@ref{FREE} 10103@end table 10104 10105 10106 10107@node MASKL 10108@section @code{MASKL} --- Left justified mask 10109@fnindex MASKL 10110@cindex mask, left justified 10111 10112@table @asis 10113@item @emph{Description}: 10114@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the 10115remaining bits set to 0. 10116 10117@item @emph{Standard}: 10118Fortran 2008 and later 10119 10120@item @emph{Class}: 10121Elemental function 10122 10123@item @emph{Syntax}: 10124@code{RESULT = MASKL(I[, KIND])} 10125 10126@item @emph{Arguments}: 10127@multitable @columnfractions .15 .70 10128@item @var{I} @tab Shall be of type @code{INTEGER}. 10129@item @var{KIND} @tab Shall be a scalar constant expression of type 10130@code{INTEGER}. 10131@end multitable 10132 10133@item @emph{Return value}: 10134The return value is of type @code{INTEGER}. If @var{KIND} is present, it 10135specifies the kind value of the return type; otherwise, it is of the 10136default integer kind. 10137 10138@item @emph{See also}: 10139@ref{MASKR} 10140@end table 10141 10142 10143 10144@node MASKR 10145@section @code{MASKR} --- Right justified mask 10146@fnindex MASKR 10147@cindex mask, right justified 10148 10149@table @asis 10150@item @emph{Description}: 10151@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the 10152remaining bits set to 0. 10153 10154@item @emph{Standard}: 10155Fortran 2008 and later 10156 10157@item @emph{Class}: 10158Elemental function 10159 10160@item @emph{Syntax}: 10161@code{RESULT = MASKR(I[, KIND])} 10162 10163@item @emph{Arguments}: 10164@multitable @columnfractions .15 .70 10165@item @var{I} @tab Shall be of type @code{INTEGER}. 10166@item @var{KIND} @tab Shall be a scalar constant expression of type 10167@code{INTEGER}. 10168@end multitable 10169 10170@item @emph{Return value}: 10171The return value is of type @code{INTEGER}. If @var{KIND} is present, it 10172specifies the kind value of the return type; otherwise, it is of the 10173default integer kind. 10174 10175@item @emph{See also}: 10176@ref{MASKL} 10177@end table 10178 10179 10180 10181@node MATMUL 10182@section @code{MATMUL} --- matrix multiplication 10183@fnindex MATMUL 10184@cindex matrix multiplication 10185@cindex product, matrix 10186 10187@table @asis 10188@item @emph{Description}: 10189Performs a matrix multiplication on numeric or logical arguments. 10190 10191@item @emph{Standard}: 10192Fortran 90 and later 10193 10194@item @emph{Class}: 10195Transformational function 10196 10197@item @emph{Syntax}: 10198@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)} 10199 10200@item @emph{Arguments}: 10201@multitable @columnfractions .15 .70 10202@item @var{MATRIX_A} @tab An array of @code{INTEGER}, 10203@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of 10204one or two. 10205@item @var{MATRIX_B} @tab An array of @code{INTEGER}, 10206@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric 10207type; otherwise, an array of @code{LOGICAL} type. The rank shall be one 10208or two, and the first (or only) dimension of @var{MATRIX_B} shall be 10209equal to the last (or only) dimension of @var{MATRIX_A}. 10210@var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays. 10211@end multitable 10212 10213@item @emph{Return value}: 10214The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and 10215kind of the result follow the usual type and kind promotion rules, as 10216for the @code{*} or @code{.AND.} operators. 10217@end table 10218 10219 10220 10221@node MAX 10222@section @code{MAX} --- Maximum value of an argument list 10223@fnindex MAX 10224@fnindex MAX0 10225@fnindex AMAX0 10226@fnindex MAX1 10227@fnindex AMAX1 10228@fnindex DMAX1 10229@cindex maximum value 10230 10231@table @asis 10232@item @emph{Description}: 10233Returns the argument with the largest (most positive) value. 10234 10235@item @emph{Standard}: 10236Fortran 77 and later 10237 10238@item @emph{Class}: 10239Elemental function 10240 10241@item @emph{Syntax}: 10242@code{RESULT = MAX(A1, A2 [, A3 [, ...]])} 10243 10244@item @emph{Arguments}: 10245@multitable @columnfractions .15 .70 10246@item @var{A1} @tab The type shall be @code{INTEGER} or 10247@code{REAL}. 10248@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10249as @var{A1}. (As a GNU extension, arguments of different kinds are 10250permitted.) 10251@end multitable 10252 10253@item @emph{Return value}: 10254The return value corresponds to the maximum value among the arguments, 10255and has the same type and kind as the first argument. 10256 10257@item @emph{Specific names}: 10258@multitable @columnfractions .20 .20 .20 .25 10259@item Name @tab Argument @tab Return type @tab Standard 10260@item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10261@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later 10262@item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later 10263@item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10264@item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10265@end multitable 10266 10267@item @emph{See also}: 10268@ref{MAXLOC} @gol 10269@ref{MAXVAL}, @gol 10270@ref{MIN} 10271@end table 10272 10273 10274 10275@node MAXEXPONENT 10276@section @code{MAXEXPONENT} --- Maximum exponent of a real kind 10277@fnindex MAXEXPONENT 10278@cindex model representation, maximum exponent 10279 10280@table @asis 10281@item @emph{Description}: 10282@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the 10283type of @code{X}. 10284 10285@item @emph{Standard}: 10286Fortran 90 and later 10287 10288@item @emph{Class}: 10289Inquiry function 10290 10291@item @emph{Syntax}: 10292@code{RESULT = MAXEXPONENT(X)} 10293 10294@item @emph{Arguments}: 10295@multitable @columnfractions .15 .70 10296@item @var{X} @tab Shall be of type @code{REAL}. 10297@end multitable 10298 10299@item @emph{Return value}: 10300The return value is of type @code{INTEGER} and of the default integer 10301kind. 10302 10303@item @emph{Example}: 10304@smallexample 10305program exponents 10306 real(kind=4) :: x 10307 real(kind=8) :: y 10308 10309 print *, minexponent(x), maxexponent(x) 10310 print *, minexponent(y), maxexponent(y) 10311end program exponents 10312@end smallexample 10313@end table 10314 10315 10316 10317@node MAXLOC 10318@section @code{MAXLOC} --- Location of the maximum value within an array 10319@fnindex MAXLOC 10320@cindex array, location of maximum element 10321 10322@table @asis 10323@item @emph{Description}: 10324Determines the location of the element in the array with the maximum 10325value, or, if the @var{DIM} argument is supplied, determines the 10326locations of the maximum element along each row of the array in the 10327@var{DIM} direction. If @var{MASK} is present, only the elements for 10328which @var{MASK} is @code{.TRUE.} are considered. If more than one 10329element in the array has the maximum value, the location returned is 10330that of the first such element in array element order if the 10331@var{BACK} is not present, or is false; if @var{BACK} is true, the location 10332returned is that of the last such element. If the array has zero 10333size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10334the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10335and all of the elements of @var{MASK} along a given row are zero, the 10336result value for that row is zero. 10337 10338@item @emph{Standard}: 10339Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the 10340@var{KIND} argument are available in Fortran 2003 and later. 10341The @var{BACK} argument is available in Fortran 2008 and later. 10342 10343@item @emph{Class}: 10344Transformational function 10345 10346@item @emph{Syntax}: 10347@multitable @columnfractions .80 10348@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} 10349@item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])} 10350@end multitable 10351 10352@item @emph{Arguments}: 10353@multitable @columnfractions .15 .70 10354@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10355@code{REAL}. 10356@item @var{DIM} @tab (Optional) Shall be a scalar of type 10357@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10358inclusive. It may not be an optional dummy argument. 10359@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10360and conformable with @var{ARRAY}. 10361@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10362expression indicating the kind parameter of the result. 10363@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 10364@end multitable 10365 10366@item @emph{Return value}: 10367If @var{DIM} is absent, the result is a rank-one array with a length 10368equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10369is an array with a rank one less than the rank of @var{ARRAY}, and a 10370size corresponding to the size of @var{ARRAY} with the @var{DIM} 10371dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10372of one, the result is a scalar. If the optional argument @var{KIND} 10373is present, the result is an integer of kind @var{KIND}, otherwise it 10374is of default kind. 10375 10376@item @emph{See also}: 10377@ref{FINDLOC}, @gol 10378@ref{MAX}, @gol 10379@ref{MAXVAL} 10380@end table 10381 10382 10383 10384@node MAXVAL 10385@section @code{MAXVAL} --- Maximum value of an array 10386@fnindex MAXVAL 10387@cindex array, maximum value 10388@cindex maximum value 10389 10390@table @asis 10391@item @emph{Description}: 10392Determines the maximum value of the elements in an array value, or, if 10393the @var{DIM} argument is supplied, determines the maximum value along 10394each row of the array in the @var{DIM} direction. If @var{MASK} is 10395present, only the elements for which @var{MASK} is @code{.TRUE.} are 10396considered. If the array has zero size, or all of the elements of 10397@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)} 10398if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character 10399type. 10400 10401@item @emph{Standard}: 10402Fortran 90 and later 10403 10404@item @emph{Class}: 10405Transformational function 10406 10407@item @emph{Syntax}: 10408@multitable @columnfractions .80 10409@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])} 10410@item @code{RESULT = MAXVAL(ARRAY [, MASK])} 10411@end multitable 10412 10413@item @emph{Arguments}: 10414@multitable @columnfractions .15 .70 10415@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10416@code{REAL}. 10417@item @var{DIM} @tab (Optional) Shall be a scalar of type 10418@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10419inclusive. It may not be an optional dummy argument. 10420@item @var{MASK} @tab (Opional) Shall be an array of type @code{LOGICAL}, 10421and conformable with @var{ARRAY}. 10422@end multitable 10423 10424@item @emph{Return value}: 10425If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10426is a scalar. If @var{DIM} is present, the result is an array with a 10427rank one less than the rank of @var{ARRAY}, and a size corresponding to 10428the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10429cases, the result is of the same type and kind as @var{ARRAY}. 10430 10431@item @emph{See also}: 10432@ref{MAX}, @gol 10433@ref{MAXLOC} 10434@end table 10435 10436 10437 10438@node MCLOCK 10439@section @code{MCLOCK} --- Time function 10440@fnindex MCLOCK 10441@cindex time, clock ticks 10442@cindex clock ticks 10443 10444@table @asis 10445@item @emph{Description}: 10446Returns the number of clock ticks since the start of the process, based 10447on the function @code{clock(3)} in the C standard library. 10448 10449This intrinsic is not fully portable, such as to systems with 32-bit 10450@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 10451the values returned by this intrinsic might be, or become, negative, or 10452numerically less than previous values, during a single run of the 10453compiled program. 10454 10455@item @emph{Standard}: 10456GNU extension 10457 10458@item @emph{Class}: 10459Function 10460 10461@item @emph{Syntax}: 10462@code{RESULT = MCLOCK()} 10463 10464@item @emph{Return value}: 10465The return value is a scalar of type @code{INTEGER(4)}, equal to the 10466number of clock ticks since the start of the process, or @code{-1} if 10467the system does not support @code{clock(3)}. 10468 10469@item @emph{See also}: 10470@ref{CTIME}, @gol 10471@ref{GMTIME}, @gol 10472@ref{LTIME}, @gol 10473@ref{MCLOCK}, @gol 10474@ref{TIME} 10475@end table 10476 10477 10478 10479@node MCLOCK8 10480@section @code{MCLOCK8} --- Time function (64-bit) 10481@fnindex MCLOCK8 10482@cindex time, clock ticks 10483@cindex clock ticks 10484 10485@table @asis 10486@item @emph{Description}: 10487Returns the number of clock ticks since the start of the process, based 10488on the function @code{clock(3)} in the C standard library. 10489 10490@emph{Warning:} this intrinsic does not increase the range of the timing 10491values over that returned by @code{clock(3)}. On a system with a 32-bit 10492@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though 10493it is converted to a 64-bit @code{INTEGER(8)} value. That means 10494overflows of the 32-bit value can still occur. Therefore, the values 10495returned by this intrinsic might be or become negative or numerically 10496less than previous values during a single run of the compiled program. 10497 10498@item @emph{Standard}: 10499GNU extension 10500 10501@item @emph{Class}: 10502Function 10503 10504@item @emph{Syntax}: 10505@code{RESULT = MCLOCK8()} 10506 10507@item @emph{Return value}: 10508The return value is a scalar of type @code{INTEGER(8)}, equal to the 10509number of clock ticks since the start of the process, or @code{-1} if 10510the system does not support @code{clock(3)}. 10511 10512@item @emph{See also}: 10513@ref{CTIME}, @gol 10514@ref{GMTIME}, @gol 10515@ref{LTIME}, @gol 10516@ref{MCLOCK}, @gol 10517@ref{TIME8} 10518@end table 10519 10520 10521 10522@node MERGE 10523@section @code{MERGE} --- Merge variables 10524@fnindex MERGE 10525@cindex array, merge arrays 10526@cindex array, combine arrays 10527 10528@table @asis 10529@item @emph{Description}: 10530Select values from two arrays according to a logical mask. The result 10531is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to 10532@var{FSOURCE} if it is @code{.FALSE.}. 10533 10534@item @emph{Standard}: 10535Fortran 90 and later 10536 10537@item @emph{Class}: 10538Elemental function 10539 10540@item @emph{Syntax}: 10541@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)} 10542 10543@item @emph{Arguments}: 10544@multitable @columnfractions .15 .70 10545@item @var{TSOURCE} @tab May be of any type. 10546@item @var{FSOURCE} @tab Shall be of the same type and type parameters 10547as @var{TSOURCE}. 10548@item @var{MASK} @tab Shall be of type @code{LOGICAL}. 10549@end multitable 10550 10551@item @emph{Return value}: 10552The result is of the same type and type parameters as @var{TSOURCE}. 10553 10554@end table 10555 10556 10557 10558@node MERGE_BITS 10559@section @code{MERGE_BITS} --- Merge of bits under mask 10560@fnindex MERGE_BITS 10561@cindex bits, merge 10562 10563@table @asis 10564@item @emph{Description}: 10565@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J} 10566as determined by the mask. The i-th bit of the result is equal to the 10567i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to 10568the i-th bit of @var{J} otherwise. 10569 10570@item @emph{Standard}: 10571Fortran 2008 and later 10572 10573@item @emph{Class}: 10574Elemental function 10575 10576@item @emph{Syntax}: 10577@code{RESULT = MERGE_BITS(I, J, MASK)} 10578 10579@item @emph{Arguments}: 10580@multitable @columnfractions .15 .70 10581@item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant. 10582@item @var{J} @tab Shall be of type @code{INTEGER} with the same 10583kind type parameter as @var{I} or a boz-literal-constant. 10584@var{I} and @var{J} shall not both be boz-literal-constants. 10585@item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant 10586and of the same kind as @var{I}. 10587@end multitable 10588 10589@item @emph{Return value}: 10590The result is of the same type and kind as @var{I}. 10591 10592@end table 10593 10594 10595 10596@node MIN 10597@section @code{MIN} --- Minimum value of an argument list 10598@fnindex MIN 10599@fnindex MIN0 10600@fnindex AMIN0 10601@fnindex MIN1 10602@fnindex AMIN1 10603@fnindex DMIN1 10604@cindex minimum value 10605 10606@table @asis 10607@item @emph{Description}: 10608Returns the argument with the smallest (most negative) value. 10609 10610@item @emph{Standard}: 10611Fortran 77 and later 10612 10613@item @emph{Class}: 10614Elemental function 10615 10616@item @emph{Syntax}: 10617@code{RESULT = MIN(A1, A2 [, A3, ...])} 10618 10619@item @emph{Arguments}: 10620@multitable @columnfractions .15 .70 10621@item @var{A1} @tab The type shall be @code{INTEGER} or 10622@code{REAL}. 10623@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10624as @var{A1}. (As a GNU extension, arguments of different kinds are 10625permitted.) 10626@end multitable 10627 10628@item @emph{Return value}: 10629The return value corresponds to the maximum value among the arguments, 10630and has the same type and kind as the first argument. 10631 10632@item @emph{Specific names}: 10633@multitable @columnfractions .20 .20 .20 .25 10634@item Name @tab Argument @tab Return type @tab Standard 10635@item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10636@item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10637@item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10638@item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10639@item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10640@end multitable 10641 10642@item @emph{See also}: 10643@ref{MAX}, @gol 10644@ref{MINLOC}, @gol 10645@ref{MINVAL} 10646@end table 10647 10648 10649 10650@node MINEXPONENT 10651@section @code{MINEXPONENT} --- Minimum exponent of a real kind 10652@fnindex MINEXPONENT 10653@cindex model representation, minimum exponent 10654 10655@table @asis 10656@item @emph{Description}: 10657@code{MINEXPONENT(X)} returns the minimum exponent in the model of the 10658type of @code{X}. 10659 10660@item @emph{Standard}: 10661Fortran 90 and later 10662 10663@item @emph{Class}: 10664Inquiry function 10665 10666@item @emph{Syntax}: 10667@code{RESULT = MINEXPONENT(X)} 10668 10669@item @emph{Arguments}: 10670@multitable @columnfractions .15 .70 10671@item @var{X} @tab Shall be of type @code{REAL}. 10672@end multitable 10673 10674@item @emph{Return value}: 10675The return value is of type @code{INTEGER} and of the default integer 10676kind. 10677 10678@item @emph{Example}: 10679See @code{MAXEXPONENT} for an example. 10680@end table 10681 10682 10683 10684@node MINLOC 10685@section @code{MINLOC} --- Location of the minimum value within an array 10686@fnindex MINLOC 10687@cindex array, location of minimum element 10688 10689@table @asis 10690@item @emph{Description}: 10691Determines the location of the element in the array with the minimum 10692value, or, if the @var{DIM} argument is supplied, determines the 10693locations of the minimum element along each row of the array in the 10694@var{DIM} direction. If @var{MASK} is present, only the elements for 10695which @var{MASK} is @code{.TRUE.} are considered. If more than one 10696element in the array has the minimum value, the location returned is 10697that of the first such element in array element order if the 10698@var{BACK} is not present, or is false; if @var{BACK} is true, the location 10699returned is that of the last such element. If the array has 10700zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10701the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10702and all of the elements of @var{MASK} along a given row are zero, the 10703result value for that row is zero. 10704 10705@item @emph{Standard}: 10706Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the 10707@var{KIND} argument are available in Fortran 2003 and later. 10708The @var{BACK} argument is available in Fortran 2008 and later. 10709 10710@item @emph{Class}: 10711Transformational function 10712 10713@item @emph{Syntax}: 10714@multitable @columnfractions .80 10715@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} 10716@item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])} 10717@end multitable 10718 10719@item @emph{Arguments}: 10720@multitable @columnfractions .15 .70 10721@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 10722@code{REAL} or @code{CHARACTER}. 10723@item @var{DIM} @tab (Optional) Shall be a scalar of type 10724@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10725inclusive. It may not be an optional dummy argument. 10726@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10727and conformable with @var{ARRAY}. 10728@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10729expression indicating the kind parameter of the result. 10730@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 10731@end multitable 10732 10733@item @emph{Return value}: 10734If @var{DIM} is absent, the result is a rank-one array with a length 10735equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10736is an array with a rank one less than the rank of @var{ARRAY}, and a 10737size corresponding to the size of @var{ARRAY} with the @var{DIM} 10738dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10739of one, the result is a scalar. If the optional argument @var{KIND} 10740is present, the result is an integer of kind @var{KIND}, otherwise it 10741is of default kind. 10742 10743@item @emph{See also}: 10744@ref{FINDLOC}, @gol 10745@ref{MIN}, @gol 10746@ref{MINVAL} 10747@end table 10748 10749 10750 10751@node MINVAL 10752@section @code{MINVAL} --- Minimum value of an array 10753@fnindex MINVAL 10754@cindex array, minimum value 10755@cindex minimum value 10756 10757@table @asis 10758@item @emph{Description}: 10759Determines the minimum value of the elements in an array value, or, if 10760the @var{DIM} argument is supplied, determines the minimum value along 10761each row of the array in the @var{DIM} direction. If @var{MASK} is 10762present, only the elements for which @var{MASK} is @code{.TRUE.} are 10763considered. If the array has zero size, or all of the elements of 10764@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if 10765@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if 10766@var{ARRAY} is of character type. 10767 10768@item @emph{Standard}: 10769Fortran 90 and later 10770 10771@item @emph{Class}: 10772Transformational function 10773 10774@item @emph{Syntax}: 10775@multitable @columnfractions .80 10776@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])} 10777@item @code{RESULT = MINVAL(ARRAY [, MASK])} 10778@end multitable 10779 10780@item @emph{Arguments}: 10781@multitable @columnfractions .15 .70 10782@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10783@code{REAL}. 10784@item @var{DIM} @tab (Optional) Shall be a scalar of type 10785@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10786inclusive. It may not be an optional dummy argument. 10787@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10788and conformable with @var{ARRAY}. 10789@end multitable 10790 10791@item @emph{Return value}: 10792If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10793is a scalar. If @var{DIM} is present, the result is an array with a 10794rank one less than the rank of @var{ARRAY}, and a size corresponding to 10795the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10796cases, the result is of the same type and kind as @var{ARRAY}. 10797 10798@item @emph{See also}: 10799@ref{MIN}, @gol 10800@ref{MINLOC} 10801@end table 10802 10803 10804 10805@node MOD 10806@section @code{MOD} --- Remainder function 10807@fnindex MOD 10808@fnindex AMOD 10809@fnindex DMOD 10810@fnindex BMOD 10811@fnindex IMOD 10812@fnindex JMOD 10813@fnindex KMOD 10814@cindex remainder 10815@cindex division, remainder 10816 10817@table @asis 10818@item @emph{Description}: 10819@code{MOD(A,P)} computes the remainder of the division of A by P@. 10820 10821@item @emph{Standard}: 10822Fortran 77 and later, has overloads that are GNU extensions 10823 10824@item @emph{Class}: 10825Elemental function 10826 10827@item @emph{Syntax}: 10828@code{RESULT = MOD(A, P)} 10829 10830@item @emph{Arguments}: 10831@multitable @columnfractions .15 .70 10832@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10833@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A} 10834and not equal to zero. (As a GNU extension, arguments of different kinds are 10835permitted.) 10836@end multitable 10837 10838@item @emph{Return value}: 10839The return value is the result of @code{A - (INT(A/P) * P)}. The type 10840and kind of the return value is the same as that of the arguments. The 10841returned value has the same sign as A and a magnitude less than the 10842magnitude of P. (As a GNU extension, kind is the largest kind of the actual 10843arguments.) 10844 10845@item @emph{Example}: 10846@smallexample 10847program test_mod 10848 print *, mod(17,3) 10849 print *, mod(17.5,5.5) 10850 print *, mod(17.5d0,5.5) 10851 print *, mod(17.5,5.5d0) 10852 10853 print *, mod(-17,3) 10854 print *, mod(-17.5,5.5) 10855 print *, mod(-17.5d0,5.5) 10856 print *, mod(-17.5,5.5d0) 10857 10858 print *, mod(17,-3) 10859 print *, mod(17.5,-5.5) 10860 print *, mod(17.5d0,-5.5) 10861 print *, mod(17.5,-5.5d0) 10862end program test_mod 10863@end smallexample 10864 10865@item @emph{Specific names}: 10866@multitable @columnfractions .20 .20 .20 .25 10867@item Name @tab Arguments @tab Return type @tab Standard 10868@item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later 10869@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later 10870@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later 10871@item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension 10872@item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension 10873@item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension 10874@item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension 10875@end multitable 10876 10877@item @emph{See also}: 10878@ref{MODULO} 10879 10880@end table 10881 10882 10883 10884@node MODULO 10885@section @code{MODULO} --- Modulo function 10886@fnindex MODULO 10887@cindex modulo 10888@cindex division, modulo 10889 10890@table @asis 10891@item @emph{Description}: 10892@code{MODULO(A,P)} computes the @var{A} modulo @var{P}. 10893 10894@item @emph{Standard}: 10895Fortran 95 and later 10896 10897@item @emph{Class}: 10898Elemental function 10899 10900@item @emph{Syntax}: 10901@code{RESULT = MODULO(A, P)} 10902 10903@item @emph{Arguments}: 10904@multitable @columnfractions .15 .70 10905@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10906@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}. 10907It shall not be zero. (As a GNU extension, arguments of different kinds are 10908permitted.) 10909@end multitable 10910 10911@item @emph{Return value}: 10912The type and kind of the result are those of the arguments. (As a GNU 10913extension, kind is the largest kind of the actual arguments.) 10914@table @asis 10915@item If @var{A} and @var{P} are of type @code{INTEGER}: 10916@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where 10917@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P} 10918(exclusive). 10919@item If @var{A} and @var{P} are of type @code{REAL}: 10920@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}. 10921@end table 10922The returned value has the same sign as P and a magnitude less than 10923the magnitude of P. 10924 10925@item @emph{Example}: 10926@smallexample 10927program test_modulo 10928 print *, modulo(17,3) 10929 print *, modulo(17.5,5.5) 10930 10931 print *, modulo(-17,3) 10932 print *, modulo(-17.5,5.5) 10933 10934 print *, modulo(17,-3) 10935 print *, modulo(17.5,-5.5) 10936end program 10937@end smallexample 10938 10939@item @emph{See also}: 10940@ref{MOD} 10941 10942@end table 10943 10944 10945 10946@node MOVE_ALLOC 10947@section @code{MOVE_ALLOC} --- Move allocation from one object to another 10948@fnindex MOVE_ALLOC 10949@cindex moving allocation 10950@cindex allocation, moving 10951 10952@table @asis 10953@item @emph{Description}: 10954@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to 10955@var{TO}. @var{FROM} will become deallocated in the process. 10956 10957@item @emph{Standard}: 10958Fortran 2003 and later 10959 10960@item @emph{Class}: 10961Pure subroutine 10962 10963@item @emph{Syntax}: 10964@code{CALL MOVE_ALLOC(FROM, TO)} 10965 10966@item @emph{Arguments}: 10967@multitable @columnfractions .15 .70 10968@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be 10969of any type and kind. 10970@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be 10971of the same type, kind and rank as @var{FROM}. 10972@end multitable 10973 10974@item @emph{Return value}: 10975None 10976 10977@item @emph{Example}: 10978@smallexample 10979program test_move_alloc 10980 integer, allocatable :: a(:), b(:) 10981 10982 allocate(a(3)) 10983 a = [ 1, 2, 3 ] 10984 call move_alloc(a, b) 10985 print *, allocated(a), allocated(b) 10986 print *, b 10987end program test_move_alloc 10988@end smallexample 10989@end table 10990 10991 10992 10993@node MVBITS 10994@section @code{MVBITS} --- Move bits from one integer to another 10995@fnindex MVBITS 10996@fnindex BMVBITS 10997@fnindex IMVBITS 10998@fnindex JMVBITS 10999@fnindex KMVBITS 11000@cindex bits, move 11001 11002@table @asis 11003@item @emph{Description}: 11004Moves @var{LEN} bits from positions @var{FROMPOS} through 11005@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through 11006@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not 11007affected by the movement of bits is unchanged. The values of 11008@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than 11009@code{BIT_SIZE(FROM)}. 11010 11011@item @emph{Standard}: 11012Fortran 90 and later, has overloads that are GNU extensions 11013 11014@item @emph{Class}: 11015Elemental subroutine 11016 11017@item @emph{Syntax}: 11018@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)} 11019 11020@item @emph{Arguments}: 11021@multitable @columnfractions .15 .70 11022@item @var{FROM} @tab The type shall be @code{INTEGER}. 11023@item @var{FROMPOS} @tab The type shall be @code{INTEGER}. 11024@item @var{LEN} @tab The type shall be @code{INTEGER}. 11025@item @var{TO} @tab The type shall be @code{INTEGER}, of the 11026same kind as @var{FROM}. 11027@item @var{TOPOS} @tab The type shall be @code{INTEGER}. 11028@end multitable 11029 11030@item @emph{Specific names}: 11031@multitable @columnfractions .20 .20 .20 .25 11032@item Name @tab Argument @tab Return type @tab Standard 11033@item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later 11034@item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 11035@item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 11036@item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 11037@item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 11038@end multitable 11039 11040@item @emph{See also}: 11041@ref{IBCLR}, @gol 11042@ref{IBSET}, @gol 11043@ref{IBITS}, @gol 11044@ref{IAND}, @gol 11045@ref{IOR}, @gol 11046@ref{IEOR} 11047@end table 11048 11049 11050 11051@node NEAREST 11052@section @code{NEAREST} --- Nearest representable number 11053@fnindex NEAREST 11054@cindex real number, nearest different 11055@cindex floating point, nearest different 11056 11057@table @asis 11058@item @emph{Description}: 11059@code{NEAREST(X, S)} returns the processor-representable number nearest 11060to @code{X} in the direction indicated by the sign of @code{S}. 11061 11062@item @emph{Standard}: 11063Fortran 90 and later 11064 11065@item @emph{Class}: 11066Elemental function 11067 11068@item @emph{Syntax}: 11069@code{RESULT = NEAREST(X, S)} 11070 11071@item @emph{Arguments}: 11072@multitable @columnfractions .15 .70 11073@item @var{X} @tab Shall be of type @code{REAL}. 11074@item @var{S} @tab Shall be of type @code{REAL} and 11075not equal to zero. 11076@end multitable 11077 11078@item @emph{Return value}: 11079The return value is of the same type as @code{X}. If @code{S} is 11080positive, @code{NEAREST} returns the processor-representable number 11081greater than @code{X} and nearest to it. If @code{S} is negative, 11082@code{NEAREST} returns the processor-representable number smaller than 11083@code{X} and nearest to it. 11084 11085@item @emph{Example}: 11086@smallexample 11087program test_nearest 11088 real :: x, y 11089 x = nearest(42.0, 1.0) 11090 y = nearest(42.0, -1.0) 11091 write (*,"(3(G20.15))") x, y, x - y 11092end program test_nearest 11093@end smallexample 11094@end table 11095 11096 11097 11098@node NEW_LINE 11099@section @code{NEW_LINE} --- New line character 11100@fnindex NEW_LINE 11101@cindex newline 11102@cindex output, newline 11103 11104@table @asis 11105@item @emph{Description}: 11106@code{NEW_LINE(C)} returns the new-line character. 11107 11108@item @emph{Standard}: 11109Fortran 2003 and later 11110 11111@item @emph{Class}: 11112Inquiry function 11113 11114@item @emph{Syntax}: 11115@code{RESULT = NEW_LINE(C)} 11116 11117@item @emph{Arguments}: 11118@multitable @columnfractions .15 .70 11119@item @var{C} @tab The argument shall be a scalar or array of the 11120type @code{CHARACTER}. 11121@end multitable 11122 11123@item @emph{Return value}: 11124Returns a @var{CHARACTER} scalar of length one with the new-line character of 11125the same kind as parameter @var{C}. 11126 11127@item @emph{Example}: 11128@smallexample 11129program newline 11130 implicit none 11131 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' 11132end program newline 11133@end smallexample 11134@end table 11135 11136 11137 11138@node NINT 11139@section @code{NINT} --- Nearest whole number 11140@fnindex NINT 11141@fnindex IDNINT 11142@cindex rounding, nearest whole number 11143 11144@table @asis 11145@item @emph{Description}: 11146@code{NINT(A)} rounds its argument to the nearest whole number. 11147 11148@item @emph{Standard}: 11149Fortran 77 and later, with @var{KIND} argument Fortran 90 and later 11150 11151@item @emph{Class}: 11152Elemental function 11153 11154@item @emph{Syntax}: 11155@code{RESULT = NINT(A [, KIND])} 11156 11157@item @emph{Arguments}: 11158@multitable @columnfractions .15 .70 11159@item @var{A} @tab The type of the argument shall be @code{REAL}. 11160@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 11161expression indicating the kind parameter of the result. 11162@end multitable 11163 11164@item @emph{Return value}: 11165Returns @var{A} with the fractional portion of its magnitude eliminated by 11166rounding to the nearest whole number and with its sign preserved, 11167converted to an @code{INTEGER} of the default kind. 11168 11169@item @emph{Example}: 11170@smallexample 11171program test_nint 11172 real(4) x4 11173 real(8) x8 11174 x4 = 1.234E0_4 11175 x8 = 4.321_8 11176 print *, nint(x4), idnint(x8) 11177end program test_nint 11178@end smallexample 11179 11180@item @emph{Specific names}: 11181@multitable @columnfractions .20 .20 .20 .25 11182@item Name @tab Argument @tab Return Type @tab Standard 11183@item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 11184@item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 11185@end multitable 11186 11187@item @emph{See also}: 11188@ref{CEILING}, @gol 11189@ref{FLOOR} 11190@end table 11191 11192 11193 11194@node NORM2 11195@section @code{NORM2} --- Euclidean vector norms 11196@fnindex NORM2 11197@cindex Euclidean vector norm 11198@cindex L2 vector norm 11199@cindex norm, Euclidean 11200 11201@table @asis 11202@item @emph{Description}: 11203Calculates the Euclidean vector norm (@math{L_2} norm) of 11204of @var{ARRAY} along dimension @var{DIM}. 11205 11206@item @emph{Standard}: 11207Fortran 2008 and later 11208 11209@item @emph{Class}: 11210Transformational function 11211 11212@item @emph{Syntax}: 11213@multitable @columnfractions .80 11214@item @code{RESULT = NORM2(ARRAY[, DIM])} 11215@end multitable 11216 11217@item @emph{Arguments}: 11218@multitable @columnfractions .15 .70 11219@item @var{ARRAY} @tab Shall be an array of type @code{REAL} 11220@item @var{DIM} @tab (Optional) shall be a scalar of type 11221@code{INTEGER} with a value in the range from 1 to n, where n 11222equals the rank of @var{ARRAY}. 11223@end multitable 11224 11225@item @emph{Return value}: 11226The result is of the same type as @var{ARRAY}. 11227 11228If @var{DIM} is absent, a scalar with the square root of the sum of all 11229elements in @var{ARRAY} squared is returned. Otherwise, an array of 11230rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a 11231shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped 11232is returned. 11233 11234@item @emph{Example}: 11235@smallexample 11236PROGRAM test_sum 11237 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] 11238 print *, NORM2(x) ! = sqrt(55.) ~ 7.416 11239END PROGRAM 11240@end smallexample 11241@end table 11242 11243 11244 11245@node NOT 11246@section @code{NOT} --- Logical negation 11247@fnindex NOT 11248@fnindex BNOT 11249@fnindex INOT 11250@fnindex JNOT 11251@fnindex KNOT 11252@cindex bits, negate 11253@cindex bitwise logical not 11254@cindex logical not, bitwise 11255 11256@table @asis 11257@item @emph{Description}: 11258@code{NOT} returns the bitwise Boolean inverse of @var{I}. 11259 11260@item @emph{Standard}: 11261Fortran 90 and later, has overloads that are GNU extensions 11262 11263@item @emph{Class}: 11264Elemental function 11265 11266@item @emph{Syntax}: 11267@code{RESULT = NOT(I)} 11268 11269@item @emph{Arguments}: 11270@multitable @columnfractions .15 .70 11271@item @var{I} @tab The type shall be @code{INTEGER}. 11272@end multitable 11273 11274@item @emph{Return value}: 11275The return type is @code{INTEGER}, of the same kind as the 11276argument. 11277 11278@item @emph{Specific names}: 11279@multitable @columnfractions .20 .20 .20 .25 11280@item Name @tab Argument @tab Return type @tab Standard 11281@item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 11282@item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 11283@item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 11284@item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 11285@item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 11286@end multitable 11287 11288@item @emph{See also}: 11289@ref{IAND}, @gol 11290@ref{IEOR}, @gol 11291@ref{IOR}, @gol 11292@ref{IBITS}, @gol 11293@ref{IBSET}, @gol 11294@ref{IBCLR} 11295@end table 11296 11297 11298 11299@node NULL 11300@section @code{NULL} --- Function that returns an disassociated pointer 11301@fnindex NULL 11302@cindex pointer, status 11303@cindex pointer, disassociated 11304 11305@table @asis 11306@item @emph{Description}: 11307Returns a disassociated pointer. 11308 11309If @var{MOLD} is present, a disassociated pointer of the same type is 11310returned, otherwise the type is determined by context. 11311 11312In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003 11313includes cases where it is required. 11314 11315@item @emph{Standard}: 11316Fortran 95 and later 11317 11318@item @emph{Class}: 11319Transformational function 11320 11321@item @emph{Syntax}: 11322@code{PTR => NULL([MOLD])} 11323 11324@item @emph{Arguments}: 11325@multitable @columnfractions .15 .70 11326@item @var{MOLD} @tab (Optional) shall be a pointer of any association 11327status and of any type. 11328@end multitable 11329 11330@item @emph{Return value}: 11331A disassociated pointer. 11332 11333@item @emph{Example}: 11334@smallexample 11335REAL, POINTER, DIMENSION(:) :: VEC => NULL () 11336@end smallexample 11337 11338@item @emph{See also}: 11339@ref{ASSOCIATED} 11340@end table 11341 11342 11343 11344@node NUM_IMAGES 11345@section @code{NUM_IMAGES} --- Function that returns the number of images 11346@fnindex NUM_IMAGES 11347@cindex coarray, @code{NUM_IMAGES} 11348@cindex images, number of 11349 11350@table @asis 11351@item @emph{Description}: 11352Returns the number of images. 11353 11354@item @emph{Standard}: 11355Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument, 11356Technical Specification (TS) 18508 or later 11357 11358 11359@item @emph{Class}: 11360Transformational function 11361 11362@item @emph{Syntax}: 11363@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} 11364 11365@item @emph{Arguments}: 11366@multitable @columnfractions .15 .70 11367@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 11368@item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression 11369@end multitable 11370 11371@item @emph{Return value}: 11372Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, 11373the number of images in the current team is returned. For values smaller or 11374equal distance to the initial team, it returns the number of images index 11375on the ancestor team which has a distance of @var{DISTANCE} from the invoking 11376team. If @var{DISTANCE} is larger than the distance to the initial team, the 11377number of images of the initial team is returned. If @var{FAILED} is not present 11378the total number of images is returned; if it has the value @code{.TRUE.}, 11379the number of failed images is returned, otherwise, the number of images which 11380do have not the failed status. 11381 11382@item @emph{Example}: 11383@smallexample 11384INTEGER :: value[*] 11385INTEGER :: i 11386value = THIS_IMAGE() 11387SYNC ALL 11388IF (THIS_IMAGE() == 1) THEN 11389 DO i = 1, NUM_IMAGES() 11390 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 11391 END DO 11392END IF 11393@end smallexample 11394 11395@item @emph{See also}: 11396@ref{THIS_IMAGE}, @gol 11397@ref{IMAGE_INDEX} 11398@end table 11399 11400 11401 11402@node OR 11403@section @code{OR} --- Bitwise logical OR 11404@fnindex OR 11405@cindex bitwise logical or 11406@cindex logical or, bitwise 11407 11408@table @asis 11409@item @emph{Description}: 11410Bitwise logical @code{OR}. 11411 11412This intrinsic routine is provided for backwards compatibility with 11413GNU Fortran 77. For integer arguments, programmers should consider 11414the use of the @ref{IOR} intrinsic defined by the Fortran standard. 11415 11416@item @emph{Standard}: 11417GNU extension 11418 11419@item @emph{Class}: 11420Function 11421 11422@item @emph{Syntax}: 11423@code{RESULT = OR(I, J)} 11424 11425@item @emph{Arguments}: 11426@multitable @columnfractions .15 .70 11427@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 11428type or a scalar @code{LOGICAL} type or a boz-literal-constant. 11429@item @var{J} @tab The type shall be the same as the type of @var{I} or 11430a boz-literal-constant. @var{I} and @var{J} shall not both be 11431boz-literal-constants. If either @var{I} and @var{J} is a 11432boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 11433@end multitable 11434 11435@item @emph{Return value}: 11436The return type is either a scalar @code{INTEGER} or a scalar 11437@code{LOGICAL}. If the kind type parameters differ, then the 11438smaller kind type is implicitly converted to larger kind, and the 11439return has the larger kind. A boz-literal-constant is 11440converted to an @code{INTEGER} with the kind type parameter of 11441the other argument as-if a call to @ref{INT} occurred. 11442 11443@item @emph{Example}: 11444@smallexample 11445PROGRAM test_or 11446 LOGICAL :: T = .TRUE., F = .FALSE. 11447 INTEGER :: a, b 11448 DATA a / Z'F' /, b / Z'3' / 11449 11450 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F) 11451 WRITE (*,*) OR(a, b) 11452END PROGRAM 11453@end smallexample 11454 11455@item @emph{See also}: 11456Fortran 95 elemental function: @gol 11457@ref{IOR} 11458@end table 11459 11460 11461 11462@node PACK 11463@section @code{PACK} --- Pack an array into an array of rank one 11464@fnindex PACK 11465@cindex array, packing 11466@cindex array, reduce dimension 11467@cindex array, gather elements 11468 11469@table @asis 11470@item @emph{Description}: 11471Stores the elements of @var{ARRAY} in an array of rank one. 11472 11473The beginning of the resulting array is made up of elements whose @var{MASK} 11474equals @code{TRUE}. Afterwards, positions are filled with elements taken from 11475@var{VECTOR}. 11476 11477@item @emph{Standard}: 11478Fortran 90 and later 11479 11480@item @emph{Class}: 11481Transformational function 11482 11483@item @emph{Syntax}: 11484@code{RESULT = PACK(ARRAY, MASK[,VECTOR])} 11485 11486@item @emph{Arguments}: 11487@multitable @columnfractions .15 .70 11488@item @var{ARRAY} @tab Shall be an array of any type. 11489@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and 11490of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} 11491scalar. 11492@item @var{VECTOR} @tab (Optional) shall be an array of the same type 11493as @var{ARRAY} and of rank one. If present, the number of elements in 11494@var{VECTOR} shall be equal to or greater than the number of true elements 11495in @var{MASK}. If @var{MASK} is scalar, the number of elements in 11496@var{VECTOR} shall be equal to or greater than the number of elements in 11497@var{ARRAY}. 11498@end multitable 11499 11500@item @emph{Return value}: 11501The result is an array of rank one and the same type as that of @var{ARRAY}. 11502If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the 11503number of @code{TRUE} values in @var{MASK} otherwise. 11504 11505@item @emph{Example}: 11506Gathering nonzero elements from an array: 11507@smallexample 11508PROGRAM test_pack_1 11509 INTEGER :: m(6) 11510 m = (/ 1, 0, 0, 0, 5, 0 /) 11511 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5" 11512END PROGRAM 11513@end smallexample 11514 11515Gathering nonzero elements from an array and appending elements from @var{VECTOR}: 11516@smallexample 11517PROGRAM test_pack_2 11518 INTEGER :: m(4) 11519 m = (/ 1, 0, 0, 2 /) 11520 ! The following results in "1 2 3 4" 11521 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) 11522END PROGRAM 11523@end smallexample 11524 11525@item @emph{See also}: 11526@ref{UNPACK} 11527@end table 11528 11529 11530 11531@node PARITY 11532@section @code{PARITY} --- Reduction with exclusive OR 11533@fnindex PARITY 11534@cindex Parity 11535@cindex Reduction, XOR 11536@cindex XOR reduction 11537 11538@table @asis 11539@item @emph{Description}: 11540Calculates the parity, i.e. the reduction using @code{.XOR.}, 11541of @var{MASK} along dimension @var{DIM}. 11542 11543@item @emph{Standard}: 11544Fortran 2008 and later 11545 11546@item @emph{Class}: 11547Transformational function 11548 11549@item @emph{Syntax}: 11550@multitable @columnfractions .80 11551@item @code{RESULT = PARITY(MASK[, DIM])} 11552@end multitable 11553 11554@item @emph{Arguments}: 11555@multitable @columnfractions .15 .70 11556@item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL} 11557@item @var{DIM} @tab (Optional) shall be a scalar of type 11558@code{INTEGER} with a value in the range from 1 to n, where n 11559equals the rank of @var{MASK}. 11560@end multitable 11561 11562@item @emph{Return value}: 11563The result is of the same type as @var{MASK}. 11564 11565If @var{DIM} is absent, a scalar with the parity of all elements in 11566@var{MASK} is returned, i.e. true if an odd number of elements is 11567@code{.true.} and false otherwise. If @var{DIM} is present, an array 11568of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, 11569and a shape similar to that of @var{MASK} with dimension @var{DIM} 11570dropped is returned. 11571 11572@item @emph{Example}: 11573@smallexample 11574PROGRAM test_sum 11575 LOGICAL :: x(2) = [ .true., .false. ] 11576 print *, PARITY(x) ! prints "T" (true). 11577END PROGRAM 11578@end smallexample 11579@end table 11580 11581 11582 11583@node PERROR 11584@section @code{PERROR} --- Print system error message 11585@fnindex PERROR 11586@cindex system, error handling 11587 11588@table @asis 11589@item @emph{Description}: 11590Prints (on the C @code{stderr} stream) a newline-terminated error 11591message corresponding to the last system error. This is prefixed by 11592@var{STRING}, a colon and a space. See @code{perror(3)}. 11593 11594@item @emph{Standard}: 11595GNU extension 11596 11597@item @emph{Class}: 11598Subroutine 11599 11600@item @emph{Syntax}: 11601@code{CALL PERROR(STRING)} 11602 11603@item @emph{Arguments}: 11604@multitable @columnfractions .15 .70 11605@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the 11606default kind. 11607@end multitable 11608 11609@item @emph{See also}: 11610@ref{IERRNO} 11611@end table 11612 11613 11614 11615@node POPCNT 11616@section @code{POPCNT} --- Number of bits set 11617@fnindex POPCNT 11618@cindex binary representation 11619@cindex bits set 11620 11621@table @asis 11622@item @emph{Description}: 11623@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary 11624representation of @code{I}. 11625 11626@item @emph{Standard}: 11627Fortran 2008 and later 11628 11629@item @emph{Class}: 11630Elemental function 11631 11632@item @emph{Syntax}: 11633@code{RESULT = POPCNT(I)} 11634 11635@item @emph{Arguments}: 11636@multitable @columnfractions .15 .70 11637@item @var{I} @tab Shall be of type @code{INTEGER}. 11638@end multitable 11639 11640@item @emph{Return value}: 11641The return value is of type @code{INTEGER} and of the default integer 11642kind. 11643 11644@item @emph{Example}: 11645@smallexample 11646program test_population 11647 print *, popcnt(127), poppar(127) 11648 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11649 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11650end program test_population 11651@end smallexample 11652@item @emph{See also}: 11653@ref{POPPAR}, @gol 11654@ref{LEADZ}, @gol 11655@ref{TRAILZ} 11656@end table 11657 11658 11659 11660@node POPPAR 11661@section @code{POPPAR} --- Parity of the number of bits set 11662@fnindex POPPAR 11663@cindex binary representation 11664@cindex parity 11665 11666@table @asis 11667@item @emph{Description}: 11668@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity 11669of the number of bits set ('1' bits) in the binary representation of 11670@code{I}. It is equal to 0 if @code{I} has an even number of bits set, 11671and 1 for an odd number of '1' bits. 11672 11673@item @emph{Standard}: 11674Fortran 2008 and later 11675 11676@item @emph{Class}: 11677Elemental function 11678 11679@item @emph{Syntax}: 11680@code{RESULT = POPPAR(I)} 11681 11682@item @emph{Arguments}: 11683@multitable @columnfractions .15 .70 11684@item @var{I} @tab Shall be of type @code{INTEGER}. 11685@end multitable 11686 11687@item @emph{Return value}: 11688The return value is of type @code{INTEGER} and of the default integer 11689kind. 11690 11691@item @emph{Example}: 11692@smallexample 11693program test_population 11694 print *, popcnt(127), poppar(127) 11695 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11696 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11697end program test_population 11698@end smallexample 11699@item @emph{See also}: 11700@ref{POPCNT}, @gol 11701@ref{LEADZ}, @gol 11702@ref{TRAILZ} 11703@end table 11704 11705 11706 11707@node PRECISION 11708@section @code{PRECISION} --- Decimal precision of a real kind 11709@fnindex PRECISION 11710@cindex model representation, precision 11711 11712@table @asis 11713@item @emph{Description}: 11714@code{PRECISION(X)} returns the decimal precision in the model of the 11715type of @code{X}. 11716 11717@item @emph{Standard}: 11718Fortran 90 and later 11719 11720@item @emph{Class}: 11721Inquiry function 11722 11723@item @emph{Syntax}: 11724@code{RESULT = PRECISION(X)} 11725 11726@item @emph{Arguments}: 11727@multitable @columnfractions .15 .70 11728@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may 11729be scalar or valued. 11730@end multitable 11731 11732@item @emph{Return value}: 11733The return value is of type @code{INTEGER} and of the default integer 11734kind. 11735 11736@item @emph{Example}: 11737@smallexample 11738program prec_and_range 11739 real(kind=4) :: x(2) 11740 complex(kind=8) :: y 11741 11742 print *, precision(x), range(x) 11743 print *, precision(y), range(y) 11744end program prec_and_range 11745@end smallexample 11746@item @emph{See also}: 11747@ref{SELECTED_REAL_KIND}, @gol 11748@ref{RANGE} 11749@end table 11750 11751 11752 11753@node PRESENT 11754@section @code{PRESENT} --- Determine whether an optional dummy argument is specified 11755@fnindex PRESENT 11756 11757@table @asis 11758@item @emph{Description}: 11759Determines whether an optional dummy argument is present. 11760 11761@item @emph{Standard}: 11762Fortran 90 and later 11763 11764@item @emph{Class}: 11765Inquiry function 11766 11767@item @emph{Syntax}: 11768@code{RESULT = PRESENT(A)} 11769 11770@item @emph{Arguments}: 11771@multitable @columnfractions .15 .70 11772@item @var{A} @tab May be of any type and may be a pointer, scalar or array 11773value, or a dummy procedure. It shall be the name of an optional dummy argument 11774accessible within the current subroutine or function. 11775@end multitable 11776 11777@item @emph{Return value}: 11778Returns either @code{TRUE} if the optional argument @var{A} is present, or 11779@code{FALSE} otherwise. 11780 11781@item @emph{Example}: 11782@smallexample 11783PROGRAM test_present 11784 WRITE(*,*) f(), f(42) ! "F T" 11785CONTAINS 11786 LOGICAL FUNCTION f(x) 11787 INTEGER, INTENT(IN), OPTIONAL :: x 11788 f = PRESENT(x) 11789 END FUNCTION 11790END PROGRAM 11791@end smallexample 11792@end table 11793 11794 11795 11796@node PRODUCT 11797@section @code{PRODUCT} --- Product of array elements 11798@fnindex PRODUCT 11799@cindex array, product 11800@cindex array, multiply elements 11801@cindex array, conditionally multiply elements 11802@cindex multiply array elements 11803 11804@table @asis 11805@item @emph{Description}: 11806Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if 11807the corresponding element in @var{MASK} is @code{TRUE}. 11808 11809@item @emph{Standard}: 11810Fortran 90 and later 11811 11812@item @emph{Class}: 11813Transformational function 11814 11815@item @emph{Syntax}: 11816@multitable @columnfractions .80 11817@item @code{RESULT = PRODUCT(ARRAY[, MASK])} 11818@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])} 11819@end multitable 11820 11821@item @emph{Arguments}: 11822@multitable @columnfractions .15 .70 11823@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 11824@code{REAL} or @code{COMPLEX}. 11825@item @var{DIM} @tab (Optional) shall be a scalar of type 11826@code{INTEGER} with a value in the range from 1 to n, where n 11827equals the rank of @var{ARRAY}. 11828@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 11829and either be a scalar or an array of the same shape as @var{ARRAY}. 11830@end multitable 11831 11832@item @emph{Return value}: 11833The result is of the same type as @var{ARRAY}. 11834 11835If @var{DIM} is absent, a scalar with the product of all elements in 11836@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 11837the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 11838dimension @var{DIM} dropped is returned. 11839 11840 11841@item @emph{Example}: 11842@smallexample 11843PROGRAM test_product 11844 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 11845 print *, PRODUCT(x) ! all elements, product = 120 11846 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15 11847END PROGRAM 11848@end smallexample 11849 11850@item @emph{See also}: 11851@ref{SUM} 11852@end table 11853 11854 11855 11856@node RADIX 11857@section @code{RADIX} --- Base of a model number 11858@fnindex RADIX 11859@cindex model representation, base 11860@cindex model representation, radix 11861 11862@table @asis 11863@item @emph{Description}: 11864@code{RADIX(X)} returns the base of the model representing the entity @var{X}. 11865 11866@item @emph{Standard}: 11867Fortran 90 and later 11868 11869@item @emph{Class}: 11870Inquiry function 11871 11872@item @emph{Syntax}: 11873@code{RESULT = RADIX(X)} 11874 11875@item @emph{Arguments}: 11876@multitable @columnfractions .15 .70 11877@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL} 11878@end multitable 11879 11880@item @emph{Return value}: 11881The return value is a scalar of type @code{INTEGER} and of the default 11882integer kind. 11883 11884@item @emph{Example}: 11885@smallexample 11886program test_radix 11887 print *, "The radix for the default integer kind is", radix(0) 11888 print *, "The radix for the default real kind is", radix(0.0) 11889end program test_radix 11890@end smallexample 11891@item @emph{See also}: 11892@ref{SELECTED_REAL_KIND} 11893@end table 11894 11895 11896 11897@node RAN 11898@section @code{RAN} --- Real pseudo-random number 11899@fnindex RAN 11900@cindex random number generation 11901 11902@table @asis 11903@item @emph{Description}: 11904For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is 11905provided as an alias for @code{RAND}. See @ref{RAND} for complete 11906documentation. 11907 11908@item @emph{Standard}: 11909GNU extension 11910 11911@item @emph{Class}: 11912Function 11913 11914@item @emph{See also}: 11915@ref{RAND}, @gol 11916@ref{RANDOM_NUMBER} 11917@end table 11918 11919 11920 11921@node RAND 11922@section @code{RAND} --- Real pseudo-random number 11923@fnindex RAND 11924@cindex random number generation 11925 11926@table @asis 11927@item @emph{Description}: 11928@code{RAND(FLAG)} returns a pseudo-random number from a uniform 11929distribution between 0 and 1. If @var{FLAG} is 0, the next number 11930in the current sequence is returned; if @var{FLAG} is 1, the generator 11931is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 11932it is used as a new seed with @code{SRAND}. 11933 11934This intrinsic routine is provided for backwards compatibility with 11935GNU Fortran 77. It implements a simple modulo generator as provided 11936by @command{g77}. For new code, one should consider the use of 11937@ref{RANDOM_NUMBER} as it implements a superior algorithm. 11938 11939@item @emph{Standard}: 11940GNU extension 11941 11942@item @emph{Class}: 11943Function 11944 11945@item @emph{Syntax}: 11946@code{RESULT = RAND(I)} 11947 11948@item @emph{Arguments}: 11949@multitable @columnfractions .15 .70 11950@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 11951@end multitable 11952 11953@item @emph{Return value}: 11954The return value is of @code{REAL} type and the default kind. 11955 11956@item @emph{Example}: 11957@smallexample 11958program test_rand 11959 integer,parameter :: seed = 86456 11960 11961 call srand(seed) 11962 print *, rand(), rand(), rand(), rand() 11963 print *, rand(seed), rand(), rand(), rand() 11964end program test_rand 11965@end smallexample 11966 11967@item @emph{See also}: 11968@ref{SRAND}, @gol 11969@ref{RANDOM_NUMBER} 11970 11971@end table 11972 11973 11974@node RANDOM_INIT 11975@section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator 11976@fnindex RANDOM_INIT 11977@cindex random number generation, initialization 11978 11979@table @asis 11980@item @emph{Description}: 11981Initializes the state of the pseudorandom number generator used by 11982@code{RANDOM_NUMBER}. 11983 11984@item @emph{Standard}: 11985Fortran 2018 11986 11987@item @emph{Class}: 11988Subroutine 11989 11990@item @emph{Syntax}: 11991@code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)} 11992 11993@item @emph{Arguments}: 11994@multitable @columnfractions .25 .70 11995@item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type, 11996and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to 11997a processor-dependent value that is the same each time @code{RANDOM_INIT} 11998is called from the same image. The term ``same image'' means a single 11999instance of program execution. The sequence of random numbers is different 12000for repeated execution of the program. If it is @code{.false.}, the seed 12001is set to a processor-dependent value. 12002@item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a 12003@code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.}, 12004the seed is set to a processor-dependent value that is distinct from th 12005seed set by a call to @code{RANDOM_INIT} in another image. If it is 12006@code{.false.}, the seed is set value that does depend which image called 12007@code{RANDOM_INIT}. 12008@end multitable 12009 12010@item @emph{Example}: 12011@smallexample 12012program test_random_seed 12013 implicit none 12014 real x(3), y(3) 12015 call random_init(.true., .true.) 12016 call random_number(x) 12017 call random_init(.true., .true.) 12018 call random_number(y) 12019 ! x and y are the same sequence 12020 if (any(x /= y)) call abort 12021end program test_random_seed 12022@end smallexample 12023 12024@item @emph{See also}: 12025@ref{RANDOM_NUMBER}, @gol 12026@ref{RANDOM_SEED} 12027@end table 12028 12029 12030@node RANDOM_NUMBER 12031@section @code{RANDOM_NUMBER} --- Pseudo-random number 12032@fnindex RANDOM_NUMBER 12033@cindex random number generation 12034 12035@table @asis 12036@item @emph{Description}: 12037Returns a single pseudorandom number or an array of pseudorandom numbers 12038from the uniform distribution over the range @math{ 0 \leq x < 1}. 12039 12040The runtime-library implements the xoshiro256** pseudorandom number 12041generator (PRNG). This generator has a period of @math{2^{256} - 1}, 12042and when using multiple threads up to @math{2^{128}} threads can each 12043generate @math{2^{128}} random numbers before any aliasing occurs. 12044 12045Note that in a multi-threaded program (e.g. using OpenMP directives), 12046each thread will have its own random number state. For details of the 12047seeding procedure, see the documentation for the @code{RANDOM_SEED} 12048intrinsic. 12049 12050 12051@item @emph{Standard}: 12052Fortran 90 and later 12053 12054@item @emph{Class}: 12055Subroutine 12056 12057@item @emph{Syntax}: 12058@code{RANDOM_NUMBER(HARVEST)} 12059 12060@item @emph{Arguments}: 12061@multitable @columnfractions .15 .70 12062@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}. 12063@end multitable 12064 12065@item @emph{Example}: 12066@smallexample 12067program test_random_number 12068 REAL :: r(5,5) 12069 CALL RANDOM_NUMBER(r) 12070end program 12071@end smallexample 12072 12073@item @emph{See also}: 12074@ref{RANDOM_SEED}, @gol 12075@ref{RANDOM_INIT} 12076@end table 12077 12078 12079 12080@node RANDOM_SEED 12081@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence 12082@fnindex RANDOM_SEED 12083@cindex random number generation, seeding 12084@cindex seeding a random number generator 12085 12086@table @asis 12087@item @emph{Description}: 12088Restarts or queries the state of the pseudorandom number generator used by 12089@code{RANDOM_NUMBER}. 12090 12091If @code{RANDOM_SEED} is called without arguments, it is seeded with 12092random data retrieved from the operating system. 12093 12094As an extension to the Fortran standard, the GFortran 12095@code{RANDOM_NUMBER} supports multiple threads. Each thread in a 12096multi-threaded program has its own seed. When @code{RANDOM_SEED} is 12097called either without arguments or with the @var{PUT} argument, the 12098given seed is copied into a master seed as well as the seed of the 12099current thread. When a new thread uses @code{RANDOM_NUMBER} for the 12100first time, the seed is copied from the master seed, and forwarded 12101@math{N * 2^{128}} steps to guarantee that the random stream does not 12102alias any other stream in the system, where @var{N} is the number of 12103threads that have used @code{RANDOM_NUMBER} so far during the program 12104execution. 12105 12106@item @emph{Standard}: 12107Fortran 90 and later 12108 12109@item @emph{Class}: 12110Subroutine 12111 12112@item @emph{Syntax}: 12113@code{CALL RANDOM_SEED([SIZE, PUT, GET])} 12114 12115@item @emph{Arguments}: 12116@multitable @columnfractions .15 .70 12117@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default 12118@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size 12119of the arrays used with the @var{PUT} and @var{GET} arguments. 12120@item @var{PUT} @tab (Optional) Shall be an array of type default 12121@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of 12122the array must be larger than or equal to the number returned by the 12123@var{SIZE} argument. 12124@item @var{GET} @tab (Optional) Shall be an array of type default 12125@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size 12126of the array must be larger than or equal to the number returned by 12127the @var{SIZE} argument. 12128@end multitable 12129 12130@item @emph{Example}: 12131@smallexample 12132program test_random_seed 12133 implicit none 12134 integer, allocatable :: seed(:) 12135 integer :: n 12136 12137 call random_seed(size = n) 12138 allocate(seed(n)) 12139 call random_seed(get=seed) 12140 write (*, *) seed 12141end program test_random_seed 12142@end smallexample 12143 12144@item @emph{See also}: 12145@ref{RANDOM_NUMBER}, @gol 12146@ref{RANDOM_INIT} 12147@end table 12148 12149 12150 12151@node RANGE 12152@section @code{RANGE} --- Decimal exponent range 12153@fnindex RANGE 12154@cindex model representation, range 12155 12156@table @asis 12157@item @emph{Description}: 12158@code{RANGE(X)} returns the decimal exponent range in the model of the 12159type of @code{X}. 12160 12161@item @emph{Standard}: 12162Fortran 90 and later 12163 12164@item @emph{Class}: 12165Inquiry function 12166 12167@item @emph{Syntax}: 12168@code{RESULT = RANGE(X)} 12169 12170@item @emph{Arguments}: 12171@multitable @columnfractions .15 .70 12172@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL} 12173or @code{COMPLEX}. 12174@end multitable 12175 12176@item @emph{Return value}: 12177The return value is of type @code{INTEGER} and of the default integer 12178kind. 12179 12180@item @emph{Example}: 12181See @code{PRECISION} for an example. 12182@item @emph{See also}: 12183@ref{SELECTED_REAL_KIND}, @gol 12184@ref{PRECISION} 12185@end table 12186 12187 12188 12189@node RANK 12190@section @code{RANK} --- Rank of a data object 12191@fnindex RANK 12192@cindex rank 12193 12194@table @asis 12195@item @emph{Description}: 12196@code{RANK(A)} returns the rank of a scalar or array data object. 12197 12198@item @emph{Standard}: 12199Technical Specification (TS) 29113 12200 12201@item @emph{Class}: 12202Inquiry function 12203 12204@item @emph{Syntax}: 12205@code{RESULT = RANK(A)} 12206 12207@item @emph{Arguments}: 12208@multitable @columnfractions .15 .70 12209@item @var{A} @tab can be of any type 12210@end multitable 12211 12212@item @emph{Return value}: 12213The return value is of type @code{INTEGER} and of the default integer 12214kind. For arrays, their rank is returned; for scalars zero is returned. 12215 12216@item @emph{Example}: 12217@smallexample 12218program test_rank 12219 integer :: a 12220 real, allocatable :: b(:,:) 12221 12222 print *, rank(a), rank(b) ! Prints: 0 2 12223end program test_rank 12224@end smallexample 12225 12226@end table 12227 12228 12229 12230@node REAL 12231@section @code{REAL} --- Convert to real type 12232@fnindex REAL 12233@fnindex REALPART 12234@fnindex FLOAT 12235@fnindex DFLOAT 12236@fnindex FLOATI 12237@fnindex FLOATJ 12238@fnindex FLOATK 12239@fnindex SNGL 12240@cindex conversion, to real 12241@cindex complex numbers, real part 12242 12243@table @asis 12244@item @emph{Description}: 12245@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The 12246@code{REALPART} function is provided for compatibility with @command{g77}, 12247and its use is strongly discouraged. 12248 12249@item @emph{Standard}: 12250Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions 12251 12252@item @emph{Class}: 12253Elemental function 12254 12255@item @emph{Syntax}: 12256@multitable @columnfractions .80 12257@item @code{RESULT = REAL(A [, KIND])} 12258@item @code{RESULT = REALPART(Z)} 12259@end multitable 12260 12261@item @emph{Arguments}: 12262@multitable @columnfractions .15 .70 12263@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or 12264@code{COMPLEX}. 12265@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12266expression indicating the kind parameter of the result. 12267@end multitable 12268 12269@item @emph{Return value}: 12270These functions return a @code{REAL} variable or array under 12271the following rules: 12272 12273@table @asis 12274@item (A) 12275@code{REAL(A)} is converted to a default real type if @var{A} is an 12276integer or real variable. 12277@item (B) 12278@code{REAL(A)} is converted to a real type with the kind type parameter 12279of @var{A} if @var{A} is a complex variable. 12280@item (C) 12281@code{REAL(A, KIND)} is converted to a real type with kind type 12282parameter @var{KIND} if @var{A} is a complex, integer, or real 12283variable. 12284@end table 12285 12286@item @emph{Example}: 12287@smallexample 12288program test_real 12289 complex :: x = (1.0, 2.0) 12290 print *, real(x), real(x,8), realpart(x) 12291end program test_real 12292@end smallexample 12293 12294@item @emph{Specific names}: 12295@multitable @columnfractions .20 .20 .20 .25 12296@item Name @tab Argument @tab Return type @tab Standard 12297@item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension 12298@item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension 12299@item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension 12300@item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension 12301@item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension 12302@item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension 12303@end multitable 12304 12305 12306@item @emph{See also}: 12307@ref{DBLE} 12308 12309@end table 12310 12311 12312 12313@node RENAME 12314@section @code{RENAME} --- Rename a file 12315@fnindex RENAME 12316@cindex file system, rename file 12317 12318@table @asis 12319@item @emph{Description}: 12320Renames a file from file @var{PATH1} to @var{PATH2}. A null 12321character (@code{CHAR(0)}) can be used to mark the end of the names in 12322@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 12323names are ignored. If the @var{STATUS} argument is supplied, it 12324contains 0 on success or a nonzero error code upon return; see 12325@code{rename(2)}. 12326 12327This intrinsic is provided in both subroutine and function forms; 12328however, only one form can be used in any given program unit. 12329 12330@item @emph{Standard}: 12331GNU extension 12332 12333@item @emph{Class}: 12334Subroutine, function 12335 12336@item @emph{Syntax}: 12337@multitable @columnfractions .80 12338@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])} 12339@item @code{STATUS = RENAME(PATH1, PATH2)} 12340@end multitable 12341 12342@item @emph{Arguments}: 12343@multitable @columnfractions .15 .70 12344@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 12345@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 12346@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 12347@end multitable 12348 12349@item @emph{See also}: 12350@ref{LINK} 12351 12352@end table 12353 12354 12355 12356@node REPEAT 12357@section @code{REPEAT} --- Repeated string concatenation 12358@fnindex REPEAT 12359@cindex string, repeat 12360@cindex string, concatenate 12361 12362@table @asis 12363@item @emph{Description}: 12364Concatenates @var{NCOPIES} copies of a string. 12365 12366@item @emph{Standard}: 12367Fortran 90 and later 12368 12369@item @emph{Class}: 12370Transformational function 12371 12372@item @emph{Syntax}: 12373@code{RESULT = REPEAT(STRING, NCOPIES)} 12374 12375@item @emph{Arguments}: 12376@multitable @columnfractions .15 .70 12377@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}. 12378@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}. 12379@end multitable 12380 12381@item @emph{Return value}: 12382A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies 12383of @var{STRING}. 12384 12385@item @emph{Example}: 12386@smallexample 12387program test_repeat 12388 write(*,*) repeat("x", 5) ! "xxxxx" 12389end program 12390@end smallexample 12391@end table 12392 12393 12394 12395@node RESHAPE 12396@section @code{RESHAPE} --- Function to reshape an array 12397@fnindex RESHAPE 12398@cindex array, change dimensions 12399@cindex array, transmogrify 12400 12401@table @asis 12402@item @emph{Description}: 12403Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary, 12404the new array may be padded with elements from @var{PAD} or permuted 12405as defined by @var{ORDER}. 12406 12407@item @emph{Standard}: 12408Fortran 90 and later 12409 12410@item @emph{Class}: 12411Transformational function 12412 12413@item @emph{Syntax}: 12414@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])} 12415 12416@item @emph{Arguments}: 12417@multitable @columnfractions .15 .70 12418@item @var{SOURCE} @tab Shall be an array of any type. 12419@item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an 12420array of rank one. Its values must be positive or zero. 12421@item @var{PAD} @tab (Optional) shall be an array of the same 12422type as @var{SOURCE}. 12423@item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER} 12424and an array of the same shape as @var{SHAPE}. Its values shall 12425be a permutation of the numbers from 1 to n, where n is the size of 12426@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall 12427be assumed. 12428@end multitable 12429 12430@item @emph{Return value}: 12431The result is an array of shape @var{SHAPE} with the same type as 12432@var{SOURCE}. 12433 12434@item @emph{Example}: 12435@smallexample 12436PROGRAM test_reshape 12437 INTEGER, DIMENSION(4) :: x 12438 WRITE(*,*) SHAPE(x) ! prints "4" 12439 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" 12440END PROGRAM 12441@end smallexample 12442 12443@item @emph{See also}: 12444@ref{SHAPE} 12445@end table 12446 12447 12448 12449@node RRSPACING 12450@section @code{RRSPACING} --- Reciprocal of the relative spacing 12451@fnindex RRSPACING 12452@cindex real number, relative spacing 12453@cindex floating point, relative spacing 12454 12455 12456@table @asis 12457@item @emph{Description}: 12458@code{RRSPACING(X)} returns the reciprocal of the relative spacing of 12459model numbers near @var{X}. 12460 12461@item @emph{Standard}: 12462Fortran 90 and later 12463 12464@item @emph{Class}: 12465Elemental function 12466 12467@item @emph{Syntax}: 12468@code{RESULT = RRSPACING(X)} 12469 12470@item @emph{Arguments}: 12471@multitable @columnfractions .15 .70 12472@item @var{X} @tab Shall be of type @code{REAL}. 12473@end multitable 12474 12475@item @emph{Return value}: 12476The return value is of the same type and kind as @var{X}. 12477The value returned is equal to 12478@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}. 12479 12480@item @emph{See also}: 12481@ref{SPACING} 12482@end table 12483 12484 12485 12486@node RSHIFT 12487@section @code{RSHIFT} --- Right shift bits 12488@fnindex RSHIFT 12489@cindex bits, shift right 12490 12491@table @asis 12492@item @emph{Description}: 12493@code{RSHIFT} returns a value corresponding to @var{I} with all of the 12494bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be 12495nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 12496the result value is undefined. Bits shifted out from the right end 12497are lost. The fill is arithmetic: the bits shifted in from the left 12498end are equal to the leftmost bit, which in two's complement 12499representation is the sign bit. 12500 12501This function has been superseded by the @code{SHIFTA} intrinsic, which 12502is standard in Fortran 2008 and later. 12503 12504@item @emph{Standard}: 12505GNU extension 12506 12507@item @emph{Class}: 12508Elemental function 12509 12510@item @emph{Syntax}: 12511@code{RESULT = RSHIFT(I, SHIFT)} 12512 12513@item @emph{Arguments}: 12514@multitable @columnfractions .15 .70 12515@item @var{I} @tab The type shall be @code{INTEGER}. 12516@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12517@end multitable 12518 12519@item @emph{Return value}: 12520The return value is of type @code{INTEGER} and of the same kind as 12521@var{I}. 12522 12523@item @emph{See also}: 12524@ref{ISHFT}, @gol 12525@ref{ISHFTC}, @gol 12526@ref{LSHIFT}, @gol 12527@ref{SHIFTA}, @gol 12528@ref{SHIFTR}, @gol 12529@ref{SHIFTL} 12530 12531@end table 12532 12533 12534 12535@node SAME_TYPE_AS 12536@section @code{SAME_TYPE_AS} --- Query dynamic types for equality 12537@fnindex SAME_TYPE_AS 12538 12539@table @asis 12540@item @emph{Description}: 12541Query dynamic types for equality. 12542 12543@item @emph{Standard}: 12544Fortran 2003 and later 12545 12546@item @emph{Class}: 12547Inquiry function 12548 12549@item @emph{Syntax}: 12550@code{RESULT = SAME_TYPE_AS(A, B)} 12551 12552@item @emph{Arguments}: 12553@multitable @columnfractions .15 .70 12554@item @var{A} @tab Shall be an object of extensible declared type or 12555unlimited polymorphic. 12556@item @var{B} @tab Shall be an object of extensible declared type or 12557unlimited polymorphic. 12558@end multitable 12559 12560@item @emph{Return value}: 12561The return value is a scalar of type default logical. It is true if and 12562only if the dynamic type of A is the same as the dynamic type of B. 12563 12564@item @emph{See also}: 12565@ref{EXTENDS_TYPE_OF} 12566 12567@end table 12568 12569 12570 12571@node SCALE 12572@section @code{SCALE} --- Scale a real value 12573@fnindex SCALE 12574@cindex real number, scale 12575@cindex floating point, scale 12576 12577@table @asis 12578@item @emph{Description}: 12579@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}. 12580 12581@item @emph{Standard}: 12582Fortran 90 and later 12583 12584@item @emph{Class}: 12585Elemental function 12586 12587@item @emph{Syntax}: 12588@code{RESULT = SCALE(X, I)} 12589 12590@item @emph{Arguments}: 12591@multitable @columnfractions .15 .70 12592@item @var{X} @tab The type of the argument shall be a @code{REAL}. 12593@item @var{I} @tab The type of the argument shall be a @code{INTEGER}. 12594@end multitable 12595 12596@item @emph{Return value}: 12597The return value is of the same type and kind as @var{X}. 12598Its value is @code{X * RADIX(X)**I}. 12599 12600@item @emph{Example}: 12601@smallexample 12602program test_scale 12603 real :: x = 178.1387e-4 12604 integer :: i = 5 12605 print *, scale(x,i), x*radix(x)**i 12606end program test_scale 12607@end smallexample 12608 12609@end table 12610 12611 12612 12613@node SCAN 12614@section @code{SCAN} --- Scan a string for the presence of a set of characters 12615@fnindex SCAN 12616@cindex string, find subset 12617 12618@table @asis 12619@item @emph{Description}: 12620Scans a @var{STRING} for any of the characters in a @var{SET} 12621of characters. 12622 12623If @var{BACK} is either absent or equals @code{FALSE}, this function 12624returns the position of the leftmost character of @var{STRING} that is 12625in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position 12626is returned. If no character of @var{SET} is found in @var{STRING}, the 12627result is zero. 12628 12629@item @emph{Standard}: 12630Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 12631 12632@item @emph{Class}: 12633Elemental function 12634 12635@item @emph{Syntax}: 12636@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])} 12637 12638@item @emph{Arguments}: 12639@multitable @columnfractions .15 .70 12640@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 12641@item @var{SET} @tab Shall be of type @code{CHARACTER}. 12642@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 12643@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12644expression indicating the kind parameter of the result. 12645@end multitable 12646 12647@item @emph{Return value}: 12648The return value is of type @code{INTEGER} and of kind @var{KIND}. If 12649@var{KIND} is absent, the return value is of default integer kind. 12650 12651@item @emph{Example}: 12652@smallexample 12653PROGRAM test_scan 12654 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O' 12655 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A' 12656 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none 12657END PROGRAM 12658@end smallexample 12659 12660@item @emph{See also}: 12661@ref{INDEX intrinsic}, @gol 12662@ref{VERIFY} 12663@end table 12664 12665 12666 12667@node SECNDS 12668@section @code{SECNDS} --- Time function 12669@fnindex SECNDS 12670@cindex time, elapsed 12671@cindex elapsed time 12672 12673@table @asis 12674@item @emph{Description}: 12675@code{SECNDS(X)} gets the time in seconds from the real-time system clock. 12676@var{X} is a reference time, also in seconds. If this is zero, the time in 12677seconds from midnight is returned. This function is non-standard and its 12678use is discouraged. 12679 12680@item @emph{Standard}: 12681GNU extension 12682 12683@item @emph{Class}: 12684Function 12685 12686@item @emph{Syntax}: 12687@code{RESULT = SECNDS (X)} 12688 12689@item @emph{Arguments}: 12690@multitable @columnfractions .15 .70 12691@item @var{T} @tab Shall be of type @code{REAL(4)}. 12692@item @var{X} @tab Shall be of type @code{REAL(4)}. 12693@end multitable 12694 12695@item @emph{Return value}: 12696None 12697 12698@item @emph{Example}: 12699@smallexample 12700program test_secnds 12701 integer :: i 12702 real(4) :: t1, t2 12703 print *, secnds (0.0) ! seconds since midnight 12704 t1 = secnds (0.0) ! reference time 12705 do i = 1, 10000000 ! do something 12706 end do 12707 t2 = secnds (t1) ! elapsed time 12708 print *, "Something took ", t2, " seconds." 12709end program test_secnds 12710@end smallexample 12711@end table 12712 12713 12714 12715@node SECOND 12716@section @code{SECOND} --- CPU time function 12717@fnindex SECOND 12718@cindex time, elapsed 12719@cindex elapsed time 12720 12721@table @asis 12722@item @emph{Description}: 12723Returns a @code{REAL(4)} value representing the elapsed CPU time in 12724seconds. This provides the same functionality as the standard 12725@code{CPU_TIME} intrinsic, and is only included for backwards 12726compatibility. 12727 12728This intrinsic is provided in both subroutine and function forms; 12729however, only one form can be used in any given program unit. 12730 12731@item @emph{Standard}: 12732GNU extension 12733 12734@item @emph{Class}: 12735Subroutine, function 12736 12737@item @emph{Syntax}: 12738@multitable @columnfractions .80 12739@item @code{CALL SECOND(TIME)} 12740@item @code{TIME = SECOND()} 12741@end multitable 12742 12743@item @emph{Arguments}: 12744@multitable @columnfractions .15 .70 12745@item @var{TIME} @tab Shall be of type @code{REAL(4)}. 12746@end multitable 12747 12748@item @emph{Return value}: 12749In either syntax, @var{TIME} is set to the process's current runtime in 12750seconds. 12751 12752@item @emph{See also}: 12753@ref{CPU_TIME} 12754 12755@end table 12756 12757 12758 12759@node SELECTED_CHAR_KIND 12760@section @code{SELECTED_CHAR_KIND} --- Choose character kind 12761@fnindex SELECTED_CHAR_KIND 12762@cindex character kind 12763@cindex kind, character 12764 12765@table @asis 12766@item @emph{Description}: 12767 12768@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character 12769set named @var{NAME}, if a character set with such a name is supported, 12770or @math{-1} otherwise. Currently, supported character sets include 12771``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646'' 12772(Universal Character Set, UCS-4) which is commonly known as Unicode. 12773 12774@item @emph{Standard}: 12775Fortran 2003 and later 12776 12777@item @emph{Class}: 12778Transformational function 12779 12780@item @emph{Syntax}: 12781@code{RESULT = SELECTED_CHAR_KIND(NAME)} 12782 12783@item @emph{Arguments}: 12784@multitable @columnfractions .15 .70 12785@item @var{NAME} @tab Shall be a scalar and of the default character type. 12786@end multitable 12787 12788@item @emph{Example}: 12789@smallexample 12790program character_kind 12791 use iso_fortran_env 12792 implicit none 12793 integer, parameter :: ascii = selected_char_kind ("ascii") 12794 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646') 12795 12796 character(kind=ascii, len=26) :: alphabet 12797 character(kind=ucs4, len=30) :: hello_world 12798 12799 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz" 12800 hello_world = ucs4_'Hello World and Ni Hao -- ' & 12801 // char (int (z'4F60'), ucs4) & 12802 // char (int (z'597D'), ucs4) 12803 12804 write (*,*) alphabet 12805 12806 open (output_unit, encoding='UTF-8') 12807 write (*,*) trim (hello_world) 12808end program character_kind 12809@end smallexample 12810@end table 12811 12812 12813 12814@node SELECTED_INT_KIND 12815@section @code{SELECTED_INT_KIND} --- Choose integer kind 12816@fnindex SELECTED_INT_KIND 12817@cindex integer kind 12818@cindex kind, integer 12819 12820@table @asis 12821@item @emph{Description}: 12822@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer 12823type that can represent all values ranging from @math{-10^R} (exclusive) 12824to @math{10^R} (exclusive). If there is no integer kind that accommodates 12825this range, @code{SELECTED_INT_KIND} returns @math{-1}. 12826 12827@item @emph{Standard}: 12828Fortran 90 and later 12829 12830@item @emph{Class}: 12831Transformational function 12832 12833@item @emph{Syntax}: 12834@code{RESULT = SELECTED_INT_KIND(R)} 12835 12836@item @emph{Arguments}: 12837@multitable @columnfractions .15 .70 12838@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}. 12839@end multitable 12840 12841@item @emph{Example}: 12842@smallexample 12843program large_integers 12844 integer,parameter :: k5 = selected_int_kind(5) 12845 integer,parameter :: k15 = selected_int_kind(15) 12846 integer(kind=k5) :: i5 12847 integer(kind=k15) :: i15 12848 12849 print *, huge(i5), huge(i15) 12850 12851 ! The following inequalities are always true 12852 print *, huge(i5) >= 10_k5**5-1 12853 print *, huge(i15) >= 10_k15**15-1 12854end program large_integers 12855@end smallexample 12856@end table 12857 12858 12859 12860@node SELECTED_REAL_KIND 12861@section @code{SELECTED_REAL_KIND} --- Choose real kind 12862@fnindex SELECTED_REAL_KIND 12863@cindex real kind 12864@cindex kind, real 12865@cindex radix, real 12866 12867@table @asis 12868@item @emph{Description}: 12869@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type 12870with decimal precision of at least @code{P} digits, exponent range of 12871at least @code{R}, and with a radix of @code{RADIX}. 12872 12873@item @emph{Standard}: 12874Fortran 90 and later, with @code{RADIX} Fortran 2008 or later 12875 12876@item @emph{Class}: 12877Transformational function 12878 12879@item @emph{Syntax}: 12880@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])} 12881 12882@item @emph{Arguments}: 12883@multitable @columnfractions .15 .70 12884@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12885@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12886@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12887@end multitable 12888Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall 12889be present; since Fortran 2008, they are assumed to be zero if absent. 12890 12891@item @emph{Return value}: 12892 12893@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of 12894a real data type with decimal precision of at least @code{P} digits, a 12895decimal exponent range of at least @code{R}, and with the requested 12896@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with 12897any radix can be returned. If more than one real data type meet the 12898criteria, the kind of the data type with the smallest decimal precision 12899is returned. If no real data type matches the criteria, the result is 12900@table @asis 12901@item -1 if the processor does not support a real data type with a 12902precision greater than or equal to @code{P}, but the @code{R} and 12903@code{RADIX} requirements can be fulfilled 12904@item -2 if the processor does not support a real type with an exponent 12905range greater than or equal to @code{R}, but @code{P} and @code{RADIX} 12906are fulfillable 12907@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements 12908are fulfillable 12909@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements 12910are fulfillable 12911@item -5 if there is no real type with the given @code{RADIX} 12912@end table 12913 12914@item @emph{Example}: 12915@smallexample 12916program real_kinds 12917 integer,parameter :: p6 = selected_real_kind(6) 12918 integer,parameter :: p10r100 = selected_real_kind(10,100) 12919 integer,parameter :: r400 = selected_real_kind(r=400) 12920 real(kind=p6) :: x 12921 real(kind=p10r100) :: y 12922 real(kind=r400) :: z 12923 12924 print *, precision(x), range(x) 12925 print *, precision(y), range(y) 12926 print *, precision(z), range(z) 12927end program real_kinds 12928@end smallexample 12929@item @emph{See also}: 12930@ref{PRECISION}, @gol 12931@ref{RANGE}, @gol 12932@ref{RADIX} 12933@end table 12934 12935 12936 12937@node SET_EXPONENT 12938@section @code{SET_EXPONENT} --- Set the exponent of the model 12939@fnindex SET_EXPONENT 12940@cindex real number, set exponent 12941@cindex floating point, set exponent 12942 12943@table @asis 12944@item @emph{Description}: 12945@code{SET_EXPONENT(X, I)} returns the real number whose fractional part 12946is that that of @var{X} and whose exponent part is @var{I}. 12947 12948@item @emph{Standard}: 12949Fortran 90 and later 12950 12951@item @emph{Class}: 12952Elemental function 12953 12954@item @emph{Syntax}: 12955@code{RESULT = SET_EXPONENT(X, I)} 12956 12957@item @emph{Arguments}: 12958@multitable @columnfractions .15 .70 12959@item @var{X} @tab Shall be of type @code{REAL}. 12960@item @var{I} @tab Shall be of type @code{INTEGER}. 12961@end multitable 12962 12963@item @emph{Return value}: 12964The return value is of the same type and kind as @var{X}. 12965The real number whose fractional part 12966is that that of @var{X} and whose exponent part if @var{I} is returned; 12967it is @code{FRACTION(X) * RADIX(X)**I}. 12968 12969@item @emph{Example}: 12970@smallexample 12971PROGRAM test_setexp 12972 REAL :: x = 178.1387e-4 12973 INTEGER :: i = 17 12974 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i 12975END PROGRAM 12976@end smallexample 12977 12978@end table 12979 12980 12981 12982@node SHAPE 12983@section @code{SHAPE} --- Determine the shape of an array 12984@fnindex SHAPE 12985@cindex array, shape 12986 12987@table @asis 12988@item @emph{Description}: 12989Determines the shape of an array. 12990 12991@item @emph{Standard}: 12992Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 12993 12994@item @emph{Class}: 12995Inquiry function 12996 12997@item @emph{Syntax}: 12998@code{RESULT = SHAPE(SOURCE [, KIND])} 12999 13000@item @emph{Arguments}: 13001@multitable @columnfractions .15 .70 13002@item @var{SOURCE} @tab Shall be an array or scalar of any type. 13003If @var{SOURCE} is a pointer it must be associated and allocatable 13004arrays must be allocated. 13005@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13006expression indicating the kind parameter of the result. 13007@end multitable 13008 13009@item @emph{Return value}: 13010An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 13011has dimensions. The elements of the resulting array correspond to the extend 13012of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar, 13013the result is the rank one array of size zero. If @var{KIND} is absent, the 13014return value has the default integer kind otherwise the specified kind. 13015 13016@item @emph{Example}: 13017@smallexample 13018PROGRAM test_shape 13019 INTEGER, DIMENSION(-1:1, -1:2) :: A 13020 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) 13021 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) 13022END PROGRAM 13023@end smallexample 13024 13025@item @emph{See also}: 13026@ref{RESHAPE}, @gol 13027@ref{SIZE} 13028@end table 13029 13030 13031 13032@node SHIFTA 13033@section @code{SHIFTA} --- Right shift with fill 13034@fnindex SHIFTA 13035@cindex bits, shift right 13036@cindex shift, right with fill 13037 13038@table @asis 13039@item @emph{Description}: 13040@code{SHIFTA} returns a value corresponding to @var{I} with all of the 13041bits shifted right by @var{SHIFT} places. @var{SHIFT} that be 13042nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 13043the result value is undefined. Bits shifted out from the right end 13044are lost. The fill is arithmetic: the bits shifted in from the left 13045end are equal to the leftmost bit, which in two's complement 13046representation is the sign bit. 13047 13048@item @emph{Standard}: 13049Fortran 2008 and later 13050 13051@item @emph{Class}: 13052Elemental function 13053 13054@item @emph{Syntax}: 13055@code{RESULT = SHIFTA(I, SHIFT)} 13056 13057@item @emph{Arguments}: 13058@multitable @columnfractions .15 .70 13059@item @var{I} @tab The type shall be @code{INTEGER}. 13060@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13061@end multitable 13062 13063@item @emph{Return value}: 13064The return value is of type @code{INTEGER} and of the same kind as 13065@var{I}. 13066 13067@item @emph{See also}: 13068@ref{SHIFTL}, @gol 13069@ref{SHIFTR} 13070@end table 13071 13072 13073 13074@node SHIFTL 13075@section @code{SHIFTL} --- Left shift 13076@fnindex SHIFTL 13077@cindex bits, shift left 13078@cindex shift, left 13079 13080@table @asis 13081@item @emph{Description}: 13082@code{SHIFTL} returns a value corresponding to @var{I} with all of the 13083bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be 13084nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 13085the result value is undefined. Bits shifted out from the left end are 13086lost, and bits shifted in from the right end are set to 0. 13087 13088@item @emph{Standard}: 13089Fortran 2008 and later 13090 13091@item @emph{Class}: 13092Elemental function 13093 13094@item @emph{Syntax}: 13095@code{RESULT = SHIFTL(I, SHIFT)} 13096 13097@item @emph{Arguments}: 13098@multitable @columnfractions .15 .70 13099@item @var{I} @tab The type shall be @code{INTEGER}. 13100@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13101@end multitable 13102 13103@item @emph{Return value}: 13104The return value is of type @code{INTEGER} and of the same kind as 13105@var{I}. 13106 13107@item @emph{See also}: 13108@ref{SHIFTA}, @gol 13109@ref{SHIFTR} 13110@end table 13111 13112 13113 13114@node SHIFTR 13115@section @code{SHIFTR} --- Right shift 13116@fnindex SHIFTR 13117@cindex bits, shift right 13118@cindex shift, right 13119 13120@table @asis 13121@item @emph{Description}: 13122@code{SHIFTR} returns a value corresponding to @var{I} with all of the 13123bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be 13124nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 13125the result value is undefined. Bits shifted out from the right end 13126are lost, and bits shifted in from the left end are set to 0. 13127 13128@item @emph{Standard}: 13129Fortran 2008 and later 13130 13131@item @emph{Class}: 13132Elemental function 13133 13134@item @emph{Syntax}: 13135@code{RESULT = SHIFTR(I, SHIFT)} 13136 13137@item @emph{Arguments}: 13138@multitable @columnfractions .15 .70 13139@item @var{I} @tab The type shall be @code{INTEGER}. 13140@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 13141@end multitable 13142 13143@item @emph{Return value}: 13144The return value is of type @code{INTEGER} and of the same kind as 13145@var{I}. 13146 13147@item @emph{See also}: 13148@ref{SHIFTA}, @gol 13149@ref{SHIFTL} 13150@end table 13151 13152 13153 13154@node SIGN 13155@section @code{SIGN} --- Sign copying function 13156@fnindex SIGN 13157@fnindex ISIGN 13158@fnindex DSIGN 13159@cindex sign copying 13160 13161@table @asis 13162@item @emph{Description}: 13163@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}. 13164 13165@item @emph{Standard}: 13166Fortran 77 and later 13167 13168@item @emph{Class}: 13169Elemental function 13170 13171@item @emph{Syntax}: 13172@code{RESULT = SIGN(A, B)} 13173 13174@item @emph{Arguments}: 13175@multitable @columnfractions .15 .70 13176@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL} 13177@item @var{B} @tab Shall be of the same type and kind as @var{A}. 13178@end multitable 13179 13180@item @emph{Return value}: 13181The kind of the return value is that of @var{A} and @var{B}. 13182If @math{B\ge 0} then the result is @code{ABS(A)}, else 13183it is @code{-ABS(A)}. 13184 13185@item @emph{Example}: 13186@smallexample 13187program test_sign 13188 print *, sign(-12,1) 13189 print *, sign(-12,0) 13190 print *, sign(-12,-1) 13191 13192 print *, sign(-12.,1.) 13193 print *, sign(-12.,0.) 13194 print *, sign(-12.,-1.) 13195end program test_sign 13196@end smallexample 13197 13198@item @emph{Specific names}: 13199@multitable @columnfractions .20 .20 .20 .25 13200@item Name @tab Arguments @tab Return type @tab Standard 13201@item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later 13202@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later 13203@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later 13204@end multitable 13205@end table 13206 13207 13208 13209@node SIGNAL 13210@section @code{SIGNAL} --- Signal handling subroutine (or function) 13211@fnindex SIGNAL 13212@cindex system, signal handling 13213 13214@table @asis 13215@item @emph{Description}: 13216@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine 13217@var{HANDLER} to be executed with a single integer argument when signal 13218@var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to 13219turn off handling of signal @var{NUMBER} or revert to its default 13220action. See @code{signal(2)}. 13221 13222If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument 13223is supplied, it is set to the value returned by @code{signal(2)}. 13224 13225@item @emph{Standard}: 13226GNU extension 13227 13228@item @emph{Class}: 13229Subroutine, function 13230 13231@item @emph{Syntax}: 13232@multitable @columnfractions .80 13233@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])} 13234@item @code{STATUS = SIGNAL(NUMBER, HANDLER)} 13235@end multitable 13236 13237@item @emph{Arguments}: 13238@multitable @columnfractions .15 .70 13239@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)} 13240@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or 13241@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. 13242@code{INTEGER}. It is @code{INTENT(IN)}. 13243@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 13244integer. It has @code{INTENT(OUT)}. 13245@end multitable 13246@c TODO: What should the interface of the handler be? Does it take arguments? 13247 13248@item @emph{Return value}: 13249The @code{SIGNAL} function returns the value returned by @code{signal(2)}. 13250 13251@item @emph{Example}: 13252@smallexample 13253program test_signal 13254 intrinsic signal 13255 external handler_print 13256 13257 call signal (12, handler_print) 13258 call signal (10, 1) 13259 13260 call sleep (30) 13261end program test_signal 13262@end smallexample 13263@end table 13264 13265 13266 13267@node SIN 13268@section @code{SIN} --- Sine function 13269@fnindex SIN 13270@fnindex DSIN 13271@fnindex CSIN 13272@fnindex ZSIN 13273@fnindex CDSIN 13274@cindex trigonometric function, sine 13275@cindex sine 13276 13277@table @asis 13278@item @emph{Description}: 13279@code{SIN(X)} computes the sine of @var{X}. 13280 13281@item @emph{Standard}: 13282Fortran 77 and later 13283 13284@item @emph{Class}: 13285Elemental function 13286 13287@item @emph{Syntax}: 13288@code{RESULT = SIN(X)} 13289 13290@item @emph{Arguments}: 13291@multitable @columnfractions .15 .70 13292@item @var{X} @tab The type shall be @code{REAL} or 13293@code{COMPLEX}. 13294@end multitable 13295 13296@item @emph{Return value}: 13297The return value has same type and kind as @var{X}. 13298 13299@item @emph{Example}: 13300@smallexample 13301program test_sin 13302 real :: x = 0.0 13303 x = sin(x) 13304end program test_sin 13305@end smallexample 13306 13307@item @emph{Specific names}: 13308@multitable @columnfractions .20 .20 .20 .25 13309@item Name @tab Argument @tab Return type @tab Standard 13310@item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 13311@item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 13312@item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 13313@item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13314@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13315@end multitable 13316 13317@item @emph{See also}: 13318Inverse function: @gol 13319@ref{ASIN} @gol 13320Degrees function: @gol 13321@ref{SIND} 13322@end table 13323 13324 13325 13326@node SIND 13327@section @code{SIND} --- Sine function, degrees 13328@fnindex SIND 13329@fnindex DSIND 13330@fnindex CSIND 13331@fnindex ZSIND 13332@fnindex CDSIND 13333@cindex trigonometric function, sine, degrees 13334@cindex sine, degrees 13335 13336@table @asis 13337@item @emph{Description}: 13338@code{SIND(X)} computes the sine of @var{X} in degrees. 13339 13340This function is for compatibility only and should be avoided in favor of 13341standard constructs wherever possible. 13342 13343@item @emph{Standard}: 13344GNU extension, enabled with @option{-fdec-math}. 13345 13346@item @emph{Class}: 13347Elemental function 13348 13349@item @emph{Syntax}: 13350@code{RESULT = SIND(X)} 13351 13352@item @emph{Arguments}: 13353@multitable @columnfractions .15 .70 13354@item @var{X} @tab The type shall be @code{REAL} or 13355@code{COMPLEX}. 13356@end multitable 13357 13358@item @emph{Return value}: 13359The return value has same type and kind as @var{X}, and its value is in degrees. 13360 13361@item @emph{Example}: 13362@smallexample 13363program test_sind 13364 real :: x = 0.0 13365 x = sind(x) 13366end program test_sind 13367@end smallexample 13368 13369@item @emph{Specific names}: 13370@multitable @columnfractions .20 .20 .20 .25 13371@item Name @tab Argument @tab Return type @tab Standard 13372@item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 13373@item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 13374@item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension 13375@item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13376@item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13377@end multitable 13378 13379@item @emph{See also}: 13380Inverse function: @gol 13381@ref{ASIND} @gol 13382Radians function: @gol 13383@ref{SIN} @gol 13384@end table 13385 13386 13387 13388@node SINH 13389@section @code{SINH} --- Hyperbolic sine function 13390@fnindex SINH 13391@fnindex DSINH 13392@cindex hyperbolic sine 13393@cindex hyperbolic function, sine 13394@cindex sine, hyperbolic 13395 13396@table @asis 13397@item @emph{Description}: 13398@code{SINH(X)} computes the hyperbolic sine of @var{X}. 13399 13400@item @emph{Standard}: 13401Fortran 90 and later, for a complex argument Fortran 2008 or later, has 13402a GNU extension 13403 13404@item @emph{Class}: 13405Elemental function 13406 13407@item @emph{Syntax}: 13408@code{RESULT = SINH(X)} 13409 13410@item @emph{Arguments}: 13411@multitable @columnfractions .15 .70 13412@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13413@end multitable 13414 13415@item @emph{Return value}: 13416The return value has same type and kind as @var{X}. 13417 13418@item @emph{Example}: 13419@smallexample 13420program test_sinh 13421 real(8) :: x = - 1.0_8 13422 x = sinh(x) 13423end program test_sinh 13424@end smallexample 13425 13426@item @emph{Specific names}: 13427@multitable @columnfractions .20 .20 .20 .25 13428@item Name @tab Argument @tab Return type @tab Standard 13429@item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 and later 13430@end multitable 13431 13432@item @emph{See also}: 13433@ref{ASINH} 13434@end table 13435 13436 13437 13438@node SIZE 13439@section @code{SIZE} --- Determine the size of an array 13440@fnindex SIZE 13441@cindex array, size 13442@cindex array, number of elements 13443@cindex array, count elements 13444 13445@table @asis 13446@item @emph{Description}: 13447Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}, 13448or the total number of elements in @var{ARRAY} if @var{DIM} is absent. 13449 13450@item @emph{Standard}: 13451Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 13452 13453@item @emph{Class}: 13454Inquiry function 13455 13456@item @emph{Syntax}: 13457@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])} 13458 13459@item @emph{Arguments}: 13460@multitable @columnfractions .15 .70 13461@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is 13462a pointer it must be associated and allocatable arrays must be allocated. 13463@item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} 13464and its value shall be in the range from 1 to n, where n equals the rank 13465of @var{ARRAY}. 13466@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13467expression indicating the kind parameter of the result. 13468@end multitable 13469 13470@item @emph{Return value}: 13471The return value is of type @code{INTEGER} and of kind @var{KIND}. If 13472@var{KIND} is absent, the return value is of default integer kind. 13473 13474@item @emph{Example}: 13475@smallexample 13476PROGRAM test_size 13477 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 13478END PROGRAM 13479@end smallexample 13480 13481@item @emph{See also}: 13482@ref{SHAPE}, @gol 13483@ref{RESHAPE} 13484@end table 13485 13486 13487@node SIZEOF 13488@section @code{SIZEOF} --- Size in bytes of an expression 13489@fnindex SIZEOF 13490@cindex expression size 13491@cindex size of an expression 13492 13493@table @asis 13494@item @emph{Description}: 13495@code{SIZEOF(X)} calculates the number of bytes of storage the 13496expression @code{X} occupies. 13497 13498@item @emph{Standard}: 13499GNU extension 13500 13501@item @emph{Class}: 13502Inquiry function 13503 13504@item @emph{Syntax}: 13505@code{N = SIZEOF(X)} 13506 13507@item @emph{Arguments}: 13508@multitable @columnfractions .15 .70 13509@item @var{X} @tab The argument shall be of any type, rank or shape. 13510@end multitable 13511 13512@item @emph{Return value}: 13513The return value is of type integer and of the system-dependent kind 13514@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the 13515number of bytes occupied by the argument. If the argument has the 13516@code{POINTER} attribute, the number of bytes of the storage area pointed 13517to is returned. If the argument is of a derived type with @code{POINTER} 13518or @code{ALLOCATABLE} components, the return value does not account for 13519the sizes of the data pointed to by these components. If the argument is 13520polymorphic, the size according to the dynamic type is returned. The argument 13521may not be a procedure or procedure pointer. Note that the code assumes for 13522arrays that those are contiguous; for contiguous arrays, it returns the 13523storage or an array element multiplied by the size of the array. 13524 13525@item @emph{Example}: 13526@smallexample 13527 integer :: i 13528 real :: r, s(5) 13529 print *, (sizeof(s)/sizeof(r) == 5) 13530 end 13531@end smallexample 13532The example will print @code{.TRUE.} unless you are using a platform 13533where default @code{REAL} variables are unusually padded. 13534 13535@item @emph{See also}: 13536@ref{C_SIZEOF}, @gol 13537@ref{STORAGE_SIZE} 13538@end table 13539 13540 13541@node SLEEP 13542@section @code{SLEEP} --- Sleep for the specified number of seconds 13543@fnindex SLEEP 13544@cindex delayed execution 13545 13546@table @asis 13547@item @emph{Description}: 13548Calling this subroutine causes the process to pause for @var{SECONDS} seconds. 13549 13550@item @emph{Standard}: 13551GNU extension 13552 13553@item @emph{Class}: 13554Subroutine 13555 13556@item @emph{Syntax}: 13557@code{CALL SLEEP(SECONDS)} 13558 13559@item @emph{Arguments}: 13560@multitable @columnfractions .15 .70 13561@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}. 13562@end multitable 13563 13564@item @emph{Example}: 13565@smallexample 13566program test_sleep 13567 call sleep(5) 13568end 13569@end smallexample 13570@end table 13571 13572 13573 13574@node SPACING 13575@section @code{SPACING} --- Smallest distance between two numbers of a given type 13576@fnindex SPACING 13577@cindex real number, relative spacing 13578@cindex floating point, relative spacing 13579 13580@table @asis 13581@item @emph{Description}: 13582Determines the distance between the argument @var{X} and the nearest 13583adjacent number of the same type. 13584 13585@item @emph{Standard}: 13586Fortran 90 and later 13587 13588@item @emph{Class}: 13589Elemental function 13590 13591@item @emph{Syntax}: 13592@code{RESULT = SPACING(X)} 13593 13594@item @emph{Arguments}: 13595@multitable @columnfractions .15 .70 13596@item @var{X} @tab Shall be of type @code{REAL}. 13597@end multitable 13598 13599@item @emph{Return value}: 13600The result is of the same type as the input argument @var{X}. 13601 13602@item @emph{Example}: 13603@smallexample 13604PROGRAM test_spacing 13605 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37) 13606 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200) 13607 13608 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686 13609 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686 13610END PROGRAM 13611@end smallexample 13612 13613@item @emph{See also}: 13614@ref{RRSPACING} 13615@end table 13616 13617 13618 13619@node SPREAD 13620@section @code{SPREAD} --- Add a dimension to an array 13621@fnindex SPREAD 13622@cindex array, increase dimension 13623@cindex array, duplicate elements 13624@cindex array, duplicate dimensions 13625 13626@table @asis 13627@item @emph{Description}: 13628Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified 13629dimension @var{DIM}. 13630 13631@item @emph{Standard}: 13632Fortran 90 and later 13633 13634@item @emph{Class}: 13635Transformational function 13636 13637@item @emph{Syntax}: 13638@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)} 13639 13640@item @emph{Arguments}: 13641@multitable @columnfractions .15 .70 13642@item @var{SOURCE} @tab Shall be a scalar or an array of any type and 13643a rank less than seven. 13644@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a 13645value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}. 13646@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}. 13647@end multitable 13648 13649@item @emph{Return value}: 13650The result is an array of the same type as @var{SOURCE} and has rank n+1 13651where n equals the rank of @var{SOURCE}. 13652 13653@item @emph{Example}: 13654@smallexample 13655PROGRAM test_spread 13656 INTEGER :: a = 1, b(2) = (/ 1, 2 /) 13657 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1" 13658 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2" 13659END PROGRAM 13660@end smallexample 13661 13662@item @emph{See also}: 13663@ref{UNPACK} 13664@end table 13665 13666 13667 13668@node SQRT 13669@section @code{SQRT} --- Square-root function 13670@fnindex SQRT 13671@fnindex DSQRT 13672@fnindex CSQRT 13673@fnindex ZSQRT 13674@fnindex CDSQRT 13675@cindex root 13676@cindex square-root 13677 13678@table @asis 13679@item @emph{Description}: 13680@code{SQRT(X)} computes the square root of @var{X}. 13681 13682@item @emph{Standard}: 13683Fortran 77 and later 13684 13685@item @emph{Class}: 13686Elemental function 13687 13688@item @emph{Syntax}: 13689@code{RESULT = SQRT(X)} 13690 13691@item @emph{Arguments}: 13692@multitable @columnfractions .15 .70 13693@item @var{X} @tab The type shall be @code{REAL} or 13694@code{COMPLEX}. 13695@end multitable 13696 13697@item @emph{Return value}: 13698The return value is of type @code{REAL} or @code{COMPLEX}. 13699The kind type parameter is the same as @var{X}. 13700 13701@item @emph{Example}: 13702@smallexample 13703program test_sqrt 13704 real(8) :: x = 2.0_8 13705 complex :: z = (1.0, 2.0) 13706 x = sqrt(x) 13707 z = sqrt(z) 13708end program test_sqrt 13709@end smallexample 13710 13711@item @emph{Specific names}: 13712@multitable @columnfractions .20 .20 .20 .25 13713@item Name @tab Argument @tab Return type @tab Standard 13714@item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 13715@item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 13716@item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 13717@item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13718@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13719@end multitable 13720@end table 13721 13722 13723 13724@node SRAND 13725@section @code{SRAND} --- Reinitialize the random number generator 13726@fnindex SRAND 13727@cindex random number generation, seeding 13728@cindex seeding a random number generator 13729 13730@table @asis 13731@item @emph{Description}: 13732@code{SRAND} reinitializes the pseudo-random number generator 13733called by @code{RAND} and @code{IRAND}. The new seed used by the 13734generator is specified by the required argument @var{SEED}. 13735 13736@item @emph{Standard}: 13737GNU extension 13738 13739@item @emph{Class}: 13740Subroutine 13741 13742@item @emph{Syntax}: 13743@code{CALL SRAND(SEED)} 13744 13745@item @emph{Arguments}: 13746@multitable @columnfractions .15 .70 13747@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}. 13748@end multitable 13749 13750@item @emph{Return value}: 13751Does not return anything. 13752 13753@item @emph{Example}: 13754See @code{RAND} and @code{IRAND} for examples. 13755 13756@item @emph{Notes}: 13757The Fortran standard specifies the intrinsic subroutines 13758@code{RANDOM_SEED} to initialize the pseudo-random number 13759generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers. 13760These subroutines should be used in new codes. 13761 13762Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND}, 13763@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and 13764@code{RANDOM_SEED} on the other hand) access two independent 13765pseudo-random number generators. 13766 13767@item @emph{See also}: 13768@ref{RAND}, @gol 13769@ref{RANDOM_SEED}, @gol 13770@ref{RANDOM_NUMBER} 13771@end table 13772 13773 13774 13775@node STAT 13776@section @code{STAT} --- Get file status 13777@fnindex STAT 13778@cindex file system, file status 13779 13780@table @asis 13781@item @emph{Description}: 13782This function returns information about a file. No permissions are required on 13783the file itself, but execute (search) permission is required on all of the 13784directories in path that lead to the file. 13785 13786The elements that are obtained and stored in the array @code{VALUES}: 13787@multitable @columnfractions .15 .70 13788@item @code{VALUES(1)} @tab Device ID 13789@item @code{VALUES(2)} @tab Inode number 13790@item @code{VALUES(3)} @tab File mode 13791@item @code{VALUES(4)} @tab Number of links 13792@item @code{VALUES(5)} @tab Owner's uid 13793@item @code{VALUES(6)} @tab Owner's gid 13794@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available) 13795@item @code{VALUES(8)} @tab File size (bytes) 13796@item @code{VALUES(9)} @tab Last access time 13797@item @code{VALUES(10)} @tab Last modification time 13798@item @code{VALUES(11)} @tab Last file status change time 13799@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available) 13800@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available) 13801@end multitable 13802 13803Not all these elements are relevant on all systems. 13804If an element is not relevant, it is returned as 0. 13805 13806This intrinsic is provided in both subroutine and function forms; however, 13807only one form can be used in any given program unit. 13808 13809@item @emph{Standard}: 13810GNU extension 13811 13812@item @emph{Class}: 13813Subroutine, function 13814 13815@item @emph{Syntax}: 13816@multitable @columnfractions .80 13817@item @code{CALL STAT(NAME, VALUES [, STATUS])} 13818@item @code{STATUS = STAT(NAME, VALUES)} 13819@end multitable 13820 13821@item @emph{Arguments}: 13822@multitable @columnfractions .15 .70 13823@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the 13824default kind and a valid path within the file system. 13825@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 13826@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 13827on success and a system specific error code otherwise. 13828@end multitable 13829 13830@item @emph{Example}: 13831@smallexample 13832PROGRAM test_stat 13833 INTEGER, DIMENSION(13) :: buff 13834 INTEGER :: status 13835 13836 CALL STAT("/etc/passwd", buff, status) 13837 13838 IF (status == 0) THEN 13839 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1) 13840 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2) 13841 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3) 13842 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4) 13843 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5) 13844 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6) 13845 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7) 13846 WRITE (*, FMT="('File size:', T30, I19)") buff(8) 13847 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9)) 13848 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10)) 13849 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11)) 13850 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12) 13851 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13) 13852 END IF 13853END PROGRAM 13854@end smallexample 13855 13856@item @emph{See also}: 13857To stat an open file: @gol 13858@ref{FSTAT} @gol 13859To stat a link: @gol 13860@ref{LSTAT} 13861@end table 13862 13863 13864 13865@node STORAGE_SIZE 13866@section @code{STORAGE_SIZE} --- Storage size in bits 13867@fnindex STORAGE_SIZE 13868@cindex storage size 13869 13870@table @asis 13871@item @emph{Description}: 13872Returns the storage size of argument @var{A} in bits. 13873@item @emph{Standard}: 13874Fortran 2008 and later 13875@item @emph{Class}: 13876Inquiry function 13877@item @emph{Syntax}: 13878@code{RESULT = STORAGE_SIZE(A [, KIND])} 13879 13880@item @emph{Arguments}: 13881@multitable @columnfractions .15 .70 13882@item @var{A} @tab Shall be a scalar or array of any type. 13883@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression. 13884@end multitable 13885 13886@item @emph{Return Value}: 13887The result is a scalar integer with the kind type parameter specified by KIND 13888(or default integer type if KIND is missing). The result value is the size 13889expressed in bits for an element of an array that has the dynamic type and type 13890parameters of A. 13891 13892@item @emph{See also}: 13893@ref{C_SIZEOF}, @gol 13894@ref{SIZEOF} 13895@end table 13896 13897 13898 13899@node SUM 13900@section @code{SUM} --- Sum of array elements 13901@fnindex SUM 13902@cindex array, sum 13903@cindex array, add elements 13904@cindex array, conditionally add elements 13905@cindex sum array elements 13906 13907@table @asis 13908@item @emph{Description}: 13909Adds the elements of @var{ARRAY} along dimension @var{DIM} if 13910the corresponding element in @var{MASK} is @code{TRUE}. 13911 13912@item @emph{Standard}: 13913Fortran 90 and later 13914 13915@item @emph{Class}: 13916Transformational function 13917 13918@item @emph{Syntax}: 13919@multitable @columnfractions .80 13920@item @code{RESULT = SUM(ARRAY[, MASK])} 13921@item @code{RESULT = SUM(ARRAY, DIM[, MASK])} 13922@end multitable 13923 13924@item @emph{Arguments}: 13925@multitable @columnfractions .15 .70 13926@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 13927@code{REAL} or @code{COMPLEX}. 13928@item @var{DIM} @tab (Optional) shall be a scalar of type 13929@code{INTEGER} with a value in the range from 1 to n, where n 13930equals the rank of @var{ARRAY}. 13931@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 13932and either be a scalar or an array of the same shape as @var{ARRAY}. 13933@end multitable 13934 13935@item @emph{Return value}: 13936The result is of the same type as @var{ARRAY}. 13937 13938If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY} 13939is returned. Otherwise, an array of rank n-1, where n equals the rank of 13940@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} 13941dropped is returned. 13942 13943@item @emph{Example}: 13944@smallexample 13945PROGRAM test_sum 13946 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 13947 print *, SUM(x) ! all elements, sum = 15 13948 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9 13949END PROGRAM 13950@end smallexample 13951 13952@item @emph{See also}: 13953@ref{PRODUCT} 13954@end table 13955 13956 13957 13958@node SYMLNK 13959@section @code{SYMLNK} --- Create a symbolic link 13960@fnindex SYMLNK 13961@cindex file system, create link 13962@cindex file system, soft link 13963 13964@table @asis 13965@item @emph{Description}: 13966Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null 13967character (@code{CHAR(0)}) can be used to mark the end of the names in 13968@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 13969names are ignored. If the @var{STATUS} argument is supplied, it 13970contains 0 on success or a nonzero error code upon return; see 13971@code{symlink(2)}. If the system does not supply @code{symlink(2)}, 13972@code{ENOSYS} is returned. 13973 13974This intrinsic is provided in both subroutine and function forms; 13975however, only one form can be used in any given program unit. 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 SYMLNK(PATH1, PATH2 [, STATUS])} 13986@item @code{STATUS = SYMLNK(PATH1, PATH2)} 13987@end multitable 13988 13989@item @emph{Arguments}: 13990@multitable @columnfractions .15 .70 13991@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 13992@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 13993@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13994@end multitable 13995 13996@item @emph{See also}: 13997@ref{LINK}, @gol 13998@ref{UNLINK} 13999@end table 14000 14001 14002 14003@node SYSTEM 14004@section @code{SYSTEM} --- Execute a shell command 14005@fnindex SYSTEM 14006@cindex system, system call 14007 14008@table @asis 14009@item @emph{Description}: 14010Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If 14011argument @var{STATUS} is present, it contains the value returned by 14012@code{system(3)}, which is presumably 0 if the shell command succeeded. 14013Note that which shell is used to invoke the command is system-dependent 14014and environment-dependent. 14015 14016This intrinsic is provided in both subroutine and function forms; 14017however, only one form can be used in any given program unit. 14018 14019Note that the @code{system} function need not be thread-safe. It is 14020the responsibility of the user to ensure that @code{system} is not 14021called concurrently. 14022 14023@item @emph{Standard}: 14024GNU extension 14025 14026@item @emph{Class}: 14027Subroutine, function 14028 14029@item @emph{Syntax}: 14030@multitable @columnfractions .80 14031@item @code{CALL SYSTEM(COMMAND [, STATUS])} 14032@item @code{STATUS = SYSTEM(COMMAND)} 14033@end multitable 14034 14035@item @emph{Arguments}: 14036@multitable @columnfractions .15 .70 14037@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type. 14038@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 14039@end multitable 14040 14041@item @emph{See also}: 14042@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard 14043and should considered in new code for future portability. 14044@end table 14045 14046 14047 14048@node SYSTEM_CLOCK 14049@section @code{SYSTEM_CLOCK} --- Time function 14050@fnindex SYSTEM_CLOCK 14051@cindex time, clock ticks 14052@cindex clock ticks 14053 14054@table @asis 14055@item @emph{Description}: 14056Determines the @var{COUNT} of a processor clock since an unspecified 14057time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines 14058the number of clock ticks per second. If the platform supports a 14059monotonic clock, that clock is used and can, depending on the platform 14060clock implementation, provide up to nanosecond resolution. If a 14061monotonic clock is not available, the implementation falls back to a 14062realtime clock. 14063 14064@var{COUNT_RATE} is system dependent and can vary depending on the kind of 14065the arguments. For @var{kind=4} arguments (and smaller integer kinds), 14066@var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and 14067larger integer kinds), @var{COUNT} typically represents micro- or 14068nanoseconds depending on resolution of the underlying platform clock. 14069@var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the 14070millisecond resolution of the @var{kind=4} version implies that the 14071@var{COUNT} will wrap around in roughly 25 days. In order to avoid issues 14072with the wrap around and for more precise timing, please use the 14073@var{kind=8} version. 14074 14075If there is no clock, or querying the clock fails, @var{COUNT} is set 14076to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are 14077set to zero. 14078 14079When running on a platform using the GNU C library (glibc) version 140802.16 or older, or a derivative thereof, the high resolution monotonic 14081clock is available only when linking with the @var{rt} library. This 14082can be done explicitly by adding the @code{-lrt} flag when linking the 14083application, but is also done implicitly when using OpenMP. 14084 14085On the Windows platform, the version with @var{kind=4} arguments uses 14086the @code{GetTickCount} function, whereas the @var{kind=8} version 14087uses @code{QueryPerformanceCounter} and 14088@code{QueryPerformanceCounterFrequency}. For more information, and 14089potential caveats, please see the platform documentation. 14090 14091@item @emph{Standard}: 14092Fortran 90 and later 14093 14094@item @emph{Class}: 14095Subroutine 14096 14097@item @emph{Syntax}: 14098@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} 14099 14100@item @emph{Arguments}: 14101@multitable @columnfractions .20 .65 14102@item @var{COUNT} @tab (Optional) shall be a scalar of type 14103@code{INTEGER} with @code{INTENT(OUT)}. 14104@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type 14105@code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}. 14106@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type 14107@code{INTEGER} with @code{INTENT(OUT)}. 14108@end multitable 14109 14110@item @emph{Example}: 14111@smallexample 14112PROGRAM test_system_clock 14113 INTEGER :: count, count_rate, count_max 14114 CALL SYSTEM_CLOCK(count, count_rate, count_max) 14115 WRITE(*,*) count, count_rate, count_max 14116END PROGRAM 14117@end smallexample 14118 14119@item @emph{See also}: 14120@ref{DATE_AND_TIME}, @gol 14121@ref{CPU_TIME} 14122@end table 14123 14124 14125 14126@node TAN 14127@section @code{TAN} --- Tangent function 14128@fnindex TAN 14129@fnindex DTAN 14130@cindex trigonometric function, tangent 14131@cindex tangent 14132 14133@table @asis 14134@item @emph{Description}: 14135@code{TAN(X)} computes the tangent of @var{X}. 14136 14137@item @emph{Standard}: 14138Fortran 77 and later, for a complex argument Fortran 2008 or later 14139 14140@item @emph{Class}: 14141Elemental function 14142 14143@item @emph{Syntax}: 14144@code{RESULT = TAN(X)} 14145 14146@item @emph{Arguments}: 14147@multitable @columnfractions .15 .70 14148@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14149@end multitable 14150 14151@item @emph{Return value}: 14152The return value has same type and kind as @var{X}, and its value is in radians. 14153 14154@item @emph{Example}: 14155@smallexample 14156program test_tan 14157 real(8) :: x = 0.165_8 14158 x = tan(x) 14159end program test_tan 14160@end smallexample 14161 14162@item @emph{Specific names}: 14163@multitable @columnfractions .20 .20 .20 .25 14164@item Name @tab Argument @tab Return type @tab Standard 14165@item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 14166@item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 14167@end multitable 14168 14169@item @emph{See also}: 14170Inverse function: @gol 14171@ref{ATAN} @gol 14172Degrees function: @gol 14173@ref{TAND} 14174@end table 14175 14176 14177 14178@node TAND 14179@section @code{TAND} --- Tangent function, degrees 14180@fnindex TAND 14181@fnindex DTAND 14182@cindex trigonometric function, tangent, degrees 14183@cindex tangent, degrees 14184 14185@table @asis 14186@item @emph{Description}: 14187@code{TAND(X)} computes the tangent of @var{X} in degrees. 14188 14189This function is for compatibility only and should be avoided in favor of 14190standard constructs wherever possible. 14191 14192@item @emph{Standard}: 14193GNU extension, enabled with @option{-fdec-math}. 14194 14195@item @emph{Class}: 14196Elemental function 14197 14198@item @emph{Syntax}: 14199@code{RESULT = TAND(X)} 14200 14201@item @emph{Arguments}: 14202@multitable @columnfractions .15 .70 14203@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14204@end multitable 14205 14206@item @emph{Return value}: 14207The return value has same type and kind as @var{X}, and its value is in degrees. 14208 14209@item @emph{Example}: 14210@smallexample 14211program test_tand 14212 real(8) :: x = 0.165_8 14213 x = tand(x) 14214end program test_tand 14215@end smallexample 14216 14217@item @emph{Specific names}: 14218@multitable @columnfractions .20 .20 .20 .25 14219@item Name @tab Argument @tab Return type @tab Standard 14220@item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension 14221@item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 14222@end multitable 14223 14224@item @emph{See also}: 14225Inverse function: @gol 14226@ref{ATAND} @gol 14227Radians function: @gol 14228@ref{TAN} 14229@end table 14230 14231 14232 14233@node TANH 14234@section @code{TANH} --- Hyperbolic tangent function 14235@fnindex TANH 14236@fnindex DTANH 14237@cindex hyperbolic tangent 14238@cindex hyperbolic function, tangent 14239@cindex tangent, hyperbolic 14240 14241@table @asis 14242@item @emph{Description}: 14243@code{TANH(X)} computes the hyperbolic tangent of @var{X}. 14244 14245@item @emph{Standard}: 14246Fortran 77 and later, for a complex argument Fortran 2008 or later 14247 14248@item @emph{Class}: 14249Elemental function 14250 14251@item @emph{Syntax}: 14252@code{X = TANH(X)} 14253 14254@item @emph{Arguments}: 14255@multitable @columnfractions .15 .70 14256@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 14257@end multitable 14258 14259@item @emph{Return value}: 14260The return value has same type and kind as @var{X}. If @var{X} is 14261complex, the imaginary part of the result is in radians. If @var{X} 14262is @code{REAL}, the return value lies in the range 14263@math{ - 1 \leq tanh(x) \leq 1 }. 14264 14265@item @emph{Example}: 14266@smallexample 14267program test_tanh 14268 real(8) :: x = 2.1_8 14269 x = tanh(x) 14270end program test_tanh 14271@end smallexample 14272 14273@item @emph{Specific names}: 14274@multitable @columnfractions .20 .20 .20 .25 14275@item Name @tab Argument @tab Return type @tab Standard 14276@item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 14277@item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 14278@end multitable 14279 14280@item @emph{See also}: 14281@ref{ATANH} 14282@end table 14283 14284 14285 14286@node THIS_IMAGE 14287@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image 14288@fnindex THIS_IMAGE 14289@cindex coarray, @code{THIS_IMAGE} 14290@cindex images, index of this image 14291 14292@table @asis 14293@item @emph{Description}: 14294Returns the cosubscript for this image. 14295 14296@item @emph{Standard}: 14297Fortran 2008 and later. With @var{DISTANCE} argument, 14298Technical Specification (TS) 18508 or later 14299 14300@item @emph{Class}: 14301Transformational function 14302 14303@item @emph{Syntax}: 14304@multitable @columnfractions .80 14305@item @code{RESULT = THIS_IMAGE()} 14306@item @code{RESULT = THIS_IMAGE(DISTANCE)} 14307@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} 14308@end multitable 14309 14310@item @emph{Arguments}: 14311@multitable @columnfractions .15 .70 14312@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 14313(not permitted together with @var{COARRAY}). 14314@item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} 14315present, required). 14316@item @var{DIM} @tab default integer scalar (optional). If present, 14317@var{DIM} shall be between one and the corank of @var{COARRAY}. 14318@end multitable 14319 14320 14321@item @emph{Return value}: 14322Default integer. If @var{COARRAY} is not present, it is scalar; if 14323@var{DISTANCE} is not present or has value 0, its value is the image index on 14324the invoking image for the current team, for values smaller or equal 14325distance to the initial team, it returns the image index on the ancestor team 14326which has a distance of @var{DISTANCE} from the invoking team. If 14327@var{DISTANCE} is larger than the distance to the initial team, the image 14328index of the initial team is returned. Otherwise when the @var{COARRAY} is 14329present, if @var{DIM} is not present, a rank-1 array with corank elements is 14330returned, containing the cosubscripts for @var{COARRAY} specifying the invoking 14331image. If @var{DIM} is present, a scalar is returned, with the value of 14332the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}. 14333 14334@item @emph{Example}: 14335@smallexample 14336INTEGER :: value[*] 14337INTEGER :: i 14338value = THIS_IMAGE() 14339SYNC ALL 14340IF (THIS_IMAGE() == 1) THEN 14341 DO i = 1, NUM_IMAGES() 14342 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 14343 END DO 14344END IF 14345 14346! Check whether the current image is the initial image 14347IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) 14348 error stop "something is rotten here" 14349@end smallexample 14350 14351@item @emph{See also}: 14352@ref{NUM_IMAGES}, @gol 14353@ref{IMAGE_INDEX} 14354@end table 14355 14356 14357 14358@node TIME 14359@section @code{TIME} --- Time function 14360@fnindex TIME 14361@cindex time, current 14362@cindex current time 14363 14364@table @asis 14365@item @emph{Description}: 14366Returns the current time encoded as an integer (in the manner of the 14367function @code{time(3)} in the C standard library). This value is 14368suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 14369 14370This intrinsic is not fully portable, such as to systems with 32-bit 14371@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 14372the values returned by this intrinsic might be, or become, negative, or 14373numerically less than previous values, during a single run of the 14374compiled program. 14375 14376See @ref{TIME8}, for information on a similar intrinsic that might be 14377portable to more GNU Fortran implementations, though to fewer Fortran 14378compilers. 14379 14380@item @emph{Standard}: 14381GNU extension 14382 14383@item @emph{Class}: 14384Function 14385 14386@item @emph{Syntax}: 14387@code{RESULT = TIME()} 14388 14389@item @emph{Return value}: 14390The return value is a scalar of type @code{INTEGER(4)}. 14391 14392@item @emph{See also}: 14393@ref{DATE_AND_TIME}, @gol 14394@ref{CTIME}, @gol 14395@ref{GMTIME}, @gol 14396@ref{LTIME}, @gol 14397@ref{MCLOCK}, @gol 14398@ref{TIME8} 14399@end table 14400 14401 14402 14403@node TIME8 14404@section @code{TIME8} --- Time function (64-bit) 14405@fnindex TIME8 14406@cindex time, current 14407@cindex current time 14408 14409@table @asis 14410@item @emph{Description}: 14411Returns the current time encoded as an integer (in the manner of the 14412function @code{time(3)} in the C standard library). This value is 14413suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 14414 14415@emph{Warning:} this intrinsic does not increase the range of the timing 14416values over that returned by @code{time(3)}. On a system with a 32-bit 14417@code{time(3)}, @code{TIME8} will return a 32-bit value, even though 14418it is converted to a 64-bit @code{INTEGER(8)} value. That means 14419overflows of the 32-bit value can still occur. Therefore, the values 14420returned by this intrinsic might be or become negative or numerically 14421less than previous values during a single run of the compiled program. 14422 14423@item @emph{Standard}: 14424GNU extension 14425 14426@item @emph{Class}: 14427Function 14428 14429@item @emph{Syntax}: 14430@code{RESULT = TIME8()} 14431 14432@item @emph{Return value}: 14433The return value is a scalar of type @code{INTEGER(8)}. 14434 14435@item @emph{See also}: 14436@ref{DATE_AND_TIME}, @gol 14437@ref{CTIME}, @gol 14438@ref{GMTIME}, @gol 14439@ref{LTIME}, @gol 14440@ref{MCLOCK8}, @gol 14441@ref{TIME} 14442@end table 14443 14444 14445 14446@node TINY 14447@section @code{TINY} --- Smallest positive number of a real kind 14448@fnindex TINY 14449@cindex limits, smallest number 14450@cindex model representation, smallest number 14451 14452@table @asis 14453@item @emph{Description}: 14454@code{TINY(X)} returns the smallest positive (non zero) number 14455in the model of the type of @code{X}. 14456 14457@item @emph{Standard}: 14458Fortran 90 and later 14459 14460@item @emph{Class}: 14461Inquiry function 14462 14463@item @emph{Syntax}: 14464@code{RESULT = TINY(X)} 14465 14466@item @emph{Arguments}: 14467@multitable @columnfractions .15 .70 14468@item @var{X} @tab Shall be of type @code{REAL}. 14469@end multitable 14470 14471@item @emph{Return value}: 14472The return value is of the same type and kind as @var{X} 14473 14474@item @emph{Example}: 14475See @code{HUGE} for an example. 14476@end table 14477 14478 14479 14480@node TRAILZ 14481@section @code{TRAILZ} --- Number of trailing zero bits of an integer 14482@fnindex TRAILZ 14483@cindex zero bits 14484 14485@table @asis 14486@item @emph{Description}: 14487@code{TRAILZ} returns the number of trailing zero bits of an integer. 14488 14489@item @emph{Standard}: 14490Fortran 2008 and later 14491 14492@item @emph{Class}: 14493Elemental function 14494 14495@item @emph{Syntax}: 14496@code{RESULT = TRAILZ(I)} 14497 14498@item @emph{Arguments}: 14499@multitable @columnfractions .15 .70 14500@item @var{I} @tab Shall be of type @code{INTEGER}. 14501@end multitable 14502 14503@item @emph{Return value}: 14504The type of the return value is the default @code{INTEGER}. 14505If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 14506 14507@item @emph{Example}: 14508@smallexample 14509PROGRAM test_trailz 14510 WRITE (*,*) TRAILZ(8) ! prints 3 14511END PROGRAM 14512@end smallexample 14513 14514@item @emph{See also}: 14515@ref{BIT_SIZE}, @gol 14516@ref{LEADZ}, @gol 14517@ref{POPPAR}, @gol 14518@ref{POPCNT} 14519@end table 14520 14521 14522 14523@node TRANSFER 14524@section @code{TRANSFER} --- Transfer bit patterns 14525@fnindex TRANSFER 14526@cindex bits, move 14527@cindex type cast 14528 14529@table @asis 14530@item @emph{Description}: 14531Interprets the bitwise representation of @var{SOURCE} in memory as if it 14532is the representation of a variable or array of the same type and type 14533parameters as @var{MOLD}. 14534 14535This is approximately equivalent to the C concept of @emph{casting} one 14536type to another. 14537 14538@item @emph{Standard}: 14539Fortran 90 and later 14540 14541@item @emph{Class}: 14542Transformational function 14543 14544@item @emph{Syntax}: 14545@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])} 14546 14547@item @emph{Arguments}: 14548@multitable @columnfractions .15 .70 14549@item @var{SOURCE} @tab Shall be a scalar or an array of any type. 14550@item @var{MOLD} @tab Shall be a scalar or an array of any type. 14551@item @var{SIZE} @tab (Optional) shall be a scalar of type 14552@code{INTEGER}. 14553@end multitable 14554 14555@item @emph{Return value}: 14556The result has the same type as @var{MOLD}, with the bit level 14557representation of @var{SOURCE}. If @var{SIZE} is present, the result is 14558a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent 14559but @var{MOLD} is an array (of any size or shape), the result is a one- 14560dimensional array of the minimum length needed to contain the entirety 14561of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent 14562and @var{MOLD} is a scalar, the result is a scalar. 14563 14564If the bitwise representation of the result is longer than that of 14565@var{SOURCE}, then the leading bits of the result correspond to those of 14566@var{SOURCE} and any trailing bits are filled arbitrarily. 14567 14568When the resulting bit representation does not correspond to a valid 14569representation of a variable of the same type as @var{MOLD}, the results 14570are undefined, and subsequent operations on the result cannot be 14571guaranteed to produce sensible behavior. For example, it is possible to 14572create @code{LOGICAL} variables for which @code{@var{VAR}} and 14573@code{.NOT.@var{VAR}} both appear to be true. 14574 14575@item @emph{Example}: 14576@smallexample 14577PROGRAM test_transfer 14578 integer :: x = 2143289344 14579 print *, transfer(x, 1.0) ! prints "NaN" on i686 14580END PROGRAM 14581@end smallexample 14582@end table 14583 14584 14585 14586@node TRANSPOSE 14587@section @code{TRANSPOSE} --- Transpose an array of rank two 14588@fnindex TRANSPOSE 14589@cindex array, transpose 14590@cindex matrix, transpose 14591@cindex transpose 14592 14593@table @asis 14594@item @emph{Description}: 14595Transpose an array of rank two. Element (i, j) of the result has the value 14596@code{MATRIX(j, i)}, for all i, j. 14597 14598@item @emph{Standard}: 14599Fortran 90 and later 14600 14601@item @emph{Class}: 14602Transformational function 14603 14604@item @emph{Syntax}: 14605@code{RESULT = TRANSPOSE(MATRIX)} 14606 14607@item @emph{Arguments}: 14608@multitable @columnfractions .15 .70 14609@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two. 14610@end multitable 14611 14612@item @emph{Return value}: 14613The result has the same type as @var{MATRIX}, and has shape 14614@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}. 14615@end table 14616 14617 14618 14619@node TRIM 14620@section @code{TRIM} --- Remove trailing blank characters of a string 14621@fnindex TRIM 14622@cindex string, remove trailing whitespace 14623 14624@table @asis 14625@item @emph{Description}: 14626Removes trailing blank characters of a string. 14627 14628@item @emph{Standard}: 14629Fortran 90 and later 14630 14631@item @emph{Class}: 14632Transformational function 14633 14634@item @emph{Syntax}: 14635@code{RESULT = TRIM(STRING)} 14636 14637@item @emph{Arguments}: 14638@multitable @columnfractions .15 .70 14639@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}. 14640@end multitable 14641 14642@item @emph{Return value}: 14643A scalar of type @code{CHARACTER} which length is that of @var{STRING} 14644less the number of trailing blanks. 14645 14646@item @emph{Example}: 14647@smallexample 14648PROGRAM test_trim 14649 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " 14650 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks 14651END PROGRAM 14652@end smallexample 14653 14654@item @emph{See also}: 14655@ref{ADJUSTL}, @gol 14656@ref{ADJUSTR} 14657@end table 14658 14659 14660 14661@node TTYNAM 14662@section @code{TTYNAM} --- Get the name of a terminal device. 14663@fnindex TTYNAM 14664@cindex system, terminal 14665 14666@table @asis 14667@item @emph{Description}: 14668Get the name of a terminal device. For more information, 14669see @code{ttyname(3)}. 14670 14671This intrinsic is provided in both subroutine and function forms; 14672however, only one form can be used in any given program unit. 14673 14674@item @emph{Standard}: 14675GNU extension 14676 14677@item @emph{Class}: 14678Subroutine, function 14679 14680@item @emph{Syntax}: 14681@multitable @columnfractions .80 14682@item @code{CALL TTYNAM(UNIT, NAME)} 14683@item @code{NAME = TTYNAM(UNIT)} 14684@end multitable 14685 14686@item @emph{Arguments}: 14687@multitable @columnfractions .15 .70 14688@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 14689@item @var{NAME} @tab Shall be of type @code{CHARACTER}. 14690@end multitable 14691 14692@item @emph{Example}: 14693@smallexample 14694PROGRAM test_ttynam 14695 INTEGER :: unit 14696 DO unit = 1, 10 14697 IF (isatty(unit=unit)) write(*,*) ttynam(unit) 14698 END DO 14699END PROGRAM 14700@end smallexample 14701 14702@item @emph{See also}: 14703@ref{ISATTY} 14704@end table 14705 14706 14707 14708@node UBOUND 14709@section @code{UBOUND} --- Upper dimension bounds of an array 14710@fnindex UBOUND 14711@cindex array, upper bound 14712 14713@table @asis 14714@item @emph{Description}: 14715Returns the upper bounds of an array, or a single upper bound 14716along the @var{DIM} dimension. 14717@item @emph{Standard}: 14718Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 14719 14720@item @emph{Class}: 14721Inquiry function 14722 14723@item @emph{Syntax}: 14724@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])} 14725 14726@item @emph{Arguments}: 14727@multitable @columnfractions .15 .70 14728@item @var{ARRAY} @tab Shall be an array, of any type. 14729@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14730@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization 14731expression indicating the kind parameter of the result. 14732@end multitable 14733 14734@item @emph{Return value}: 14735The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14736@var{KIND} is absent, the return value is of default integer kind. 14737If @var{DIM} is absent, the result is an array of the upper bounds of 14738@var{ARRAY}. If @var{DIM} is present, the result is a scalar 14739corresponding to the upper bound of the array along that dimension. If 14740@var{ARRAY} is an expression rather than a whole array or array 14741structure component, or if it has a zero extent along the relevant 14742dimension, the upper bound is taken to be the number of elements along 14743the relevant dimension. 14744 14745@item @emph{See also}: 14746@ref{LBOUND}, @gol 14747@ref{LCOBOUND} 14748@end table 14749 14750 14751 14752@node UCOBOUND 14753@section @code{UCOBOUND} --- Upper codimension bounds of an array 14754@fnindex UCOBOUND 14755@cindex coarray, upper bound 14756 14757@table @asis 14758@item @emph{Description}: 14759Returns the upper cobounds of a coarray, or a single upper cobound 14760along the @var{DIM} codimension. 14761@item @emph{Standard}: 14762Fortran 2008 and later 14763 14764@item @emph{Class}: 14765Inquiry function 14766 14767@item @emph{Syntax}: 14768@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])} 14769 14770@item @emph{Arguments}: 14771@multitable @columnfractions .15 .70 14772@item @var{ARRAY} @tab Shall be an coarray, of any type. 14773@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14774@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14775expression indicating the kind parameter of the result. 14776@end multitable 14777 14778@item @emph{Return value}: 14779The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14780@var{KIND} is absent, the return value is of default integer kind. 14781If @var{DIM} is absent, the result is an array of the lower cobounds of 14782@var{COARRAY}. If @var{DIM} is present, the result is a scalar 14783corresponding to the lower cobound of the array along that codimension. 14784 14785@item @emph{See also}: 14786@ref{LCOBOUND}, @gol 14787@ref{LBOUND} 14788@end table 14789 14790 14791 14792@node UMASK 14793@section @code{UMASK} --- Set the file creation mask 14794@fnindex UMASK 14795@cindex file system, file creation mask 14796 14797@table @asis 14798@item @emph{Description}: 14799Sets the file creation mask to @var{MASK}. If called as a function, it 14800returns the old value. If called as a subroutine and argument @var{OLD} 14801if it is supplied, it is set to the old value. See @code{umask(2)}. 14802 14803@item @emph{Standard}: 14804GNU extension 14805 14806@item @emph{Class}: 14807Subroutine, function 14808 14809@item @emph{Syntax}: 14810@multitable @columnfractions .80 14811@item @code{CALL UMASK(MASK [, OLD])} 14812@item @code{OLD = UMASK(MASK)} 14813@end multitable 14814 14815@item @emph{Arguments}: 14816@multitable @columnfractions .15 .70 14817@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}. 14818@item @var{OLD} @tab (Optional) Shall be a scalar of type 14819@code{INTEGER}. 14820@end multitable 14821 14822@end table 14823 14824 14825 14826@node UNLINK 14827@section @code{UNLINK} --- Remove a file from the file system 14828@fnindex UNLINK 14829@cindex file system, remove file 14830 14831@table @asis 14832@item @emph{Description}: 14833Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be 14834used to mark the end of the name in @var{PATH}; otherwise, trailing 14835blanks in the file name are ignored. If the @var{STATUS} argument is 14836supplied, it contains 0 on success or a nonzero error code upon return; 14837see @code{unlink(2)}. 14838 14839This intrinsic is provided in both subroutine and function forms; 14840however, only one form can be used in any given program unit. 14841 14842@item @emph{Standard}: 14843GNU extension 14844 14845@item @emph{Class}: 14846Subroutine, function 14847 14848@item @emph{Syntax}: 14849@multitable @columnfractions .80 14850@item @code{CALL UNLINK(PATH [, STATUS])} 14851@item @code{STATUS = UNLINK(PATH)} 14852@end multitable 14853 14854@item @emph{Arguments}: 14855@multitable @columnfractions .15 .70 14856@item @var{PATH} @tab Shall be of default @code{CHARACTER} type. 14857@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 14858@end multitable 14859 14860@item @emph{See also}: 14861@ref{LINK}, @gol 14862@ref{SYMLNK} 14863@end table 14864 14865 14866 14867@node UNPACK 14868@section @code{UNPACK} --- Unpack an array of rank one into an array 14869@fnindex UNPACK 14870@cindex array, unpacking 14871@cindex array, increase dimension 14872@cindex array, scatter elements 14873 14874@table @asis 14875@item @emph{Description}: 14876Store the elements of @var{VECTOR} in an array of higher rank. 14877 14878@item @emph{Standard}: 14879Fortran 90 and later 14880 14881@item @emph{Class}: 14882Transformational function 14883 14884@item @emph{Syntax}: 14885@code{RESULT = UNPACK(VECTOR, MASK, FIELD)} 14886 14887@item @emph{Arguments}: 14888@multitable @columnfractions .15 .70 14889@item @var{VECTOR} @tab Shall be an array of any type and rank one. It 14890shall have at least as many elements as @var{MASK} has @code{TRUE} values. 14891@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}. 14892@item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have 14893the same shape as @var{MASK}. 14894@end multitable 14895 14896@item @emph{Return value}: 14897The resulting array corresponds to @var{FIELD} with @code{TRUE} elements 14898of @var{MASK} replaced by values from @var{VECTOR} in array element order. 14899 14900@item @emph{Example}: 14901@smallexample 14902PROGRAM test_unpack 14903 integer :: vector(2) = (/1,1/) 14904 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /) 14905 integer :: field(2,2) = 0, unity(2,2) 14906 14907 ! result: unity matrix 14908 unity = unpack(vector, reshape(mask, (/2,2/)), field) 14909END PROGRAM 14910@end smallexample 14911 14912@item @emph{See also}: 14913@ref{PACK}, @gol 14914@ref{SPREAD} 14915@end table 14916 14917 14918 14919@node VERIFY 14920@section @code{VERIFY} --- Scan a string for characters not a given set 14921@fnindex VERIFY 14922@cindex string, find missing set 14923 14924@table @asis 14925@item @emph{Description}: 14926Verifies that all the characters in @var{STRING} belong to the set of 14927characters in @var{SET}. 14928 14929If @var{BACK} is either absent or equals @code{FALSE}, this function 14930returns the position of the leftmost character of @var{STRING} that is 14931not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost 14932position is returned. If all characters of @var{STRING} are found in 14933@var{SET}, the result is zero. 14934 14935@item @emph{Standard}: 14936Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later 14937 14938@item @emph{Class}: 14939Elemental function 14940 14941@item @emph{Syntax}: 14942@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])} 14943 14944@item @emph{Arguments}: 14945@multitable @columnfractions .15 .70 14946@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 14947@item @var{SET} @tab Shall be of type @code{CHARACTER}. 14948@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 14949@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14950expression indicating the kind parameter of the result. 14951@end multitable 14952 14953@item @emph{Return value}: 14954The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14955@var{KIND} is absent, the return value is of default integer kind. 14956 14957@item @emph{Example}: 14958@smallexample 14959PROGRAM test_verify 14960 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F' 14961 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R' 14962 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F' 14963 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N' 14964 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none 14965END PROGRAM 14966@end smallexample 14967 14968@item @emph{See also}: 14969@ref{SCAN}, @gol 14970@ref{INDEX intrinsic} 14971@end table 14972 14973 14974 14975@node XOR 14976@section @code{XOR} --- Bitwise logical exclusive OR 14977@fnindex XOR 14978@cindex bitwise logical exclusive or 14979@cindex logical exclusive or, bitwise 14980 14981@table @asis 14982@item @emph{Description}: 14983Bitwise logical exclusive or. 14984 14985This intrinsic routine is provided for backwards compatibility with 14986GNU Fortran 77. For integer arguments, programmers should consider 14987the use of the @ref{IEOR} intrinsic and for logical arguments the 14988@code{.NEQV.} operator, which are both defined by the Fortran standard. 14989 14990@item @emph{Standard}: 14991GNU extension 14992 14993@item @emph{Class}: 14994Function 14995 14996@item @emph{Syntax}: 14997@code{RESULT = XOR(I, J)} 14998 14999@item @emph{Arguments}: 15000@multitable @columnfractions .15 .70 15001@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 15002type or a scalar @code{LOGICAL} type or a boz-literal-constant. 15003@item @var{J} @tab The type shall be the same as the type of @var{I} or 15004a boz-literal-constant. @var{I} and @var{J} shall not both be 15005boz-literal-constants. If either @var{I} and @var{J} is a 15006boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 15007@end multitable 15008 15009@item @emph{Return value}: 15010The return type is either a scalar @code{INTEGER} or a scalar 15011@code{LOGICAL}. If the kind type parameters differ, then the 15012smaller kind type is implicitly converted to larger kind, and the 15013return has the larger kind. A boz-literal-constant is 15014converted to an @code{INTEGER} with the kind type parameter of 15015the other argument as-if a call to @ref{INT} occurred. 15016 15017@item @emph{Example}: 15018@smallexample 15019PROGRAM test_xor 15020 LOGICAL :: T = .TRUE., F = .FALSE. 15021 INTEGER :: a, b 15022 DATA a / Z'F' /, b / Z'3' / 15023 15024 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F) 15025 WRITE (*,*) XOR(a, b) 15026END PROGRAM 15027@end smallexample 15028 15029@item @emph{See also}: 15030Fortran 95 elemental function: @gol 15031@ref{IEOR} 15032@end table 15033 15034 15035 15036@node Intrinsic Modules 15037@chapter Intrinsic Modules 15038@cindex intrinsic Modules 15039 15040@menu 15041* ISO_FORTRAN_ENV:: 15042* ISO_C_BINDING:: 15043* IEEE modules:: 15044* OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: 15045* OpenACC Module OPENACC:: 15046@end menu 15047 15048@node ISO_FORTRAN_ENV 15049@section @code{ISO_FORTRAN_ENV} 15050@table @asis 15051@item @emph{Standard}: 15052Fortran 2003 and later, except when otherwise noted 15053@end table 15054 15055The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer 15056named constants: 15057 15058@table @asis 15059@item @code{ATOMIC_INT_KIND}: 15060Default-kind integer constant to be used as kind parameter when defining 15061integer variables used in atomic operations. (Fortran 2008 or later.) 15062 15063@item @code{ATOMIC_LOGICAL_KIND}: 15064Default-kind integer constant to be used as kind parameter when defining 15065logical variables used in atomic operations. (Fortran 2008 or later.) 15066 15067@item @code{CHARACTER_KINDS}: 15068Default-kind integer constant array of rank one containing the supported kind 15069parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) 15070 15071@item @code{CHARACTER_STORAGE_SIZE}: 15072Size in bits of the character storage unit. 15073 15074@item @code{ERROR_UNIT}: 15075Identifies the preconnected unit used for error reporting. 15076 15077@item @code{FILE_STORAGE_SIZE}: 15078Size in bits of the file-storage unit. 15079 15080@item @code{INPUT_UNIT}: 15081Identifies the preconnected unit identified by the asterisk 15082(@code{*}) in @code{READ} statement. 15083 15084@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}: 15085Kind type parameters to specify an INTEGER type with a storage 15086size of 16, 32, and 64 bits. It is negative if a target platform 15087does not support the particular kind. (Fortran 2008 or later.) 15088 15089@item @code{INTEGER_KINDS}: 15090Default-kind integer constant array of rank one containing the supported kind 15091parameters of the @code{INTEGER} type. (Fortran 2008 or later.) 15092 15093@item @code{IOSTAT_END}: 15094The value assigned to the variable passed to the @code{IOSTAT=} specifier of 15095an input/output statement if an end-of-file condition occurred. 15096 15097@item @code{IOSTAT_EOR}: 15098The value assigned to the variable passed to the @code{IOSTAT=} specifier of 15099an input/output statement if an end-of-record condition occurred. 15100 15101@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}: 15102Scalar default-integer constant, used by @code{INQUIRE} for the 15103@code{IOSTAT=} specifier to denote an that a unit number identifies an 15104internal unit. (Fortran 2008 or later.) 15105 15106@item @code{NUMERIC_STORAGE_SIZE}: 15107The size in bits of the numeric storage unit. 15108 15109@item @code{LOGICAL_KINDS}: 15110Default-kind integer constant array of rank one containing the supported kind 15111parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) 15112 15113@item @code{OUTPUT_UNIT}: 15114Identifies the preconnected unit identified by the asterisk 15115(@code{*}) in @code{WRITE} statement. 15116 15117@item @code{REAL32}, @code{REAL64}, @code{REAL128}: 15118Kind type parameters to specify a REAL type with a storage 15119size of 32, 64, and 128 bits. It is negative if a target platform 15120does not support the particular kind. (Fortran 2008 or later.) 15121 15122@item @code{REAL_KINDS}: 15123Default-kind integer constant array of rank one containing the supported kind 15124parameters of the @code{REAL} type. (Fortran 2008 or later.) 15125 15126@item @code{STAT_LOCKED}: 15127Scalar default-integer constant used as STAT= return value by @code{LOCK} to 15128denote that the lock variable is locked by the executing image. (Fortran 2008 15129or later.) 15130 15131@item @code{STAT_LOCKED_OTHER_IMAGE}: 15132Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 15133denote that the lock variable is locked by another image. (Fortran 2008 or 15134later.) 15135 15136@item @code{STAT_STOPPED_IMAGE}: 15137Positive, scalar default-integer constant used as STAT= return value if the 15138argument in the statement requires synchronisation with an image, which has 15139initiated the termination of the execution. (Fortran 2008 or later.) 15140 15141@item @code{STAT_FAILED_IMAGE}: 15142Positive, scalar default-integer constant used as STAT= return value if the 15143argument in the statement requires communication with an image, which has 15144is in the failed state. (TS 18508 or later.) 15145 15146@item @code{STAT_UNLOCKED}: 15147Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 15148denote that the lock variable is unlocked. (Fortran 2008 or later.) 15149@end table 15150 15151The module provides the following derived type: 15152 15153@table @asis 15154@item @code{LOCK_TYPE}: 15155Derived type with private components to be use with the @code{LOCK} and 15156@code{UNLOCK} statement. A variable of its type has to be always declared 15157as coarray and may not appear in a variable-definition context. 15158(Fortran 2008 or later.) 15159@end table 15160 15161The module also provides the following intrinsic procedures: 15162@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}. 15163 15164 15165 15166@node ISO_C_BINDING 15167@section @code{ISO_C_BINDING} 15168@table @asis 15169@item @emph{Standard}: 15170Fortran 2003 and later, GNU extensions 15171@end table 15172 15173The following intrinsic procedures are provided by the module; their 15174definition can be found in the section Intrinsic Procedures of this 15175manual. 15176 15177@table @asis 15178@item @code{C_ASSOCIATED} 15179@item @code{C_F_POINTER} 15180@item @code{C_F_PROCPOINTER} 15181@item @code{C_FUNLOC} 15182@item @code{C_LOC} 15183@item @code{C_SIZEOF} 15184@end table 15185@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF, 15186@c don't really know why. 15187 15188The @code{ISO_C_BINDING} module provides the following named constants of 15189type default integer, which can be used as KIND type parameters. 15190 15191In addition to the integer named constants required by the Fortran 2003 15192standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an 15193extension named constants for the 128-bit integer types supported by the 15194C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}. 15195Furthermore, if @code{__float128} is supported in C, the named constants 15196@code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined. 15197 15198@multitable @columnfractions .15 .35 .35 .35 15199@item Fortran Type @tab Named constant @tab C type @tab Extension 15200@item @code{INTEGER}@tab @code{C_INT} @tab @code{int} 15201@item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int} 15202@item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int} 15203@item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int} 15204@item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char} 15205@item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t} 15206@item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t} 15207@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t} 15208@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t} 15209@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t} 15210@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext. 15211@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t} 15212@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t} 15213@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t} 15214@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t} 15215@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext. 15216@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t} 15217@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t} 15218@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t} 15219@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t} 15220@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext. 15221@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t} 15222@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t} 15223@item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113 15224@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float} 15225@item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double} 15226@item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double} 15227@item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext. 15228@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex} 15229@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex} 15230@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex} 15231@item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext. 15232@item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool} 15233@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char} 15234@end multitable 15235 15236Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)} 15237are defined. 15238 15239@multitable @columnfractions .20 .45 .15 15240@item Name @tab C definition @tab Value 15241@item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'} 15242@item @code{C_ALERT} @tab alert @tab @code{'\a'} 15243@item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'} 15244@item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'} 15245@item @code{C_NEW_LINE} @tab new line @tab @code{'\n'} 15246@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'} 15247@item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'} 15248@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'} 15249@end multitable 15250 15251Moreover, the following two named constants are defined: 15252 15253@multitable @columnfractions .20 .80 15254@item Name @tab Type 15255@item @code{C_NULL_PTR} @tab @code{C_PTR} 15256@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR} 15257@end multitable 15258 15259Both are equivalent to the value @code{NULL} in C. 15260 15261 15262 15263@node IEEE modules 15264@section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 15265@table @asis 15266@item @emph{Standard}: 15267Fortran 2003 and later 15268@end table 15269 15270The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 15271intrinsic modules provide support for exceptions and IEEE arithmetic, as 15272defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard 15273(@emph{Binary floating-point arithmetic for microprocessor systems}). These 15274modules are only provided on the following supported platforms: 15275 15276@itemize @bullet 15277@item i386 and x86_64 processors 15278@item platforms which use the GNU C Library (glibc) 15279@item platforms with support for SysV/386 routines for floating point 15280interface (including Solaris and BSDs) 15281@item platforms with the AIX OS 15282@end itemize 15283 15284For full compliance with the Fortran standards, code using the 15285@code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled 15286with the following options: @code{-fno-unsafe-math-optimizations 15287-frounding-math -fsignaling-nans}. 15288 15289 15290 15291@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS 15292@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS} 15293@table @asis 15294@item @emph{Standard}: 15295OpenMP Application Program Interface v4.5 15296@end table 15297 15298 15299The OpenMP Fortran runtime library routines are provided both in 15300a form of two Fortran 90 modules, named @code{OMP_LIB} and 15301@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named 15302@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found 15303in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi 15304Processing Runtime Library} manual, 15305the named constants defined in the modules are listed 15306below. 15307 15308For details refer to the actual 15309@uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf, 15310OpenMP Application Program Interface v4.5}. 15311And for the @code{pause}-related constants to the OpenMP 5.0 specification. 15312 15313@code{OMP_LIB_KINDS} provides the following scalar default-integer 15314named constants: 15315 15316@table @asis 15317@item @code{omp_lock_kind} 15318@item @code{omp_lock_hint_kind} 15319@item @code{omp_nest_lock_kind} 15320@item @code{omp_pause_resource_kind} 15321@item @code{omp_proc_bind_kind} 15322@item @code{omp_sched_kind} 15323@end table 15324 15325@code{OMP_LIB} provides the scalar default-integer 15326named constant @code{openmp_version} with a value of the form 15327@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 15328of the OpenMP version; for OpenMP v4.5 the value is @code{201511}. 15329 15330The following scalar integer named constants of the 15331kind @code{omp_sched_kind}: 15332 15333@table @asis 15334@item @code{omp_sched_static} 15335@item @code{omp_sched_dynamic} 15336@item @code{omp_sched_guided} 15337@item @code{omp_sched_auto} 15338@end table 15339 15340And the following scalar integer named constants of the 15341kind @code{omp_proc_bind_kind}: 15342 15343@table @asis 15344@item @code{omp_proc_bind_false} 15345@item @code{omp_proc_bind_true} 15346@item @code{omp_proc_bind_master} 15347@item @code{omp_proc_bind_close} 15348@item @code{omp_proc_bind_spread} 15349@end table 15350 15351The following scalar integer named constants are of the 15352kind @code{omp_lock_hint_kind}: 15353 15354@table @asis 15355@item @code{omp_lock_hint_none} 15356@item @code{omp_lock_hint_uncontended} 15357@item @code{omp_lock_hint_contended} 15358@item @code{omp_lock_hint_nonspeculative} 15359@item @code{omp_lock_hint_speculative} 15360@end table 15361 15362And the following two scalar integer named constants are of the 15363kind @code{omp_pause_resource_kind}: 15364 15365@table @asis 15366@item @code{omp_pause_soft} 15367@item @code{omp_pause_hard} 15368@end table 15369 15370 15371@node OpenACC Module OPENACC 15372@section OpenACC Module @code{OPENACC} 15373@table @asis 15374@item @emph{Standard}: 15375OpenACC Application Programming Interface v2.6 15376@end table 15377 15378 15379The OpenACC Fortran runtime library routines are provided both in a 15380form of a Fortran 90 module, named @code{OPENACC}, and in form of a 15381Fortran @code{include} file named @file{openacc_lib.h}. The 15382procedures provided by @code{OPENACC} can be found in the 15383@ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing 15384Runtime Library} manual, the named constants defined in the modules 15385are listed below. 15386 15387For details refer to the actual 15388@uref{http://www.openacc.org/, 15389OpenACC Application Programming Interface v2.6}. 15390 15391@code{OPENACC} provides the scalar default-integer 15392named constant @code{openacc_version} with a value of the form 15393@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 15394of the OpenACC version; for OpenACC v2.6 the value is @code{201711}. 15395