1@ignore 2Copyright (C) 2005-2019 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}, @ref{KILL}, @ref{BACKTRACE} 407 408@end table 409 410 411 412@node ABS 413@section @code{ABS} --- Absolute value 414@fnindex ABS 415@fnindex CABS 416@fnindex DABS 417@fnindex IABS 418@fnindex ZABS 419@fnindex CDABS 420@fnindex BABS 421@fnindex IIABS 422@fnindex JIABS 423@fnindex KIABS 424@cindex absolute value 425 426@table @asis 427@item @emph{Description}: 428@code{ABS(A)} computes the absolute value of @code{A}. 429 430@item @emph{Standard}: 431Fortran 77 and later, has overloads that are GNU extensions 432 433@item @emph{Class}: 434Elemental function 435 436@item @emph{Syntax}: 437@code{RESULT = ABS(A)} 438 439@item @emph{Arguments}: 440@multitable @columnfractions .15 .70 441@item @var{A} @tab The type of the argument shall be an @code{INTEGER}, 442@code{REAL}, or @code{COMPLEX}. 443@end multitable 444 445@item @emph{Return value}: 446The return value is of the same type and 447kind as the argument except the return value is @code{REAL} for a 448@code{COMPLEX} argument. 449 450@item @emph{Example}: 451@smallexample 452program test_abs 453 integer :: i = -1 454 real :: x = -1.e0 455 complex :: z = (-1.e0,0.e0) 456 i = abs(i) 457 x = abs(x) 458 x = abs(z) 459end program test_abs 460@end smallexample 461 462@item @emph{Specific names}: 463@multitable @columnfractions .20 .20 .20 .25 464@item Name @tab Argument @tab Return type @tab Standard 465@item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 466@item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 467@item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 468@item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later 469@item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 470@item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 471@item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 472@item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 473@item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension 474@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension 475@end multitable 476@end table 477 478 479 480@node ACCESS 481@section @code{ACCESS} --- Checks file access modes 482@fnindex ACCESS 483@cindex file system, access mode 484 485@table @asis 486@item @emph{Description}: 487@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 488exists, is readable, writable or executable. Except for the 489executable check, @code{ACCESS} can be replaced by 490Fortran 95's @code{INQUIRE}. 491 492@item @emph{Standard}: 493GNU extension 494 495@item @emph{Class}: 496Inquiry function 497 498@item @emph{Syntax}: 499@code{RESULT = ACCESS(NAME, MODE)} 500 501@item @emph{Arguments}: 502@multitable @columnfractions .15 .70 503@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 504file name. Tailing blank are ignored unless the character @code{achar(0)} 505is present, then all characters up to and excluding @code{achar(0)} are 506used as file name. 507@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the 508file access mode, may be any concatenation of @code{"r"} (readable), 509@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check 510for existence. 511@end multitable 512 513@item @emph{Return value}: 514Returns a scalar @code{INTEGER}, which is @code{0} if the file is 515accessible in the given mode; otherwise or if an invalid argument 516has been given for @code{MODE} the value @code{1} is returned. 517 518@item @emph{Example}: 519@smallexample 520program access_test 521 implicit none 522 character(len=*), parameter :: file = 'test.dat' 523 character(len=*), parameter :: file2 = 'test.dat '//achar(0) 524 if(access(file,' ') == 0) print *, trim(file),' is exists' 525 if(access(file,'r') == 0) print *, trim(file),' is readable' 526 if(access(file,'w') == 0) print *, trim(file),' is writable' 527 if(access(file,'x') == 0) print *, trim(file),' is executable' 528 if(access(file2,'rwx') == 0) & 529 print *, trim(file2),' is readable, writable and executable' 530end program access_test 531@end smallexample 532@item @emph{Specific names}: 533@item @emph{See also}: 534 535@end table 536 537 538 539@node ACHAR 540@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 541@fnindex ACHAR 542@cindex @acronym{ASCII} collating sequence 543@cindex collating sequence, @acronym{ASCII} 544 545@table @asis 546@item @emph{Description}: 547@code{ACHAR(I)} returns the character located at position @code{I} 548in the @acronym{ASCII} collating sequence. 549 550@item @emph{Standard}: 551Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 552 553@item @emph{Class}: 554Elemental function 555 556@item @emph{Syntax}: 557@code{RESULT = ACHAR(I [, KIND])} 558 559@item @emph{Arguments}: 560@multitable @columnfractions .15 .70 561@item @var{I} @tab The type shall be @code{INTEGER}. 562@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 563expression indicating the kind parameter of the result. 564@end multitable 565 566@item @emph{Return value}: 567The return value is of type @code{CHARACTER} with a length of one. 568If the @var{KIND} argument is present, the return value is of the 569specified kind and of the default kind otherwise. 570 571@item @emph{Example}: 572@smallexample 573program test_achar 574 character c 575 c = achar(32) 576end program test_achar 577@end smallexample 578 579@item @emph{Note}: 580See @ref{ICHAR} for a discussion of converting between numerical values 581and formatted string representations. 582 583@item @emph{See also}: 584@ref{CHAR}, @ref{IACHAR}, @ref{ICHAR} 585 586@end table 587 588 589 590@node ACOS 591@section @code{ACOS} --- Arccosine function 592@fnindex ACOS 593@fnindex DACOS 594@cindex trigonometric function, cosine, inverse 595@cindex cosine, inverse 596 597@table @asis 598@item @emph{Description}: 599@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}). 600 601@item @emph{Standard}: 602Fortran 77 and later, for a complex argument Fortran 2008 or later 603 604@item @emph{Class}: 605Elemental function 606 607@item @emph{Syntax}: 608@code{RESULT = ACOS(X)} 609 610@item @emph{Arguments}: 611@multitable @columnfractions .15 .70 612@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 613less than or equal to one - or the type shall be @code{COMPLEX}. 614@end multitable 615 616@item @emph{Return value}: 617The return value is of the same type and kind as @var{X}. 618The real part of the result is in radians and lies in the range 619@math{0 \leq \Re \acos(x) \leq \pi}. 620 621@item @emph{Example}: 622@smallexample 623program test_acos 624 real(8) :: x = 0.866_8 625 x = acos(x) 626end program test_acos 627@end smallexample 628 629@item @emph{Specific names}: 630@multitable @columnfractions .20 .20 .20 .25 631@item Name @tab Argument @tab Return type @tab Standard 632@item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 633@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 634@end multitable 635 636@item @emph{See also}: 637Inverse function: @ref{COS} 638Degrees function: @ref{ACOSD} 639 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: @ref{COSD} 696Radians function: @ref{ACOS} 697 698@end table 699 700 701 702@node ACOSH 703@section @code{ACOSH} --- Inverse hyperbolic cosine function 704@fnindex ACOSH 705@fnindex DACOSH 706@cindex area hyperbolic cosine 707@cindex inverse hyperbolic cosine 708@cindex hyperbolic function, cosine, inverse 709@cindex cosine, hyperbolic, inverse 710 711@table @asis 712@item @emph{Description}: 713@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}. 714 715@item @emph{Standard}: 716Fortran 2008 and later 717 718@item @emph{Class}: 719Elemental function 720 721@item @emph{Syntax}: 722@code{RESULT = ACOSH(X)} 723 724@item @emph{Arguments}: 725@multitable @columnfractions .15 .70 726@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 727@end multitable 728 729@item @emph{Return value}: 730The return value has the same type and kind as @var{X}. If @var{X} is 731complex, the imaginary part of the result is in radians and lies between 732@math{ 0 \leq \Im \acosh(x) \leq \pi}. 733 734@item @emph{Example}: 735@smallexample 736PROGRAM test_acosh 737 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) 738 WRITE (*,*) ACOSH(x) 739END PROGRAM 740@end smallexample 741 742@item @emph{Specific names}: 743@multitable @columnfractions .20 .20 .20 .25 744@item Name @tab Argument @tab Return type @tab Standard 745@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 746@end multitable 747 748@item @emph{See also}: 749Inverse function: @ref{COSH} 750@end table 751 752 753 754@node ADJUSTL 755@section @code{ADJUSTL} --- Left adjust a string 756@fnindex ADJUSTL 757@cindex string, adjust left 758@cindex adjust string 759 760@table @asis 761@item @emph{Description}: 762@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces. 763Spaces are inserted at the end of the string as needed. 764 765@item @emph{Standard}: 766Fortran 90 and later 767 768@item @emph{Class}: 769Elemental function 770 771@item @emph{Syntax}: 772@code{RESULT = ADJUSTL(STRING)} 773 774@item @emph{Arguments}: 775@multitable @columnfractions .15 .70 776@item @var{STRING} @tab The type shall be @code{CHARACTER}. 777@end multitable 778 779@item @emph{Return value}: 780The return value is of type @code{CHARACTER} and of the same kind as 781@var{STRING} where leading spaces are removed and the same number of 782spaces are inserted on the end of @var{STRING}. 783 784@item @emph{Example}: 785@smallexample 786program test_adjustl 787 character(len=20) :: str = ' gfortran' 788 str = adjustl(str) 789 print *, str 790end program test_adjustl 791@end smallexample 792 793@item @emph{See also}: 794@ref{ADJUSTR}, @ref{TRIM} 795@end table 796 797 798 799@node ADJUSTR 800@section @code{ADJUSTR} --- Right adjust a string 801@fnindex ADJUSTR 802@cindex string, adjust right 803@cindex adjust string 804 805@table @asis 806@item @emph{Description}: 807@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces. 808Spaces are inserted at the start of the string as needed. 809 810@item @emph{Standard}: 811Fortran 95 and later 812 813@item @emph{Class}: 814Elemental function 815 816@item @emph{Syntax}: 817@code{RESULT = ADJUSTR(STRING)} 818 819@item @emph{Arguments}: 820@multitable @columnfractions .15 .70 821@item @var{STR} @tab The type shall be @code{CHARACTER}. 822@end multitable 823 824@item @emph{Return value}: 825The return value is of type @code{CHARACTER} and of the same kind as 826@var{STRING} where trailing spaces are removed and the same number of 827spaces are inserted at the start of @var{STRING}. 828 829@item @emph{Example}: 830@smallexample 831program test_adjustr 832 character(len=20) :: str = 'gfortran' 833 str = adjustr(str) 834 print *, str 835end program test_adjustr 836@end smallexample 837 838@item @emph{See also}: 839@ref{ADJUSTL}, @ref{TRIM} 840@end table 841 842 843 844@node AIMAG 845@section @code{AIMAG} --- Imaginary part of complex number 846@fnindex AIMAG 847@fnindex DIMAG 848@fnindex IMAG 849@fnindex IMAGPART 850@cindex complex numbers, imaginary part 851 852@table @asis 853@item @emph{Description}: 854@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}. 855The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided 856for compatibility with @command{g77}, and their use in new code is 857strongly discouraged. 858 859@item @emph{Standard}: 860Fortran 77 and later, has overloads that are GNU extensions 861 862@item @emph{Class}: 863Elemental function 864 865@item @emph{Syntax}: 866@code{RESULT = AIMAG(Z)} 867 868@item @emph{Arguments}: 869@multitable @columnfractions .15 .70 870@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}. 871@end multitable 872 873@item @emph{Return value}: 874The return value is of type @code{REAL} with the 875kind type parameter of the argument. 876 877@item @emph{Example}: 878@smallexample 879program test_aimag 880 complex(4) z4 881 complex(8) z8 882 z4 = cmplx(1.e0_4, 0.e0_4) 883 z8 = cmplx(0.e0_8, 1.e0_8) 884 print *, aimag(z4), dimag(z8) 885end program test_aimag 886@end smallexample 887 888@item @emph{Specific names}: 889@multitable @columnfractions .20 .20 .20 .25 890@item Name @tab Argument @tab Return type @tab Standard 891@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 892@item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension 893@item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 894@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 895@end multitable 896@end table 897 898 899 900@node AINT 901@section @code{AINT} --- Truncate to a whole number 902@fnindex AINT 903@fnindex DINT 904@cindex floor 905@cindex rounding, floor 906 907@table @asis 908@item @emph{Description}: 909@code{AINT(A [, KIND])} truncates its argument to a whole number. 910 911@item @emph{Standard}: 912Fortran 77 and later 913 914@item @emph{Class}: 915Elemental function 916 917@item @emph{Syntax}: 918@code{RESULT = AINT(A [, KIND])} 919 920@item @emph{Arguments}: 921@multitable @columnfractions .15 .70 922@item @var{A} @tab The type of the argument shall be @code{REAL}. 923@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 924expression indicating the kind parameter of the result. 925@end multitable 926 927@item @emph{Return value}: 928The return value is of type @code{REAL} with the kind type parameter of the 929argument if the optional @var{KIND} is absent; otherwise, the kind 930type parameter will be given by @var{KIND}. If the magnitude of 931@var{X} is less than one, @code{AINT(X)} returns zero. If the 932magnitude is equal to or greater than one then it returns the largest 933whole number that does not exceed its magnitude. The sign is the same 934as the sign of @var{X}. 935 936@item @emph{Example}: 937@smallexample 938program test_aint 939 real(4) x4 940 real(8) x8 941 x4 = 1.234E0_4 942 x8 = 4.321_8 943 print *, aint(x4), dint(x8) 944 x8 = aint(x4,8) 945end program test_aint 946@end smallexample 947 948@item @emph{Specific names}: 949@multitable @columnfractions .20 .20 .20 .25 950@item Name @tab Argument @tab Return type @tab Standard 951@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 952@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 953@end multitable 954@end table 955 956 957 958@node ALARM 959@section @code{ALARM} --- Execute a routine after a given delay 960@fnindex ALARM 961@cindex delayed execution 962 963@table @asis 964@item @emph{Description}: 965@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} 966to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to 967set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is 968supplied, it will be returned with the number of seconds remaining until 969any previously scheduled alarm was due to be delivered, or zero if there 970was no previously scheduled alarm. 971 972@item @emph{Standard}: 973GNU extension 974 975@item @emph{Class}: 976Subroutine 977 978@item @emph{Syntax}: 979@code{CALL ALARM(SECONDS, HANDLER [, STATUS])} 980 981@item @emph{Arguments}: 982@multitable @columnfractions .15 .70 983@item @var{SECONDS} @tab The type of the argument shall be a scalar 984@code{INTEGER}. It is @code{INTENT(IN)}. 985@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or 986@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 987values may be either @code{SIG_IGN=1} to ignore the alarm generated 988or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}. 989@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 990variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}. 991@end multitable 992 993@item @emph{Example}: 994@smallexample 995program test_alarm 996 external handler_print 997 integer i 998 call alarm (3, handler_print, i) 999 print *, i 1000 call sleep(10) 1001end program test_alarm 1002@end smallexample 1003This will cause the external routine @var{handler_print} to be called 1004after 3 seconds. 1005@end table 1006 1007 1008 1009@node ALL 1010@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 1011@fnindex ALL 1012@cindex array, apply condition 1013@cindex array, condition testing 1014 1015@table @asis 1016@item @emph{Description}: 1017@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK} 1018in the array along dimension @var{DIM}. 1019 1020@item @emph{Standard}: 1021Fortran 95 and later 1022 1023@item @emph{Class}: 1024Transformational function 1025 1026@item @emph{Syntax}: 1027@code{RESULT = ALL(MASK [, DIM])} 1028 1029@item @emph{Arguments}: 1030@multitable @columnfractions .15 .70 1031@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1032it shall not be scalar. 1033@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1034with a value that lies between one and the rank of @var{MASK}. 1035@end multitable 1036 1037@item @emph{Return value}: 1038@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where 1039the kind type parameter is the same as the kind type parameter of 1040@var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns 1041an array with the rank of @var{MASK} minus 1. The shape is determined from 1042the shape of @var{MASK} where the @var{DIM} dimension is elided. 1043 1044@table @asis 1045@item (A) 1046@code{ALL(MASK)} is true if all elements of @var{MASK} are true. 1047It also is true if @var{MASK} has zero size; otherwise, it is false. 1048@item (B) 1049If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent 1050to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)} 1051is determined by applying @code{ALL} to the array sections. 1052@end table 1053 1054@item @emph{Example}: 1055@smallexample 1056program test_all 1057 logical l 1058 l = all((/.true., .true., .true./)) 1059 print *, l 1060 call section 1061 contains 1062 subroutine section 1063 integer a(2,3), b(2,3) 1064 a = 1 1065 b = 1 1066 b(2,2) = 2 1067 print *, all(a .eq. b, 1) 1068 print *, all(a .eq. b, 2) 1069 end subroutine section 1070end program test_all 1071@end smallexample 1072@end table 1073 1074 1075 1076@node ALLOCATED 1077@section @code{ALLOCATED} --- Status of an allocatable entity 1078@fnindex ALLOCATED 1079@cindex allocation, status 1080 1081@table @asis 1082@item @emph{Description}: 1083@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation 1084status of @var{ARRAY} and @var{SCALAR}, respectively. 1085 1086@item @emph{Standard}: 1087Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable 1088scalar entities are available in Fortran 2003 and later. 1089 1090@item @emph{Class}: 1091Inquiry function 1092 1093@item @emph{Syntax}: 1094@multitable @columnfractions .80 1095@item @code{RESULT = ALLOCATED(ARRAY)} 1096@item @code{RESULT = ALLOCATED(SCALAR)} 1097@end multitable 1098 1099@item @emph{Arguments}: 1100@multitable @columnfractions .15 .70 1101@item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array. 1102@item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar. 1103@end multitable 1104 1105@item @emph{Return value}: 1106The return value is a scalar @code{LOGICAL} with the default logical 1107kind type parameter. If the argument is allocated, then the result is 1108@code{.TRUE.}; otherwise, it returns @code{.FALSE.} 1109 1110@item @emph{Example}: 1111@smallexample 1112program test_allocated 1113 integer :: i = 4 1114 real(4), allocatable :: x(:) 1115 if (.not. allocated(x)) allocate(x(i)) 1116end program test_allocated 1117@end smallexample 1118@end table 1119 1120 1121 1122@node AND 1123@section @code{AND} --- Bitwise logical AND 1124@fnindex AND 1125@cindex bitwise logical and 1126@cindex logical and, bitwise 1127 1128@table @asis 1129@item @emph{Description}: 1130Bitwise logical @code{AND}. 1131 1132This intrinsic routine is provided for backwards compatibility with 1133GNU Fortran 77. For integer arguments, programmers should consider 1134the use of the @ref{IAND} intrinsic defined by the Fortran standard. 1135 1136@item @emph{Standard}: 1137GNU extension 1138 1139@item @emph{Class}: 1140Function 1141 1142@item @emph{Syntax}: 1143@code{RESULT = AND(I, J)} 1144 1145@item @emph{Arguments}: 1146@multitable @columnfractions .15 .70 1147@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 1148type or a scalar @code{LOGICAL} type or a boz-literal-constant. 1149@item @var{J} @tab The type shall be the same as the type of @var{I} or 1150a boz-literal-constant. @var{I} and @var{J} shall not both be 1151boz-literal-constants. If either @var{I} or @var{J} is a 1152boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 1153@end multitable 1154 1155@item @emph{Return value}: 1156The return type is either a scalar @code{INTEGER} or a scalar 1157@code{LOGICAL}. If the kind type parameters differ, then the 1158smaller kind type is implicitly converted to larger kind, and the 1159return has the larger kind. A boz-literal-constant is 1160converted to an @code{INTEGER} with the kind type parameter of 1161the other argument as-if a call to @ref{INT} occurred. 1162 1163@item @emph{Example}: 1164@smallexample 1165PROGRAM test_and 1166 LOGICAL :: T = .TRUE., F = .FALSE. 1167 INTEGER :: a, b 1168 DATA a / Z'F' /, b / Z'3' / 1169 1170 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F) 1171 WRITE (*,*) AND(a, b) 1172END PROGRAM 1173@end smallexample 1174 1175@item @emph{See also}: 1176Fortran 95 elemental function: @ref{IAND} 1177@end table 1178 1179 1180 1181@node ANINT 1182@section @code{ANINT} --- Nearest whole number 1183@fnindex ANINT 1184@fnindex DNINT 1185@cindex ceiling 1186@cindex rounding, ceiling 1187 1188@table @asis 1189@item @emph{Description}: 1190@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number. 1191 1192@item @emph{Standard}: 1193Fortran 77 and later 1194 1195@item @emph{Class}: 1196Elemental function 1197 1198@item @emph{Syntax}: 1199@code{RESULT = ANINT(A [, KIND])} 1200 1201@item @emph{Arguments}: 1202@multitable @columnfractions .15 .70 1203@item @var{A} @tab The type of the argument shall be @code{REAL}. 1204@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 1205expression indicating the kind parameter of the result. 1206@end multitable 1207 1208@item @emph{Return value}: 1209The return value is of type real with the kind type parameter of the 1210argument if the optional @var{KIND} is absent; otherwise, the kind 1211type parameter will be given by @var{KIND}. If @var{A} is greater than 1212zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is 1213less than or equal to zero then it returns @code{AINT(X-0.5)}. 1214 1215@item @emph{Example}: 1216@smallexample 1217program test_anint 1218 real(4) x4 1219 real(8) x8 1220 x4 = 1.234E0_4 1221 x8 = 4.321_8 1222 print *, anint(x4), dnint(x8) 1223 x8 = anint(x4,8) 1224end program test_anint 1225@end smallexample 1226 1227@item @emph{Specific names}: 1228@multitable @columnfractions .20 .20 .20 .25 1229@item Name @tab Argument @tab Return type @tab Standard 1230@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 1231@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 1232@end multitable 1233@end table 1234 1235 1236 1237@node ANY 1238@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 1239@fnindex ANY 1240@cindex array, apply condition 1241@cindex array, condition testing 1242 1243@table @asis 1244@item @emph{Description}: 1245@code{ANY(MASK [, DIM])} determines if any of the values in the logical array 1246@var{MASK} along dimension @var{DIM} are @code{.TRUE.}. 1247 1248@item @emph{Standard}: 1249Fortran 95 and later 1250 1251@item @emph{Class}: 1252Transformational function 1253 1254@item @emph{Syntax}: 1255@code{RESULT = ANY(MASK [, DIM])} 1256 1257@item @emph{Arguments}: 1258@multitable @columnfractions .15 .70 1259@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1260it shall not be scalar. 1261@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1262with a value that lies between one and the rank of @var{MASK}. 1263@end multitable 1264 1265@item @emph{Return value}: 1266@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where 1267the kind type parameter is the same as the kind type parameter of 1268@var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns 1269an array with the rank of @var{MASK} minus 1. The shape is determined from 1270the shape of @var{MASK} where the @var{DIM} dimension is elided. 1271 1272@table @asis 1273@item (A) 1274@code{ANY(MASK)} is true if any element of @var{MASK} is true; 1275otherwise, it is false. It also is false if @var{MASK} has zero size. 1276@item (B) 1277If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent 1278to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)} 1279is determined by applying @code{ANY} to the array sections. 1280@end table 1281 1282@item @emph{Example}: 1283@smallexample 1284program test_any 1285 logical l 1286 l = any((/.true., .true., .true./)) 1287 print *, l 1288 call section 1289 contains 1290 subroutine section 1291 integer a(2,3), b(2,3) 1292 a = 1 1293 b = 1 1294 b(2,2) = 2 1295 print *, any(a .eq. b, 1) 1296 print *, any(a .eq. b, 2) 1297 end subroutine section 1298end program test_any 1299@end smallexample 1300@end table 1301 1302 1303 1304@node ASIN 1305@section @code{ASIN} --- Arcsine function 1306@fnindex ASIN 1307@fnindex DASIN 1308@cindex trigonometric function, sine, inverse 1309@cindex sine, inverse 1310 1311@table @asis 1312@item @emph{Description}: 1313@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}). 1314 1315@item @emph{Standard}: 1316Fortran 77 and later, for a complex argument Fortran 2008 or later 1317 1318@item @emph{Class}: 1319Elemental function 1320 1321@item @emph{Syntax}: 1322@code{RESULT = ASIN(X)} 1323 1324@item @emph{Arguments}: 1325@multitable @columnfractions .15 .70 1326@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1327less than or equal to one - or be @code{COMPLEX}. 1328@end multitable 1329 1330@item @emph{Return value}: 1331The return value is of the same type and kind as @var{X}. 1332The real part of the result is in radians and lies in the range 1333@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}. 1334 1335@item @emph{Example}: 1336@smallexample 1337program test_asin 1338 real(8) :: x = 0.866_8 1339 x = asin(x) 1340end program test_asin 1341@end smallexample 1342 1343@item @emph{Specific names}: 1344@multitable @columnfractions .20 .20 .20 .25 1345@item Name @tab Argument @tab Return type @tab Standard 1346@item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1347@item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1348@end multitable 1349 1350@item @emph{See also}: 1351Inverse function: @ref{SIN} 1352Degrees function: @ref{ASIND} 1353 1354@end table 1355 1356 1357 1358@node ASIND 1359@section @code{ASIND} --- Arcsine function, degrees 1360@fnindex ASIND 1361@fnindex DASIND 1362@cindex trigonometric function, sine, inverse, degrees 1363@cindex sine, inverse, degrees 1364 1365@table @asis 1366@item @emph{Description}: 1367@code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of 1368@code{SIND(X)}). 1369 1370This function is for compatibility only and should be avoided in favor of 1371standard constructs wherever possible. 1372 1373@item @emph{Standard}: 1374GNU Extension, enabled with @option{-fdec-math}. 1375 1376@item @emph{Class}: 1377Elemental function 1378 1379@item @emph{Syntax}: 1380@code{RESULT = ASIND(X)} 1381 1382@item @emph{Arguments}: 1383@multitable @columnfractions .15 .70 1384@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1385less than or equal to one - or be @code{COMPLEX}. 1386@end multitable 1387 1388@item @emph{Return value}: 1389The return value is of the same type and kind as @var{X}. 1390The real part of the result is in degrees and lies in the range 1391@math{-90 \leq \Re \asin(x) \leq 90}. 1392 1393@item @emph{Example}: 1394@smallexample 1395program test_asind 1396 real(8) :: x = 0.866_8 1397 x = asind(x) 1398end program test_asind 1399@end smallexample 1400 1401@item @emph{Specific names}: 1402@multitable @columnfractions .20 .20 .20 .25 1403@item Name @tab Argument @tab Return type @tab Standard 1404@item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 1405@item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 1406@end multitable 1407 1408@item @emph{See also}: 1409Inverse function: @ref{SIND} 1410Radians function: @ref{ASIN} 1411 1412@end table 1413 1414 1415 1416@node ASINH 1417@section @code{ASINH} --- Inverse hyperbolic sine function 1418@fnindex ASINH 1419@fnindex DASINH 1420@cindex area hyperbolic sine 1421@cindex inverse hyperbolic sine 1422@cindex hyperbolic function, sine, inverse 1423@cindex sine, hyperbolic, inverse 1424 1425@table @asis 1426@item @emph{Description}: 1427@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}. 1428 1429@item @emph{Standard}: 1430Fortran 2008 and later 1431 1432@item @emph{Class}: 1433Elemental function 1434 1435@item @emph{Syntax}: 1436@code{RESULT = ASINH(X)} 1437 1438@item @emph{Arguments}: 1439@multitable @columnfractions .15 .70 1440@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1441@end multitable 1442 1443@item @emph{Return value}: 1444The return value is of the same type and kind as @var{X}. If @var{X} is 1445complex, the imaginary part of the result is in radians and lies between 1446@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}. 1447 1448@item @emph{Example}: 1449@smallexample 1450PROGRAM test_asinh 1451 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1452 WRITE (*,*) ASINH(x) 1453END PROGRAM 1454@end smallexample 1455 1456@item @emph{Specific names}: 1457@multitable @columnfractions .20 .20 .20 .25 1458@item Name @tab Argument @tab Return type @tab Standard 1459@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension. 1460@end multitable 1461 1462@item @emph{See also}: 1463Inverse function: @ref{SINH} 1464@end table 1465 1466 1467 1468@node ASSOCIATED 1469@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 1470@fnindex ASSOCIATED 1471@cindex pointer, status 1472@cindex association status 1473 1474@table @asis 1475@item @emph{Description}: 1476@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer 1477@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}. 1478 1479@item @emph{Standard}: 1480Fortran 95 and later 1481 1482@item @emph{Class}: 1483Inquiry function 1484 1485@item @emph{Syntax}: 1486@code{RESULT = ASSOCIATED(POINTER [, TARGET])} 1487 1488@item @emph{Arguments}: 1489@multitable @columnfractions .15 .70 1490@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute 1491and it can be of any type. 1492@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or 1493a target. It must have the same type, kind type parameter, and 1494array rank as @var{POINTER}. 1495@end multitable 1496The association status of neither @var{POINTER} nor @var{TARGET} shall be 1497undefined. 1498 1499@item @emph{Return value}: 1500@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}. 1501There are several cases: 1502@table @asis 1503@item (A) When the optional @var{TARGET} is not present then 1504@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false. 1505@item (B) If @var{TARGET} is present and a scalar target, the result is true if 1506@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 1507disassociated, the result is false. 1508@item (C) If @var{TARGET} is present and an array target, the result is true if 1509@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays, 1510are arrays whose elements are not zero-sized storage sequences, and 1511@var{TARGET} and @var{POINTER} occupy the same storage units in array element 1512order. 1513As in case(B), the result is false, if @var{POINTER} is disassociated. 1514@item (D) If @var{TARGET} is present and an scalar pointer, the result is true 1515if @var{TARGET} is associated with @var{POINTER}, the target associated with 1516@var{TARGET} are not zero-sized storage sequences and occupy the same storage 1517units. 1518The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1519@item (E) If @var{TARGET} is present and an array pointer, the result is true if 1520target associated with @var{POINTER} and the target associated with @var{TARGET} 1521have the same shape, are not zero-sized arrays, are arrays whose elements are 1522not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy 1523the same storage units in array element order. 1524The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1525@end table 1526 1527@item @emph{Example}: 1528@smallexample 1529program test_associated 1530 implicit none 1531 real, target :: tgt(2) = (/1., 2./) 1532 real, pointer :: ptr(:) 1533 ptr => tgt 1534 if (associated(ptr) .eqv. .false.) call abort 1535 if (associated(ptr,tgt) .eqv. .false.) call abort 1536end program test_associated 1537@end smallexample 1538 1539@item @emph{See also}: 1540@ref{NULL} 1541@end table 1542 1543 1544 1545@node ATAN 1546@section @code{ATAN} --- Arctangent function 1547@fnindex ATAN 1548@fnindex DATAN 1549@cindex trigonometric function, tangent, inverse 1550@cindex tangent, inverse 1551 1552@table @asis 1553@item @emph{Description}: 1554@code{ATAN(X)} computes the arctangent of @var{X}. 1555 1556@item @emph{Standard}: 1557Fortran 77 and later, for a complex argument and for two arguments 1558Fortran 2008 or later 1559 1560@item @emph{Class}: 1561Elemental function 1562 1563@item @emph{Syntax}: 1564@multitable @columnfractions .80 1565@item @code{RESULT = ATAN(X)} 1566@item @code{RESULT = ATAN(Y, X)} 1567@end multitable 1568 1569@item @emph{Arguments}: 1570@multitable @columnfractions .15 .70 1571@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1572if @var{Y} is present, @var{X} shall be REAL. 1573@item @var{Y} shall be of the same type and kind as @var{X}. 1574@end multitable 1575 1576@item @emph{Return value}: 1577The return value is of the same type and kind as @var{X}. 1578If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}. 1579Otherwise, it the arcus tangent of @var{X}, where the real part of 1580the result is in radians and lies in the range 1581@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}. 1582 1583@item @emph{Example}: 1584@smallexample 1585program test_atan 1586 real(8) :: x = 2.866_8 1587 x = atan(x) 1588end program test_atan 1589@end smallexample 1590 1591@item @emph{Specific names}: 1592@multitable @columnfractions .20 .20 .20 .25 1593@item Name @tab Argument @tab Return type @tab Standard 1594@item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1595@item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1596@end multitable 1597 1598@item @emph{See also}: 1599Inverse function: @ref{TAN} 1600Degrees function: @ref{ATAND} 1601 1602@end table 1603 1604 1605 1606@node ATAND 1607@section @code{ATAND} --- Arctangent function, degrees 1608@fnindex ATAND 1609@fnindex DATAND 1610@cindex trigonometric function, tangent, inverse, degrees 1611@cindex tangent, inverse, degrees 1612 1613@table @asis 1614@item @emph{Description}: 1615@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of 1616@ref{TAND}). 1617 1618This function is for compatibility only and should be avoided in favor of 1619standard constructs wherever possible. 1620 1621@item @emph{Standard}: 1622GNU Extension, enabled with @option{-fdec-math}. 1623 1624@item @emph{Class}: 1625Elemental function 1626 1627@item @emph{Syntax}: 1628@multitable @columnfractions .80 1629@item @code{RESULT = ATAND(X)} 1630@item @code{RESULT = ATAND(Y, X)} 1631@end multitable 1632 1633@item @emph{Arguments}: 1634@multitable @columnfractions .15 .70 1635@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1636if @var{Y} is present, @var{X} shall be REAL. 1637@item @var{Y} shall be of the same type and kind as @var{X}. 1638@end multitable 1639 1640@item @emph{Return value}: 1641The return value is of the same type and kind as @var{X}. 1642If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}. 1643Otherwise, it is the arcus tangent of @var{X}, where the real part of 1644the result is in degrees and lies in the range 1645@math{-90 \leq \Re \atand(x) \leq 90}. 1646 1647@item @emph{Example}: 1648@smallexample 1649program test_atand 1650 real(8) :: x = 2.866_8 1651 x = atand(x) 1652end program test_atand 1653@end smallexample 1654 1655@item @emph{Specific names}: 1656@multitable @columnfractions .20 .20 .20 .25 1657@item Name @tab Argument @tab Return type @tab Standard 1658@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 1659@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 1660@end multitable 1661 1662@item @emph{See also}: 1663Inverse function: @ref{TAND} 1664Radians function: @ref{ATAN} 1665 1666@end table 1667 1668 1669 1670@node ATAN2 1671@section @code{ATAN2} --- Arctangent function 1672@fnindex ATAN2 1673@fnindex DATAN2 1674@cindex trigonometric function, tangent, inverse 1675@cindex tangent, inverse 1676 1677@table @asis 1678@item @emph{Description}: 1679@code{ATAN2(Y, X)} computes the principal value of the argument 1680function of the complex number @math{X + i Y}. This function can 1681be used to transform from Cartesian into polar coordinates and 1682allows to determine the angle in the correct quadrant. 1683 1684@item @emph{Standard}: 1685Fortran 77 and later 1686 1687@item @emph{Class}: 1688Elemental function 1689 1690@item @emph{Syntax}: 1691@code{RESULT = ATAN2(Y, X)} 1692 1693@item @emph{Arguments}: 1694@multitable @columnfractions .15 .70 1695@item @var{Y} @tab The type shall be @code{REAL}. 1696@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1697If @var{Y} is zero, then @var{X} must be nonzero. 1698@end multitable 1699 1700@item @emph{Return value}: 1701The return value has the same type and kind type parameter as @var{Y}. It 1702is the principal value of the complex number @math{X + i Y}. If @var{X} 1703is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}. 1704The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1705the return value is zero if @var{X} is strictly positive, @math{\pi} if 1706@var{X} is negative and @var{Y} is positive zero (or the processor does 1707not handle signed zeros), and @math{-\pi} if @var{X} is negative and 1708@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1709magnitude of the result is @math{\pi/2}. 1710 1711@item @emph{Example}: 1712@smallexample 1713program test_atan2 1714 real(4) :: x = 1.e0_4, y = 0.5e0_4 1715 x = atan2(y,x) 1716end program test_atan2 1717@end smallexample 1718 1719@item @emph{Specific names}: 1720@multitable @columnfractions .20 .20 .20 .25 1721@item Name @tab Argument @tab Return type @tab Standard 1722@item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 1723@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 1724@end multitable 1725 1726@item @emph{See also}: 1727Alias: @ref{ATAN} 1728Degrees function: @ref{ATAN2D} 1729 1730@end table 1731 1732 1733 1734@node ATAN2D 1735@section @code{ATAN2D} --- Arctangent function, degrees 1736@fnindex ATAN2D 1737@fnindex DATAN2D 1738@cindex trigonometric function, tangent, inverse, degrees 1739@cindex tangent, inverse, degrees 1740 1741@table @asis 1742@item @emph{Description}: 1743@code{ATAN2D(Y, X)} computes the principal value of the argument 1744function of the complex number @math{X + i Y} in degrees. This function can 1745be used to transform from Cartesian into polar coordinates and 1746allows to determine the angle in the correct quadrant. 1747 1748This function is for compatibility only and should be avoided in favor of 1749standard constructs wherever possible. 1750 1751@item @emph{Standard}: 1752GNU Extension, enabled with @option{-fdec-math}. 1753 1754@item @emph{Class}: 1755Elemental function 1756 1757@item @emph{Syntax}: 1758@code{RESULT = ATAN2D(Y, X)} 1759 1760@item @emph{Arguments}: 1761@multitable @columnfractions .15 .70 1762@item @var{Y} @tab The type shall be @code{REAL}. 1763@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1764If @var{Y} is zero, then @var{X} must be nonzero. 1765@end multitable 1766 1767@item @emph{Return value}: 1768The return value has the same type and kind type parameter as @var{Y}. It 1769is the principal value of the complex number @math{X + i Y}. If @var{X} 1770is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}. 1771The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1772the return value is zero if @var{X} is strictly positive, @math{180} if 1773@var{X} is negative and @var{Y} is positive zero (or the processor does 1774not handle signed zeros), and @math{-180} if @var{X} is negative and 1775@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1776magnitude of the result is @math{90}. 1777 1778@item @emph{Example}: 1779@smallexample 1780program test_atan2d 1781 real(4) :: x = 1.e0_4, y = 0.5e0_4 1782 x = atan2d(y,x) 1783end program test_atan2d 1784@end smallexample 1785 1786@item @emph{Specific names}: 1787@multitable @columnfractions .20 .20 .20 .25 1788@item Name @tab Argument @tab Return type @tab Standard 1789@item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension 1790@item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension 1791@end multitable 1792 1793@item @emph{See also}: 1794Alias: @ref{ATAND} 1795Radians function: @ref{ATAN2} 1796 1797@end table 1798 1799 1800 1801@node ATANH 1802@section @code{ATANH} --- Inverse hyperbolic tangent function 1803@fnindex ATANH 1804@fnindex DATANH 1805@cindex area hyperbolic tangent 1806@cindex inverse hyperbolic tangent 1807@cindex hyperbolic function, tangent, inverse 1808@cindex tangent, hyperbolic, inverse 1809 1810@table @asis 1811@item @emph{Description}: 1812@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}. 1813 1814@item @emph{Standard}: 1815Fortran 2008 and later 1816 1817@item @emph{Class}: 1818Elemental function 1819 1820@item @emph{Syntax}: 1821@code{RESULT = ATANH(X)} 1822 1823@item @emph{Arguments}: 1824@multitable @columnfractions .15 .70 1825@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1826@end multitable 1827 1828@item @emph{Return value}: 1829The return value has same type and kind as @var{X}. If @var{X} is 1830complex, the imaginary part of the result is in radians and lies between 1831@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}. 1832 1833@item @emph{Example}: 1834@smallexample 1835PROGRAM test_atanh 1836 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1837 WRITE (*,*) ATANH(x) 1838END PROGRAM 1839@end smallexample 1840 1841@item @emph{Specific names}: 1842@multitable @columnfractions .20 .20 .20 .25 1843@item Name @tab Argument @tab Return type @tab Standard 1844@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1845@end multitable 1846 1847@item @emph{See also}: 1848Inverse function: @ref{TANH} 1849@end table 1850 1851 1852 1853@node ATOMIC_ADD 1854@section @code{ATOMIC_ADD} --- Atomic ADD operation 1855@fnindex ATOMIC_ADD 1856@cindex Atomic subroutine, add 1857 1858@table @asis 1859@item @emph{Description}: 1860@code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the 1861variable @var{ATOM}. When @var{STAT} is present and the invocation was 1862successful, it is assigned the value 0. If it is present and the invocation 1863has failed, it is assigned a positive value; in particular, for a coindexed 1864@var{ATOM}, if the remote image has stopped, it is assigned the value of 1865@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1866failed, the value @code{STAT_FAILED_IMAGE}. 1867 1868@item @emph{Standard}: 1869TS 18508 or later 1870 1871@item @emph{Class}: 1872Atomic subroutine 1873 1874@item @emph{Syntax}: 1875@code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])} 1876 1877@item @emph{Arguments}: 1878@multitable @columnfractions .15 .70 1879@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1880type with @code{ATOMIC_INT_KIND} kind. 1881@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1882is different, the value is converted to the kind of @var{ATOM}. 1883@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1884@end multitable 1885 1886@item @emph{Example}: 1887@smallexample 1888program atomic 1889 use iso_fortran_env 1890 integer(atomic_int_kind) :: atom[*] 1891 call atomic_add (atom[1], this_image()) 1892end program atomic 1893@end smallexample 1894 1895@item @emph{See also}: 1896@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV}, 1897@ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 1898@end table 1899 1900 1901 1902 1903@node ATOMIC_AND 1904@section @code{ATOMIC_AND} --- Atomic bitwise AND operation 1905@fnindex ATOMIC_AND 1906@cindex Atomic subroutine, AND 1907 1908@table @asis 1909@item @emph{Description}: 1910@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 1911AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 1912and the invocation was successful, it is assigned the value 0. If it is present 1913and the invocation has failed, it is assigned a positive value; in particular, 1914for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 1915value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 1916image has failed, the value @code{STAT_FAILED_IMAGE}. 1917 1918@item @emph{Standard}: 1919TS 18508 or later 1920 1921@item @emph{Class}: 1922Atomic subroutine 1923 1924@item @emph{Syntax}: 1925@code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])} 1926 1927@item @emph{Arguments}: 1928@multitable @columnfractions .15 .70 1929@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1930type with @code{ATOMIC_INT_KIND} kind. 1931@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1932is different, the value is converted to the kind of @var{ATOM}. 1933@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1934@end multitable 1935 1936@item @emph{Example}: 1937@smallexample 1938program atomic 1939 use iso_fortran_env 1940 integer(atomic_int_kind) :: atom[*] 1941 call atomic_and (atom[1], int(b'10100011101')) 1942end program atomic 1943@end smallexample 1944 1945@item @emph{See also}: 1946@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV}, 1947@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 1948@end table 1949 1950 1951 1952@node ATOMIC_CAS 1953@section @code{ATOMIC_CAS} --- Atomic compare and swap 1954@fnindex ATOMIC_DEFINE 1955@cindex Atomic subroutine, compare and swap 1956 1957@table @asis 1958@item @emph{Description}: 1959@code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of 1960@var{COMPARE}; if the value is the same, @var{ATOM} is set to the value 1961of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM} 1962that was used for the comparison. When @var{STAT} is present and the invocation 1963was successful, it is assigned the value 0. If it is present and the invocation 1964has failed, it is assigned a positive value; in particular, for a coindexed 1965@var{ATOM}, if the remote image has stopped, it is assigned the value of 1966@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1967failed, the value @code{STAT_FAILED_IMAGE}. 1968 1969@item @emph{Standard}: 1970TS 18508 or later 1971 1972@item @emph{Class}: 1973Atomic subroutine 1974 1975@item @emph{Syntax}: 1976@code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])} 1977 1978@item @emph{Arguments}: 1979@multitable @columnfractions .15 .70 1980@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 1981type with @code{ATOMIC_INT_KIND} kind or logical type with 1982@code{ATOMIC_LOGICAL_KIND} kind. 1983@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 1984@item @var{COMPARE} @tab Scalar variable of the same type and kind as 1985@var{ATOM}. 1986@item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind 1987is different, the value is converted to the kind of @var{ATOM}. 1988@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1989@end multitable 1990 1991@item @emph{Example}: 1992@smallexample 1993program atomic 1994 use iso_fortran_env 1995 logical(atomic_logical_kind) :: atom[*], prev 1996 call atomic_cas (atom[1], prev, .false., .true.)) 1997end program atomic 1998@end smallexample 1999 2000@item @emph{See also}: 2001@ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV} 2002@end table 2003 2004 2005 2006@node ATOMIC_DEFINE 2007@section @code{ATOMIC_DEFINE} --- Setting a variable atomically 2008@fnindex ATOMIC_DEFINE 2009@cindex Atomic subroutine, define 2010 2011@table @asis 2012@item @emph{Description}: 2013@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value 2014@var{VALUE} atomically. When @var{STAT} is present and the invocation was 2015successful, it is assigned the value 0. If it is present and the invocation 2016has failed, it is assigned a positive value; in particular, for a coindexed 2017@var{ATOM}, if the remote image has stopped, it is assigned the value of 2018@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2019failed, the value @code{STAT_FAILED_IMAGE}. 2020 2021@item @emph{Standard}: 2022Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2023 2024@item @emph{Class}: 2025Atomic subroutine 2026 2027@item @emph{Syntax}: 2028@code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])} 2029 2030@item @emph{Arguments}: 2031@multitable @columnfractions .15 .70 2032@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2033type with @code{ATOMIC_INT_KIND} kind or logical type with 2034@code{ATOMIC_LOGICAL_KIND} kind. 2035 2036@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2037is different, the value is converted to the kind of @var{ATOM}. 2038@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2039@end multitable 2040 2041@item @emph{Example}: 2042@smallexample 2043program atomic 2044 use iso_fortran_env 2045 integer(atomic_int_kind) :: atom[*] 2046 call atomic_define (atom[1], this_image()) 2047end program atomic 2048@end smallexample 2049 2050@item @emph{See also}: 2051@ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV}, 2052@ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 2053@end table 2054 2055 2056 2057@node ATOMIC_FETCH_ADD 2058@section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch 2059@fnindex ATOMIC_FETCH_ADD 2060@cindex Atomic subroutine, ADD with fetch 2061 2062@table @asis 2063@item @emph{Description}: 2064@code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of 2065@var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the 2066variable @var{ATOM}. When @var{STAT} is present and the invocation was 2067successful, it is assigned the value 0. If it is present and the invocation 2068has failed, it is assigned a positive value; in particular, for a coindexed 2069@var{ATOM}, if the remote image has stopped, it is assigned the value of 2070@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2071failed, the value @code{STAT_FAILED_IMAGE}. 2072 2073@item @emph{Standard}: 2074TS 18508 or later 2075 2076@item @emph{Class}: 2077Atomic subroutine 2078 2079@item @emph{Syntax}: 2080@code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])} 2081 2082@item @emph{Arguments}: 2083@multitable @columnfractions .15 .70 2084@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2085type with @code{ATOMIC_INT_KIND} kind. 2086@code{ATOMIC_LOGICAL_KIND} kind. 2087 2088@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2089is different, the value is converted to the kind of @var{ATOM}. 2090@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2091@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2092@end multitable 2093 2094@item @emph{Example}: 2095@smallexample 2096program atomic 2097 use iso_fortran_env 2098 integer(atomic_int_kind) :: atom[*], old 2099 call atomic_add (atom[1], this_image(), old) 2100end program atomic 2101@end smallexample 2102 2103@item @emph{See also}: 2104@ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV}, 2105@ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} 2106@end table 2107 2108 2109 2110@node ATOMIC_FETCH_AND 2111@section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch 2112@fnindex ATOMIC_FETCH_AND 2113@cindex Atomic subroutine, AND with fetch 2114 2115@table @asis 2116@item @emph{Description}: 2117@code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2118@var{OLD} and defines @var{ATOM} with the bitwise AND between the values of 2119@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2120successful, it is assigned the value 0. If it is present and the invocation has 2121failed, it is assigned a positive value; in particular, for a coindexed 2122@var{ATOM}, if the remote image has stopped, it is assigned the value of 2123@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2124failed, the value @code{STAT_FAILED_IMAGE}. 2125 2126@item @emph{Standard}: 2127TS 18508 or later 2128 2129@item @emph{Class}: 2130Atomic subroutine 2131 2132@item @emph{Syntax}: 2133@code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])} 2134 2135@item @emph{Arguments}: 2136@multitable @columnfractions .15 .70 2137@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2138type with @code{ATOMIC_INT_KIND} kind. 2139@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2140is different, the value is converted to the kind of @var{ATOM}. 2141@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2142@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2143@end multitable 2144 2145@item @emph{Example}: 2146@smallexample 2147program atomic 2148 use iso_fortran_env 2149 integer(atomic_int_kind) :: atom[*], old 2150 call atomic_fetch_and (atom[1], int(b'10100011101'), old) 2151end program atomic 2152@end smallexample 2153 2154@item @emph{See also}: 2155@ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV}, 2156@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} 2157@end table 2158 2159 2160 2161@node ATOMIC_FETCH_OR 2162@section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch 2163@fnindex ATOMIC_FETCH_OR 2164@cindex Atomic subroutine, OR with fetch 2165 2166@table @asis 2167@item @emph{Description}: 2168@code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2169@var{OLD} and defines @var{ATOM} with the bitwise OR between the values of 2170@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2171successful, it is assigned the value 0. If it is present and the invocation has 2172failed, it is assigned a positive value; in particular, for a coindexed 2173@var{ATOM}, if the remote image has stopped, it is assigned the value of 2174@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2175failed, the value @code{STAT_FAILED_IMAGE}. 2176 2177@item @emph{Standard}: 2178TS 18508 or later 2179 2180@item @emph{Class}: 2181Atomic subroutine 2182 2183@item @emph{Syntax}: 2184@code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])} 2185 2186@item @emph{Arguments}: 2187@multitable @columnfractions .15 .70 2188@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2189type with @code{ATOMIC_INT_KIND} kind. 2190@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2191is different, the value is converted to the kind of @var{ATOM}. 2192@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2193@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2194@end multitable 2195 2196@item @emph{Example}: 2197@smallexample 2198program atomic 2199 use iso_fortran_env 2200 integer(atomic_int_kind) :: atom[*], old 2201 call atomic_fetch_or (atom[1], int(b'10100011101'), old) 2202end program atomic 2203@end smallexample 2204 2205@item @emph{See also}: 2206@ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV}, 2207@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR} 2208@end table 2209 2210 2211 2212@node ATOMIC_FETCH_XOR 2213@section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch 2214@fnindex ATOMIC_FETCH_XOR 2215@cindex Atomic subroutine, XOR with fetch 2216 2217@table @asis 2218@item @emph{Description}: 2219@code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 2220@var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of 2221@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was 2222successful, it is assigned the value 0. If it is present and the invocation has 2223failed, it is assigned a positive value; in particular, for a coindexed 2224@var{ATOM}, if the remote image has stopped, it is assigned the value of 2225@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 2226failed, the value @code{STAT_FAILED_IMAGE}. 2227 2228@item @emph{Standard}: 2229TS 18508 or later 2230 2231@item @emph{Class}: 2232Atomic subroutine 2233 2234@item @emph{Syntax}: 2235@code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])} 2236 2237@item @emph{Arguments}: 2238@multitable @columnfractions .15 .70 2239@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2240type with @code{ATOMIC_INT_KIND} kind. 2241@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2242is different, the value is converted to the kind of @var{ATOM}. 2243@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 2244@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2245@end multitable 2246 2247@item @emph{Example}: 2248@smallexample 2249program atomic 2250 use iso_fortran_env 2251 integer(atomic_int_kind) :: atom[*], old 2252 call atomic_fetch_xor (atom[1], int(b'10100011101'), old) 2253end program atomic 2254@end smallexample 2255 2256@item @emph{See also}: 2257@ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV}, 2258@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR} 2259@end table 2260 2261 2262 2263@node ATOMIC_OR 2264@section @code{ATOMIC_OR} --- Atomic bitwise OR operation 2265@fnindex ATOMIC_OR 2266@cindex Atomic subroutine, OR 2267 2268@table @asis 2269@item @emph{Description}: 2270@code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2271AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2272and the invocation was successful, it is assigned the value 0. If it is present 2273and the invocation has failed, it is assigned a positive value; in particular, 2274for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2275value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2276image has failed, the value @code{STAT_FAILED_IMAGE}. 2277 2278@item @emph{Standard}: 2279TS 18508 or later 2280 2281@item @emph{Class}: 2282Atomic subroutine 2283 2284@item @emph{Syntax}: 2285@code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])} 2286 2287@item @emph{Arguments}: 2288@multitable @columnfractions .15 .70 2289@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2290type with @code{ATOMIC_INT_KIND} kind. 2291@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2292is different, the value is converted to the kind of @var{ATOM}. 2293@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2294@end multitable 2295 2296@item @emph{Example}: 2297@smallexample 2298program atomic 2299 use iso_fortran_env 2300 integer(atomic_int_kind) :: atom[*] 2301 call atomic_or (atom[1], int(b'10100011101')) 2302end program atomic 2303@end smallexample 2304 2305@item @emph{See also}: 2306@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV}, 2307@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 2308@end table 2309 2310 2311 2312@node ATOMIC_REF 2313@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically 2314@fnindex ATOMIC_REF 2315@cindex Atomic subroutine, reference 2316 2317@table @asis 2318@item @emph{Description}: 2319@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the 2320variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the 2321invocation was successful, it is assigned the value 0. If it is present and the 2322invocation has failed, it is assigned a positive value; in particular, for a 2323coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value 2324of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image 2325has failed, the value @code{STAT_FAILED_IMAGE}. 2326 2327 2328@item @emph{Standard}: 2329Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2330 2331@item @emph{Class}: 2332Atomic subroutine 2333 2334@item @emph{Syntax}: 2335@code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])} 2336 2337@item @emph{Arguments}: 2338@multitable @columnfractions .15 .70 2339@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2340is different, the value is converted to the kind of @var{ATOM}. 2341@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2342type with @code{ATOMIC_INT_KIND} kind or logical type with 2343@code{ATOMIC_LOGICAL_KIND} kind. 2344@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2345@end multitable 2346 2347@item @emph{Example}: 2348@smallexample 2349program atomic 2350 use iso_fortran_env 2351 logical(atomic_logical_kind) :: atom[*] 2352 logical :: val 2353 call atomic_ref (atom, .false.) 2354 ! ... 2355 call atomic_ref (atom, val) 2356 if (val) then 2357 print *, "Obtained" 2358 end if 2359end program atomic 2360@end smallexample 2361 2362@item @emph{See also}: 2363@ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV}, 2364@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, 2365@ref{ATOMIC_FETCH_XOR} 2366@end table 2367 2368 2369@node ATOMIC_XOR 2370@section @code{ATOMIC_XOR} --- Atomic bitwise OR operation 2371@fnindex ATOMIC_XOR 2372@cindex Atomic subroutine, XOR 2373 2374@table @asis 2375@item @emph{Description}: 2376@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2377XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2378and the invocation was successful, it is assigned the value 0. If it is present 2379and the invocation has failed, it is assigned a positive value; in particular, 2380for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2381value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2382image has failed, the value @code{STAT_FAILED_IMAGE}. 2383 2384@item @emph{Standard}: 2385TS 18508 or later 2386 2387@item @emph{Class}: 2388Atomic subroutine 2389 2390@item @emph{Syntax}: 2391@code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])} 2392 2393@item @emph{Arguments}: 2394@multitable @columnfractions .15 .70 2395@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2396type with @code{ATOMIC_INT_KIND} kind. 2397@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2398is different, the value is converted to the kind of @var{ATOM}. 2399@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2400@end multitable 2401 2402@item @emph{Example}: 2403@smallexample 2404program atomic 2405 use iso_fortran_env 2406 integer(atomic_int_kind) :: atom[*] 2407 call atomic_xor (atom[1], int(b'10100011101')) 2408end program atomic 2409@end smallexample 2410 2411@item @emph{See also}: 2412@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV}, 2413@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 2414@end table 2415 2416 2417@node BACKTRACE 2418@section @code{BACKTRACE} --- Show a backtrace 2419@fnindex BACKTRACE 2420@cindex backtrace 2421 2422@table @asis 2423@item @emph{Description}: 2424@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program 2425execution continues normally afterwards. The backtrace information is printed 2426to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}. 2427 2428@item @emph{Standard}: 2429GNU Extension 2430 2431@item @emph{Class}: 2432Subroutine 2433 2434@item @emph{Syntax}: 2435@code{CALL BACKTRACE} 2436 2437@item @emph{Arguments}: 2438None 2439 2440@item @emph{See also}: 2441@ref{ABORT} 2442@end table 2443 2444 2445 2446@node BESSEL_J0 2447@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0 2448@fnindex BESSEL_J0 2449@fnindex BESJ0 2450@fnindex DBESJ0 2451@cindex Bessel function, first kind 2452 2453@table @asis 2454@item @emph{Description}: 2455@code{BESSEL_J0(X)} computes the Bessel function of the first kind of 2456order 0 of @var{X}. This function is available under the name 2457@code{BESJ0} as a GNU extension. 2458 2459@item @emph{Standard}: 2460Fortran 2008 and later 2461 2462@item @emph{Class}: 2463Elemental function 2464 2465@item @emph{Syntax}: 2466@code{RESULT = BESSEL_J0(X)} 2467 2468@item @emph{Arguments}: 2469@multitable @columnfractions .15 .70 2470@item @var{X} @tab The type shall be @code{REAL}. 2471@end multitable 2472 2473@item @emph{Return value}: 2474The return value is of type @code{REAL} and lies in the 2475range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same 2476kind as @var{X}. 2477 2478@item @emph{Example}: 2479@smallexample 2480program test_besj0 2481 real(8) :: x = 0.0_8 2482 x = bessel_j0(x) 2483end program test_besj0 2484@end smallexample 2485 2486@item @emph{Specific names}: 2487@multitable @columnfractions .20 .20 .20 .25 2488@item Name @tab Argument @tab Return type @tab Standard 2489@item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2490@end multitable 2491@end table 2492 2493 2494 2495@node BESSEL_J1 2496@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1 2497@fnindex BESSEL_J1 2498@fnindex BESJ1 2499@fnindex DBESJ1 2500@cindex Bessel function, first kind 2501 2502@table @asis 2503@item @emph{Description}: 2504@code{BESSEL_J1(X)} computes the Bessel function of the first kind of 2505order 1 of @var{X}. This function is available under the name 2506@code{BESJ1} as a GNU extension. 2507 2508@item @emph{Standard}: 2509Fortran 2008 2510 2511@item @emph{Class}: 2512Elemental function 2513 2514@item @emph{Syntax}: 2515@code{RESULT = BESSEL_J1(X)} 2516 2517@item @emph{Arguments}: 2518@multitable @columnfractions .15 .70 2519@item @var{X} @tab The type shall be @code{REAL}. 2520@end multitable 2521 2522@item @emph{Return value}: 2523The return value is of type @code{REAL} and lies in the 2524range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same 2525kind as @var{X}. 2526 2527@item @emph{Example}: 2528@smallexample 2529program test_besj1 2530 real(8) :: x = 1.0_8 2531 x = bessel_j1(x) 2532end program test_besj1 2533@end smallexample 2534 2535@item @emph{Specific names}: 2536@multitable @columnfractions .20 .20 .20 .25 2537@item Name @tab Argument @tab Return type @tab Standard 2538@item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2539@end multitable 2540@end table 2541 2542 2543 2544@node BESSEL_JN 2545@section @code{BESSEL_JN} --- Bessel function of the first kind 2546@fnindex BESSEL_JN 2547@fnindex BESJN 2548@fnindex DBESJN 2549@cindex Bessel function, first kind 2550 2551@table @asis 2552@item @emph{Description}: 2553@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of 2554order @var{N} of @var{X}. This function is available under the name 2555@code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays, 2556their ranks and shapes shall conform. 2557 2558@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions 2559of the first kind of the orders @var{N1} to @var{N2}. 2560 2561@item @emph{Standard}: 2562Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2563 2564@item @emph{Class}: 2565Elemental function, except for the transformational function 2566@code{BESSEL_JN(N1, N2, X)} 2567 2568@item @emph{Syntax}: 2569@multitable @columnfractions .80 2570@item @code{RESULT = BESSEL_JN(N, X)} 2571@item @code{RESULT = BESSEL_JN(N1, N2, X)} 2572@end multitable 2573 2574@item @emph{Arguments}: 2575@multitable @columnfractions .15 .70 2576@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}. 2577@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2578@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2579@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2580for @code{BESSEL_JN(N1, N2, X)} it shall be scalar. 2581@end multitable 2582 2583@item @emph{Return value}: 2584The return value is a scalar of type @code{REAL}. It has the same 2585kind as @var{X}. 2586 2587@item @emph{Note}: 2588The transformational function uses a recurrence algorithm which might, 2589for some values of @var{X}, lead to different results than calls to 2590the elemental function. 2591 2592@item @emph{Example}: 2593@smallexample 2594program test_besjn 2595 real(8) :: x = 1.0_8 2596 x = bessel_jn(5,x) 2597end program test_besjn 2598@end smallexample 2599 2600@item @emph{Specific names}: 2601@multitable @columnfractions .20 .20 .20 .25 2602@item Name @tab Argument @tab Return type @tab Standard 2603@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2604@item @tab @code{REAL(8) X} @tab @tab 2605@end multitable 2606@end table 2607 2608 2609 2610@node BESSEL_Y0 2611@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0 2612@fnindex BESSEL_Y0 2613@fnindex BESY0 2614@fnindex DBESY0 2615@cindex Bessel function, second kind 2616 2617@table @asis 2618@item @emph{Description}: 2619@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of 2620order 0 of @var{X}. This function is available under the name 2621@code{BESY0} as a GNU extension. 2622 2623@item @emph{Standard}: 2624Fortran 2008 and later 2625 2626@item @emph{Class}: 2627Elemental function 2628 2629@item @emph{Syntax}: 2630@code{RESULT = BESSEL_Y0(X)} 2631 2632@item @emph{Arguments}: 2633@multitable @columnfractions .15 .70 2634@item @var{X} @tab The type shall be @code{REAL}. 2635@end multitable 2636 2637@item @emph{Return value}: 2638The return value is of type @code{REAL}. It has the same kind as @var{X}. 2639 2640@item @emph{Example}: 2641@smallexample 2642program test_besy0 2643 real(8) :: x = 0.0_8 2644 x = bessel_y0(x) 2645end program test_besy0 2646@end smallexample 2647 2648@item @emph{Specific names}: 2649@multitable @columnfractions .20 .20 .20 .25 2650@item Name @tab Argument @tab Return type @tab Standard 2651@item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2652@end multitable 2653@end table 2654 2655 2656 2657@node BESSEL_Y1 2658@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1 2659@fnindex BESSEL_Y1 2660@fnindex BESY1 2661@fnindex DBESY1 2662@cindex Bessel function, second kind 2663 2664@table @asis 2665@item @emph{Description}: 2666@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of 2667order 1 of @var{X}. This function is available under the name 2668@code{BESY1} as a GNU extension. 2669 2670@item @emph{Standard}: 2671Fortran 2008 and later 2672 2673@item @emph{Class}: 2674Elemental function 2675 2676@item @emph{Syntax}: 2677@code{RESULT = BESSEL_Y1(X)} 2678 2679@item @emph{Arguments}: 2680@multitable @columnfractions .15 .70 2681@item @var{X} @tab The type shall be @code{REAL}. 2682@end multitable 2683 2684@item @emph{Return value}: 2685The return value is of type @code{REAL}. It has the same kind as @var{X}. 2686 2687@item @emph{Example}: 2688@smallexample 2689program test_besy1 2690 real(8) :: x = 1.0_8 2691 x = bessel_y1(x) 2692end program test_besy1 2693@end smallexample 2694 2695@item @emph{Specific names}: 2696@multitable @columnfractions .20 .20 .20 .25 2697@item Name @tab Argument @tab Return type @tab Standard 2698@item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2699@end multitable 2700@end table 2701 2702 2703 2704@node BESSEL_YN 2705@section @code{BESSEL_YN} --- Bessel function of the second kind 2706@fnindex BESSEL_YN 2707@fnindex BESYN 2708@fnindex DBESYN 2709@cindex Bessel function, second kind 2710 2711@table @asis 2712@item @emph{Description}: 2713@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of 2714order @var{N} of @var{X}. This function is available under the name 2715@code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays, 2716their ranks and shapes shall conform. 2717 2718@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions 2719of the first kind of the orders @var{N1} to @var{N2}. 2720 2721@item @emph{Standard}: 2722Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2723 2724@item @emph{Class}: 2725Elemental function, except for the transformational function 2726@code{BESSEL_YN(N1, N2, X)} 2727 2728@item @emph{Syntax}: 2729@multitable @columnfractions .80 2730@item @code{RESULT = BESSEL_YN(N, X)} 2731@item @code{RESULT = BESSEL_YN(N1, N2, X)} 2732@end multitable 2733 2734@item @emph{Arguments}: 2735@multitable @columnfractions .15 .70 2736@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} . 2737@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2738@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2739@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2740for @code{BESSEL_YN(N1, N2, X)} it shall be scalar. 2741@end multitable 2742 2743@item @emph{Return value}: 2744The return value is a scalar of type @code{REAL}. It has the same 2745kind as @var{X}. 2746 2747@item @emph{Note}: 2748The transformational function uses a recurrence algorithm which might, 2749for some values of @var{X}, lead to different results than calls to 2750the elemental function. 2751 2752@item @emph{Example}: 2753@smallexample 2754program test_besyn 2755 real(8) :: x = 1.0_8 2756 x = bessel_yn(5,x) 2757end program test_besyn 2758@end smallexample 2759 2760@item @emph{Specific names}: 2761@multitable @columnfractions .20 .20 .20 .25 2762@item Name @tab Argument @tab Return type @tab Standard 2763@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2764@item @tab @code{REAL(8) X} @tab @tab 2765@end multitable 2766@end table 2767 2768 2769 2770@node BGE 2771@section @code{BGE} --- Bitwise greater than or equal to 2772@fnindex BGE 2773@cindex bitwise comparison 2774 2775@table @asis 2776@item @emph{Description}: 2777Determines whether an integral is a bitwise greater than or equal to 2778another. 2779 2780@item @emph{Standard}: 2781Fortran 2008 and later 2782 2783@item @emph{Class}: 2784Elemental function 2785 2786@item @emph{Syntax}: 2787@code{RESULT = BGE(I, J)} 2788 2789@item @emph{Arguments}: 2790@multitable @columnfractions .15 .70 2791@item @var{I} @tab Shall be of @code{INTEGER} type. 2792@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2793as @var{I}. 2794@end multitable 2795 2796@item @emph{Return value}: 2797The return value is of type @code{LOGICAL} and of the default kind. 2798 2799@item @emph{See also}: 2800@ref{BGT}, @ref{BLE}, @ref{BLT} 2801@end table 2802 2803 2804 2805@node BGT 2806@section @code{BGT} --- Bitwise greater than 2807@fnindex BGT 2808@cindex bitwise comparison 2809 2810@table @asis 2811@item @emph{Description}: 2812Determines whether an integral is a bitwise greater than another. 2813 2814@item @emph{Standard}: 2815Fortran 2008 and later 2816 2817@item @emph{Class}: 2818Elemental function 2819 2820@item @emph{Syntax}: 2821@code{RESULT = BGT(I, J)} 2822 2823@item @emph{Arguments}: 2824@multitable @columnfractions .15 .70 2825@item @var{I} @tab Shall be of @code{INTEGER} type. 2826@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2827as @var{I}. 2828@end multitable 2829 2830@item @emph{Return value}: 2831The return value is of type @code{LOGICAL} and of the default kind. 2832 2833@item @emph{See also}: 2834@ref{BGE}, @ref{BLE}, @ref{BLT} 2835@end table 2836 2837 2838 2839@node BIT_SIZE 2840@section @code{BIT_SIZE} --- Bit size inquiry function 2841@fnindex BIT_SIZE 2842@cindex bits, number of 2843@cindex size of a variable, in bits 2844 2845@table @asis 2846@item @emph{Description}: 2847@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) 2848represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is 2849independent of the actual value of @var{I}. 2850 2851@item @emph{Standard}: 2852Fortran 95 and later 2853 2854@item @emph{Class}: 2855Inquiry function 2856 2857@item @emph{Syntax}: 2858@code{RESULT = BIT_SIZE(I)} 2859 2860@item @emph{Arguments}: 2861@multitable @columnfractions .15 .70 2862@item @var{I} @tab The type shall be @code{INTEGER}. 2863@end multitable 2864 2865@item @emph{Return value}: 2866The return value is of type @code{INTEGER} 2867 2868@item @emph{Example}: 2869@smallexample 2870program test_bit_size 2871 integer :: i = 123 2872 integer :: size 2873 size = bit_size(i) 2874 print *, size 2875end program test_bit_size 2876@end smallexample 2877@end table 2878 2879 2880 2881@node BLE 2882@section @code{BLE} --- Bitwise less than or equal to 2883@fnindex BLE 2884@cindex bitwise comparison 2885 2886@table @asis 2887@item @emph{Description}: 2888Determines whether an integral is a bitwise less than or equal to 2889another. 2890 2891@item @emph{Standard}: 2892Fortran 2008 and later 2893 2894@item @emph{Class}: 2895Elemental function 2896 2897@item @emph{Syntax}: 2898@code{RESULT = BLE(I, J)} 2899 2900@item @emph{Arguments}: 2901@multitable @columnfractions .15 .70 2902@item @var{I} @tab Shall be of @code{INTEGER} type. 2903@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2904as @var{I}. 2905@end multitable 2906 2907@item @emph{Return value}: 2908The return value is of type @code{LOGICAL} and of the default kind. 2909 2910@item @emph{See also}: 2911@ref{BGT}, @ref{BGE}, @ref{BLT} 2912@end table 2913 2914 2915 2916@node BLT 2917@section @code{BLT} --- Bitwise less than 2918@fnindex BLT 2919@cindex bitwise comparison 2920 2921@table @asis 2922@item @emph{Description}: 2923Determines whether an integral is a bitwise less than another. 2924 2925@item @emph{Standard}: 2926Fortran 2008 and later 2927 2928@item @emph{Class}: 2929Elemental function 2930 2931@item @emph{Syntax}: 2932@code{RESULT = BLT(I, J)} 2933 2934@item @emph{Arguments}: 2935@multitable @columnfractions .15 .70 2936@item @var{I} @tab Shall be of @code{INTEGER} type. 2937@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2938as @var{I}. 2939@end multitable 2940 2941@item @emph{Return value}: 2942The return value is of type @code{LOGICAL} and of the default kind. 2943 2944@item @emph{See also}: 2945@ref{BGE}, @ref{BGT}, @ref{BLE} 2946@end table 2947 2948 2949 2950@node BTEST 2951@section @code{BTEST} --- Bit test function 2952@fnindex BTEST 2953@fnindex BBTEST 2954@fnindex BITEST 2955@fnindex BJTEST 2956@fnindex BKTEST 2957@cindex bits, testing 2958 2959@table @asis 2960@item @emph{Description}: 2961@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} 2962in @var{I} is set. The counting of the bits starts at 0. 2963 2964@item @emph{Standard}: 2965Fortran 95 and later, has overloads that are GNU extensions 2966 2967@item @emph{Class}: 2968Elemental function 2969 2970@item @emph{Syntax}: 2971@code{RESULT = BTEST(I, POS)} 2972 2973@item @emph{Arguments}: 2974@multitable @columnfractions .15 .70 2975@item @var{I} @tab The type shall be @code{INTEGER}. 2976@item @var{POS} @tab The type shall be @code{INTEGER}. 2977@end multitable 2978 2979@item @emph{Return value}: 2980The return value is of type @code{LOGICAL} 2981 2982@item @emph{Example}: 2983@smallexample 2984program test_btest 2985 integer :: i = 32768 + 1024 + 64 2986 integer :: pos 2987 logical :: bool 2988 do pos=0,16 2989 bool = btest(i, pos) 2990 print *, pos, bool 2991 end do 2992end program test_btest 2993@end smallexample 2994 2995@item @emph{Specific names}: 2996@multitable @columnfractions .20 .20 .20 .25 2997@item Name @tab Argument @tab Return type @tab Standard 2998@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later 2999@item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension 3000@item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension 3001@item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension 3002@item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension 3003@end multitable 3004@end table 3005 3006@node C_ASSOCIATED 3007@section @code{C_ASSOCIATED} --- Status of a C pointer 3008@fnindex C_ASSOCIATED 3009@cindex association status, C pointer 3010@cindex pointer, C association status 3011 3012@table @asis 3013@item @emph{Description}: 3014@code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer 3015@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}. 3016 3017@item @emph{Standard}: 3018Fortran 2003 and later 3019 3020@item @emph{Class}: 3021Inquiry function 3022 3023@item @emph{Syntax}: 3024@code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])} 3025 3026@item @emph{Arguments}: 3027@multitable @columnfractions .15 .70 3028@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}. 3029@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}. 3030@end multitable 3031 3032@item @emph{Return value}: 3033The return value is of type @code{LOGICAL}; it is @code{.false.} if either 3034@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2} 3035point to different addresses. 3036 3037@item @emph{Example}: 3038@smallexample 3039subroutine association_test(a,b) 3040 use iso_c_binding, only: c_associated, c_loc, c_ptr 3041 implicit none 3042 real, pointer :: a 3043 type(c_ptr) :: b 3044 if(c_associated(b, c_loc(a))) & 3045 stop 'b and a do not point to same target' 3046end subroutine association_test 3047@end smallexample 3048 3049@item @emph{See also}: 3050@ref{C_LOC}, @ref{C_FUNLOC} 3051@end table 3052 3053 3054@node C_F_POINTER 3055@section @code{C_F_POINTER} --- Convert C into Fortran pointer 3056@fnindex C_F_POINTER 3057@cindex pointer, convert C to Fortran 3058 3059@table @asis 3060@item @emph{Description}: 3061@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer 3062@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape. 3063 3064@item @emph{Standard}: 3065Fortran 2003 and later 3066 3067@item @emph{Class}: 3068Subroutine 3069 3070@item @emph{Syntax}: 3071@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])} 3072 3073@item @emph{Arguments}: 3074@multitable @columnfractions .15 .70 3075@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is 3076@code{INTENT(IN)}. 3077@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is 3078@code{INTENT(OUT)}. 3079@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER} 3080with @code{INTENT(IN)}. It shall be present 3081if and only if @var{fptr} is an array. The size 3082must be equal to the rank of @var{fptr}. 3083@end multitable 3084 3085@item @emph{Example}: 3086@smallexample 3087program main 3088 use iso_c_binding 3089 implicit none 3090 interface 3091 subroutine my_routine(p) bind(c,name='myC_func') 3092 import :: c_ptr 3093 type(c_ptr), intent(out) :: p 3094 end subroutine 3095 end interface 3096 type(c_ptr) :: cptr 3097 real,pointer :: a(:) 3098 call my_routine(cptr) 3099 call c_f_pointer(cptr, a, [12]) 3100end program main 3101@end smallexample 3102 3103@item @emph{See also}: 3104@ref{C_LOC}, @ref{C_F_PROCPOINTER} 3105@end table 3106 3107 3108@node C_F_PROCPOINTER 3109@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer 3110@fnindex C_F_PROCPOINTER 3111@cindex pointer, C address of pointers 3112 3113@table @asis 3114@item @emph{Description}: 3115@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer 3116@var{CPTR} to the Fortran procedure pointer @var{FPTR}. 3117 3118@item @emph{Standard}: 3119Fortran 2003 and later 3120 3121@item @emph{Class}: 3122Subroutine 3123 3124@item @emph{Syntax}: 3125@code{CALL C_F_PROCPOINTER(cptr, fptr)} 3126 3127@item @emph{Arguments}: 3128@multitable @columnfractions .15 .70 3129@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is 3130@code{INTENT(IN)}. 3131@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is 3132@code{INTENT(OUT)}. 3133@end multitable 3134 3135@item @emph{Example}: 3136@smallexample 3137program main 3138 use iso_c_binding 3139 implicit none 3140 abstract interface 3141 function func(a) 3142 import :: c_float 3143 real(c_float), intent(in) :: a 3144 real(c_float) :: func 3145 end function 3146 end interface 3147 interface 3148 function getIterFunc() bind(c,name="getIterFunc") 3149 import :: c_funptr 3150 type(c_funptr) :: getIterFunc 3151 end function 3152 end interface 3153 type(c_funptr) :: cfunptr 3154 procedure(func), pointer :: myFunc 3155 cfunptr = getIterFunc() 3156 call c_f_procpointer(cfunptr, myFunc) 3157end program main 3158@end smallexample 3159 3160@item @emph{See also}: 3161@ref{C_LOC}, @ref{C_F_POINTER} 3162@end table 3163 3164 3165@node C_FUNLOC 3166@section @code{C_FUNLOC} --- Obtain the C address of a procedure 3167@fnindex C_FUNLOC 3168@cindex pointer, C address of procedures 3169 3170@table @asis 3171@item @emph{Description}: 3172@code{C_FUNLOC(x)} determines the C address of the argument. 3173 3174@item @emph{Standard}: 3175Fortran 2003 and later 3176 3177@item @emph{Class}: 3178Inquiry function 3179 3180@item @emph{Syntax}: 3181@code{RESULT = C_FUNLOC(x)} 3182 3183@item @emph{Arguments}: 3184@multitable @columnfractions .15 .70 3185@item @var{x} @tab Interoperable function or pointer to such function. 3186@end multitable 3187 3188@item @emph{Return value}: 3189The return value is of type @code{C_FUNPTR} and contains the C address 3190of the argument. 3191 3192@item @emph{Example}: 3193@smallexample 3194module x 3195 use iso_c_binding 3196 implicit none 3197contains 3198 subroutine sub(a) bind(c) 3199 real(c_float) :: a 3200 a = sqrt(a)+5.0 3201 end subroutine sub 3202end module x 3203program main 3204 use iso_c_binding 3205 use x 3206 implicit none 3207 interface 3208 subroutine my_routine(p) bind(c,name='myC_func') 3209 import :: c_funptr 3210 type(c_funptr), intent(in) :: p 3211 end subroutine 3212 end interface 3213 call my_routine(c_funloc(sub)) 3214end program main 3215@end smallexample 3216 3217@item @emph{See also}: 3218@ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} 3219@end table 3220 3221 3222@node C_LOC 3223@section @code{C_LOC} --- Obtain the C address of an object 3224@fnindex C_LOC 3225@cindex procedure pointer, convert C to Fortran 3226 3227@table @asis 3228@item @emph{Description}: 3229@code{C_LOC(X)} determines the C address of the argument. 3230 3231@item @emph{Standard}: 3232Fortran 2003 and later 3233 3234@item @emph{Class}: 3235Inquiry function 3236 3237@item @emph{Syntax}: 3238@code{RESULT = C_LOC(X)} 3239 3240@item @emph{Arguments}: 3241@multitable @columnfractions .10 .75 3242@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. 3243 3244@end multitable 3245 3246@item @emph{Return value}: 3247The return value is of type @code{C_PTR} and contains the C address 3248of the argument. 3249 3250@item @emph{Example}: 3251@smallexample 3252subroutine association_test(a,b) 3253 use iso_c_binding, only: c_associated, c_loc, c_ptr 3254 implicit none 3255 real, pointer :: a 3256 type(c_ptr) :: b 3257 if(c_associated(b, c_loc(a))) & 3258 stop 'b and a do not point to same target' 3259end subroutine association_test 3260@end smallexample 3261 3262@item @emph{See also}: 3263@ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} 3264@end table 3265 3266 3267@node C_SIZEOF 3268@section @code{C_SIZEOF} --- Size in bytes of an expression 3269@fnindex C_SIZEOF 3270@cindex expression size 3271@cindex size of an expression 3272 3273@table @asis 3274@item @emph{Description}: 3275@code{C_SIZEOF(X)} calculates the number of bytes of storage the 3276expression @code{X} occupies. 3277 3278@item @emph{Standard}: 3279Fortran 2008 3280 3281@item @emph{Class}: 3282Inquiry function of the module @code{ISO_C_BINDING} 3283 3284@item @emph{Syntax}: 3285@code{N = C_SIZEOF(X)} 3286 3287@item @emph{Arguments}: 3288@multitable @columnfractions .15 .70 3289@item @var{X} @tab The argument shall be an interoperable data entity. 3290@end multitable 3291 3292@item @emph{Return value}: 3293The return value is of type integer and of the system-dependent kind 3294@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the 3295number of bytes occupied by the argument. If the argument has the 3296@code{POINTER} attribute, the number of bytes of the storage area pointed 3297to is returned. If the argument is of a derived type with @code{POINTER} 3298or @code{ALLOCATABLE} components, the return value does not account for 3299the sizes of the data pointed to by these components. 3300 3301@item @emph{Example}: 3302@smallexample 3303 use iso_c_binding 3304 integer(c_int) :: i 3305 real(c_float) :: r, s(5) 3306 print *, (c_sizeof(s)/c_sizeof(r) == 5) 3307 end 3308@end smallexample 3309The example will print @code{.TRUE.} unless you are using a platform 3310where default @code{REAL} variables are unusually padded. 3311 3312@item @emph{See also}: 3313@ref{SIZEOF}, @ref{STORAGE_SIZE} 3314@end table 3315 3316 3317@node CEILING 3318@section @code{CEILING} --- Integer ceiling function 3319@fnindex CEILING 3320@cindex ceiling 3321@cindex rounding, ceiling 3322 3323@table @asis 3324@item @emph{Description}: 3325@code{CEILING(A)} returns the least integer greater than or equal to @var{A}. 3326 3327@item @emph{Standard}: 3328Fortran 95 and later 3329 3330@item @emph{Class}: 3331Elemental function 3332 3333@item @emph{Syntax}: 3334@code{RESULT = CEILING(A [, KIND])} 3335 3336@item @emph{Arguments}: 3337@multitable @columnfractions .15 .70 3338@item @var{A} @tab The type shall be @code{REAL}. 3339@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3340expression indicating the kind parameter of the result. 3341@end multitable 3342 3343@item @emph{Return value}: 3344The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 3345and a default-kind @code{INTEGER} otherwise. 3346 3347@item @emph{Example}: 3348@smallexample 3349program test_ceiling 3350 real :: x = 63.29 3351 real :: y = -63.59 3352 print *, ceiling(x) ! returns 64 3353 print *, ceiling(y) ! returns -63 3354end program test_ceiling 3355@end smallexample 3356 3357@item @emph{See also}: 3358@ref{FLOOR}, @ref{NINT} 3359 3360@end table 3361 3362 3363 3364@node CHAR 3365@section @code{CHAR} --- Character conversion function 3366@fnindex CHAR 3367@cindex conversion, to character 3368 3369@table @asis 3370@item @emph{Description}: 3371@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}. 3372 3373@item @emph{Standard}: 3374Fortran 77 and later 3375 3376@item @emph{Class}: 3377Elemental function 3378 3379@item @emph{Syntax}: 3380@code{RESULT = CHAR(I [, KIND])} 3381 3382@item @emph{Arguments}: 3383@multitable @columnfractions .15 .70 3384@item @var{I} @tab The type shall be @code{INTEGER}. 3385@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3386expression indicating the kind parameter of the result. 3387@end multitable 3388 3389@item @emph{Return value}: 3390The return value is of type @code{CHARACTER(1)} 3391 3392@item @emph{Example}: 3393@smallexample 3394program test_char 3395 integer :: i = 74 3396 character(1) :: c 3397 c = char(i) 3398 print *, i, c ! returns 'J' 3399end program test_char 3400@end smallexample 3401 3402@item @emph{Specific names}: 3403@multitable @columnfractions .20 .20 .20 .25 3404@item Name @tab Argument @tab Return type @tab Standard 3405@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later 3406@end multitable 3407 3408@item @emph{Note}: 3409See @ref{ICHAR} for a discussion of converting between numerical values 3410and formatted string representations. 3411 3412@item @emph{See also}: 3413@ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR} 3414 3415@end table 3416 3417 3418 3419@node CHDIR 3420@section @code{CHDIR} --- Change working directory 3421@fnindex CHDIR 3422@cindex system, working directory 3423 3424@table @asis 3425@item @emph{Description}: 3426Change current working directory to a specified path. 3427 3428This intrinsic is provided in both subroutine and function forms; however, 3429only one form can be used in any given program unit. 3430 3431@item @emph{Standard}: 3432GNU extension 3433 3434@item @emph{Class}: 3435Subroutine, function 3436 3437@item @emph{Syntax}: 3438@multitable @columnfractions .80 3439@item @code{CALL CHDIR(NAME [, STATUS])} 3440@item @code{STATUS = CHDIR(NAME)} 3441@end multitable 3442 3443@item @emph{Arguments}: 3444@multitable @columnfractions .15 .70 3445@item @var{NAME} @tab The type shall be @code{CHARACTER} of default 3446kind and shall specify a valid path within the file system. 3447@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default 3448kind. Returns 0 on success, and a system specific and nonzero error code 3449otherwise. 3450@end multitable 3451 3452@item @emph{Example}: 3453@smallexample 3454PROGRAM test_chdir 3455 CHARACTER(len=255) :: path 3456 CALL getcwd(path) 3457 WRITE(*,*) TRIM(path) 3458 CALL chdir("/tmp") 3459 CALL getcwd(path) 3460 WRITE(*,*) TRIM(path) 3461END PROGRAM 3462@end smallexample 3463 3464@item @emph{See also}: 3465@ref{GETCWD} 3466@end table 3467 3468 3469 3470@node CHMOD 3471@section @code{CHMOD} --- Change access permissions of files 3472@fnindex CHMOD 3473@cindex file system, change access mode 3474 3475@table @asis 3476@item @emph{Description}: 3477@code{CHMOD} changes the permissions of a file. 3478 3479This intrinsic is provided in both subroutine and function forms; however, 3480only one form can be used in any given program unit. 3481 3482@item @emph{Standard}: 3483GNU extension 3484 3485@item @emph{Class}: 3486Subroutine, function 3487 3488@item @emph{Syntax}: 3489@multitable @columnfractions .80 3490@item @code{CALL CHMOD(NAME, MODE[, STATUS])} 3491@item @code{STATUS = CHMOD(NAME, MODE)} 3492@end multitable 3493 3494@item @emph{Arguments}: 3495@multitable @columnfractions .15 .70 3496 3497@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 3498file name. Trailing blanks are ignored unless the character 3499@code{achar(0)} is present, then all characters up to and excluding 3500@code{achar(0)} are used as the file name. 3501 3502@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the 3503file permission. @var{MODE} uses the same syntax as the @code{chmod} utility 3504as defined by the POSIX standard. The argument shall either be a string of 3505a nonnegative octal number or a symbolic mode. 3506 3507@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is 3508@code{0} on success and nonzero otherwise. 3509@end multitable 3510 3511@item @emph{Return value}: 3512In either syntax, @var{STATUS} is set to @code{0} on success and nonzero 3513otherwise. 3514 3515@item @emph{Example}: 3516@code{CHMOD} as subroutine 3517@smallexample 3518program chmod_test 3519 implicit none 3520 integer :: status 3521 call chmod('test.dat','u+x',status) 3522 print *, 'Status: ', status 3523end program chmod_test 3524@end smallexample 3525@code{CHMOD} as function: 3526@smallexample 3527program chmod_test 3528 implicit none 3529 integer :: status 3530 status = chmod('test.dat','u+x') 3531 print *, 'Status: ', status 3532end program chmod_test 3533@end smallexample 3534 3535@end table 3536 3537 3538 3539@node CMPLX 3540@section @code{CMPLX} --- Complex conversion function 3541@fnindex CMPLX 3542@cindex complex numbers, conversion to 3543@cindex conversion, to complex 3544 3545@table @asis 3546@item @emph{Description}: 3547@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to 3548the real component. If @var{Y} is present it is converted to the imaginary 3549component. If @var{Y} is not present then the imaginary component is set to 35500.0. If @var{X} is complex then @var{Y} must not be present. 3551 3552@item @emph{Standard}: 3553Fortran 77 and later 3554 3555@item @emph{Class}: 3556Elemental function 3557 3558@item @emph{Syntax}: 3559@code{RESULT = CMPLX(X [, Y [, KIND]])} 3560 3561@item @emph{Arguments}: 3562@multitable @columnfractions .15 .70 3563@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 3564or @code{COMPLEX}. 3565@item @var{Y} @tab (Optional; only allowed if @var{X} is not 3566@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. 3567@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3568expression indicating the kind parameter of the result. 3569@end multitable 3570 3571@item @emph{Return value}: 3572The return value is of @code{COMPLEX} type, with a kind equal to 3573@var{KIND} if it is specified. If @var{KIND} is not specified, the 3574result is of the default @code{COMPLEX} kind, regardless of the kinds of 3575@var{X} and @var{Y}. 3576 3577@item @emph{Example}: 3578@smallexample 3579program test_cmplx 3580 integer :: i = 42 3581 real :: x = 3.14 3582 complex :: z 3583 z = cmplx(i, x) 3584 print *, z, cmplx(x) 3585end program test_cmplx 3586@end smallexample 3587 3588@item @emph{See also}: 3589@ref{COMPLEX} 3590@end table 3591 3592 3593 3594@node CO_BROADCAST 3595@section @code{CO_BROADCAST} --- Copy a value to all images the current set of images 3596@fnindex CO_BROADCAST 3597@cindex Collectives, value broadcasting 3598 3599@table @asis 3600@item @emph{Description}: 3601@code{CO_BROADCAST} copies the value of argument @var{A} on the image with 3602image index @code{SOURCE_IMAGE} to all images in the current team. @var{A} 3603becomes defined as if by intrinsic assignment. If the execution was 3604successful and @var{STAT} is present, it is assigned the value zero. If the 3605execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3606@var{ERRMSG} gets assigned a value describing the occurred error. 3607 3608@item @emph{Standard}: 3609Technical Specification (TS) 18508 or later 3610 3611@item @emph{Class}: 3612Collective subroutine 3613 3614@item @emph{Syntax}: 3615@code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])} 3616 3617@item @emph{Arguments}: 3618@multitable @columnfractions .15 .70 3619@item @var{A} @tab INTENT(INOUT) argument; shall have the same 3620dynamic type and type paramters on all images of the current team. If it 3621is an array, it shall have the same shape on all images. 3622@item @var{SOURCE_IMAGE} @tab a scalar integer expression. 3623It shall have the same the same value on all images and refer to an 3624image of the current team. 3625@item @var{STAT} @tab (optional) a scalar integer variable 3626@item @var{ERRMSG} @tab (optional) a scalar character variable 3627@end multitable 3628 3629@item @emph{Example}: 3630@smallexample 3631program test 3632 integer :: val(3) 3633 if (this_image() == 1) then 3634 val = [1, 5, 3] 3635 end if 3636 call co_broadcast (val, source_image=1) 3637 print *, this_image, ":", val 3638end program test 3639@end smallexample 3640 3641@item @emph{See also}: 3642@ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE} 3643@end table 3644 3645 3646 3647@node CO_MAX 3648@section @code{CO_MAX} --- Maximal value on the current set of images 3649@fnindex CO_MAX 3650@cindex Collectives, maximal value 3651 3652@table @asis 3653@item @emph{Description}: 3654@code{CO_MAX} determines element-wise the maximal value of @var{A} on all 3655images of the current team. If @var{RESULT_IMAGE} is present, the maximum 3656values are returned in @var{A} on the specified image only and the value 3657of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3658not present, the value is returned on all images. If the execution was 3659successful and @var{STAT} is present, it is assigned the value zero. If the 3660execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3661@var{ERRMSG} gets assigned a value describing the occurred error. 3662 3663@item @emph{Standard}: 3664Technical Specification (TS) 18508 or later 3665 3666@item @emph{Class}: 3667Collective subroutine 3668 3669@item @emph{Syntax}: 3670@code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])} 3671 3672@item @emph{Arguments}: 3673@multitable @columnfractions .15 .70 3674@item @var{A} @tab shall be an integer, real or character variable, 3675which has the same type and type parameters on all images of the team. 3676@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3677present, it shall have the same the same value on all images and refer to an 3678image of the current team. 3679@item @var{STAT} @tab (optional) a scalar integer variable 3680@item @var{ERRMSG} @tab (optional) a scalar character variable 3681@end multitable 3682 3683@item @emph{Example}: 3684@smallexample 3685program test 3686 integer :: val 3687 val = this_image () 3688 call co_max (val, result_image=1) 3689 if (this_image() == 1) then 3690 write(*,*) "Maximal value", val ! prints num_images() 3691 end if 3692end program test 3693@end smallexample 3694 3695@item @emph{See also}: 3696@ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3697@end table 3698 3699 3700 3701@node CO_MIN 3702@section @code{CO_MIN} --- Minimal value on the current set of images 3703@fnindex CO_MIN 3704@cindex Collectives, minimal value 3705 3706@table @asis 3707@item @emph{Description}: 3708@code{CO_MIN} determines element-wise the minimal value of @var{A} on all 3709images of the current team. If @var{RESULT_IMAGE} is present, the minimal 3710values are returned in @var{A} on the specified image only and the value 3711of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3712not present, the value is returned on all images. If the execution was 3713successful and @var{STAT} is present, it is assigned the value zero. If the 3714execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3715@var{ERRMSG} gets assigned a value describing the occurred error. 3716 3717@item @emph{Standard}: 3718Technical Specification (TS) 18508 or later 3719 3720@item @emph{Class}: 3721Collective subroutine 3722 3723@item @emph{Syntax}: 3724@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3725 3726@item @emph{Arguments}: 3727@multitable @columnfractions .15 .70 3728@item @var{A} @tab shall be an integer, real or character variable, 3729which has the same type and type parameters on all images of the team. 3730@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3731present, it shall have the same the same value on all images and refer to an 3732image of the current team. 3733@item @var{STAT} @tab (optional) a scalar integer variable 3734@item @var{ERRMSG} @tab (optional) a scalar character variable 3735@end multitable 3736 3737@item @emph{Example}: 3738@smallexample 3739program test 3740 integer :: val 3741 val = this_image () 3742 call co_min (val, result_image=1) 3743 if (this_image() == 1) then 3744 write(*,*) "Minimal value", val ! prints 1 3745 end if 3746end program test 3747@end smallexample 3748 3749@item @emph{See also}: 3750@ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3751@end table 3752 3753 3754 3755@node CO_REDUCE 3756@section @code{CO_REDUCE} --- Reduction of values on the current set of images 3757@fnindex CO_REDUCE 3758@cindex Collectives, generic reduction 3759 3760@table @asis 3761@item @emph{Description}: 3762@code{CO_REDUCE} determines element-wise the reduction of the value of @var{A} 3763on all images of the current team. The pure function passed as @var{OPERATOR} 3764is used to pairwise reduce the values of @var{A} by passing either the value 3765of @var{A} of different images or the result values of such a reduction as 3766argument. If @var{A} is an array, the deduction is done element wise. If 3767@var{RESULT_IMAGE} is present, the result values are returned in @var{A} on 3768the specified image only and the value of @var{A} on the other images become 3769undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all 3770images. If the execution was successful and @var{STAT} is present, it is 3771assigned the value zero. If the execution failed, @var{STAT} gets assigned 3772a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing 3773the occurred error. 3774 3775@item @emph{Standard}: 3776Technical Specification (TS) 18508 or later 3777 3778@item @emph{Class}: 3779Collective subroutine 3780 3781@item @emph{Syntax}: 3782@code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])} 3783 3784@item @emph{Arguments}: 3785@multitable @columnfractions .15 .70 3786@item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be 3787nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, 3788it shall be associated. @var{A} shall have the same type and type parameters on 3789all images of the team; if it is an array, it shall have the same shape on all 3790images. 3791@item @var{OPERATOR} @tab pure function with two scalar nonallocatable 3792arguments, which shall be nonpolymorphic and have the same type and type 3793parameters as @var{A}. The function shall return a nonallocatable scalar of 3794the same type and type parameters as @var{A}. The function shall be the same on 3795all images and with regards to the arguments mathematically commutative and 3796associative. Note that @var{OPERATOR} may not be an elemental function, unless 3797it is an intrisic function. 3798@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3799present, it shall have the same the same value on all images and refer to an 3800image of the current team. 3801@item @var{STAT} @tab (optional) a scalar integer variable 3802@item @var{ERRMSG} @tab (optional) a scalar character variable 3803@end multitable 3804 3805@item @emph{Example}: 3806@smallexample 3807program test 3808 integer :: val 3809 val = this_image () 3810 call co_reduce (val, result_image=1, operator=myprod) 3811 if (this_image() == 1) then 3812 write(*,*) "Product value", val ! prints num_images() factorial 3813 end if 3814contains 3815 pure function myprod(a, b) 3816 integer, value :: a, b 3817 integer :: myprod 3818 myprod = a * b 3819 end function myprod 3820end program test 3821@end smallexample 3822 3823@item @emph{Note}: 3824While the rules permit in principle an intrinsic function, none of the 3825intrinsics in the standard fulfill the criteria of having a specific 3826function, which takes two arguments of the same type and returning that 3827type as result. 3828 3829@item @emph{See also}: 3830@ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST} 3831@end table 3832 3833 3834 3835@node CO_SUM 3836@section @code{CO_SUM} --- Sum of values on the current set of images 3837@fnindex CO_SUM 3838@cindex Collectives, sum of values 3839 3840@table @asis 3841@item @emph{Description}: 3842@code{CO_SUM} sums up the values of each element of @var{A} on all 3843images of the current team. If @var{RESULT_IMAGE} is present, the summed-up 3844values are returned in @var{A} on the specified image only and the value 3845of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3846not present, the value is returned on all images. If the execution was 3847successful and @var{STAT} is present, it is assigned the value zero. If the 3848execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3849@var{ERRMSG} gets assigned a value describing the occurred error. 3850 3851@item @emph{Standard}: 3852Technical Specification (TS) 18508 or later 3853 3854@item @emph{Class}: 3855Collective subroutine 3856 3857@item @emph{Syntax}: 3858@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3859 3860@item @emph{Arguments}: 3861@multitable @columnfractions .15 .70 3862@item @var{A} @tab shall be an integer, real or complex variable, 3863which has the same type and type parameters on all images of the team. 3864@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3865present, it shall have the same the same value on all images and refer to an 3866image of the current team. 3867@item @var{STAT} @tab (optional) a scalar integer variable 3868@item @var{ERRMSG} @tab (optional) a scalar character variable 3869@end multitable 3870 3871@item @emph{Example}: 3872@smallexample 3873program test 3874 integer :: val 3875 val = this_image () 3876 call co_sum (val, result_image=1) 3877 if (this_image() == 1) then 3878 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images() 3879 end if 3880end program test 3881@end smallexample 3882 3883@item @emph{See also}: 3884@ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3885@end table 3886 3887 3888 3889@node COMMAND_ARGUMENT_COUNT 3890@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments 3891@fnindex COMMAND_ARGUMENT_COUNT 3892@cindex command-line arguments 3893@cindex command-line arguments, number of 3894@cindex arguments, to program 3895 3896@table @asis 3897@item @emph{Description}: 3898@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the 3899command line when the containing program was invoked. 3900 3901@item @emph{Standard}: 3902Fortran 2003 and later 3903 3904@item @emph{Class}: 3905Inquiry function 3906 3907@item @emph{Syntax}: 3908@code{RESULT = COMMAND_ARGUMENT_COUNT()} 3909 3910@item @emph{Arguments}: 3911@multitable @columnfractions .15 .70 3912@item None 3913@end multitable 3914 3915@item @emph{Return value}: 3916The return value is an @code{INTEGER} of default kind. 3917 3918@item @emph{Example}: 3919@smallexample 3920program test_command_argument_count 3921 integer :: count 3922 count = command_argument_count() 3923 print *, count 3924end program test_command_argument_count 3925@end smallexample 3926 3927@item @emph{See also}: 3928@ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT} 3929@end table 3930 3931 3932 3933@node COMPILER_OPTIONS 3934@section @code{COMPILER_OPTIONS} --- Options passed to the compiler 3935@fnindex COMPILER_OPTIONS 3936@cindex flags inquiry function 3937@cindex options inquiry function 3938@cindex compiler flags inquiry function 3939 3940@table @asis 3941@item @emph{Description}: 3942@code{COMPILER_OPTIONS} returns a string with the options used for 3943compiling. 3944 3945@item @emph{Standard}: 3946Fortran 2008 3947 3948@item @emph{Class}: 3949Inquiry function of the module @code{ISO_FORTRAN_ENV} 3950 3951@item @emph{Syntax}: 3952@code{STR = COMPILER_OPTIONS()} 3953 3954@item @emph{Arguments}: 3955None. 3956 3957@item @emph{Return value}: 3958The return value is a default-kind string with system-dependent length. 3959It contains the compiler flags used to compile the file, which called 3960the @code{COMPILER_OPTIONS} intrinsic. 3961 3962@item @emph{Example}: 3963@smallexample 3964 use iso_fortran_env 3965 print '(4a)', 'This file was compiled by ', & 3966 compiler_version(), ' using the options ', & 3967 compiler_options() 3968 end 3969@end smallexample 3970 3971@item @emph{See also}: 3972@ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV} 3973@end table 3974 3975 3976 3977@node COMPILER_VERSION 3978@section @code{COMPILER_VERSION} --- Compiler version string 3979@fnindex COMPILER_VERSION 3980@cindex compiler, name and version 3981@cindex version of the compiler 3982 3983@table @asis 3984@item @emph{Description}: 3985@code{COMPILER_VERSION} returns a string with the name and the 3986version of the compiler. 3987 3988@item @emph{Standard}: 3989Fortran 2008 3990 3991@item @emph{Class}: 3992Inquiry function of the module @code{ISO_FORTRAN_ENV} 3993 3994@item @emph{Syntax}: 3995@code{STR = COMPILER_VERSION()} 3996 3997@item @emph{Arguments}: 3998None. 3999 4000@item @emph{Return value}: 4001The return value is a default-kind string with system-dependent length. 4002It contains the name of the compiler and its version number. 4003 4004@item @emph{Example}: 4005@smallexample 4006 use iso_fortran_env 4007 print '(4a)', 'This file was compiled by ', & 4008 compiler_version(), ' using the options ', & 4009 compiler_options() 4010 end 4011@end smallexample 4012 4013@item @emph{See also}: 4014@ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV} 4015@end table 4016 4017 4018 4019@node COMPLEX 4020@section @code{COMPLEX} --- Complex conversion function 4021@fnindex COMPLEX 4022@cindex complex numbers, conversion to 4023@cindex conversion, to complex 4024 4025@table @asis 4026@item @emph{Description}: 4027@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted 4028to the real component and @var{Y} is converted to the imaginary 4029component. 4030 4031@item @emph{Standard}: 4032GNU extension 4033 4034@item @emph{Class}: 4035Elemental function 4036 4037@item @emph{Syntax}: 4038@code{RESULT = COMPLEX(X, Y)} 4039 4040@item @emph{Arguments}: 4041@multitable @columnfractions .15 .70 4042@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4043@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}. 4044@end multitable 4045 4046@item @emph{Return value}: 4047If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return 4048value is of default @code{COMPLEX} type. 4049 4050If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL} 4051type and one is of @code{INTEGER} type, then the return value is of 4052@code{COMPLEX} type with a kind equal to that of the @code{REAL} 4053argument with the highest precision. 4054 4055@item @emph{Example}: 4056@smallexample 4057program test_complex 4058 integer :: i = 42 4059 real :: x = 3.14 4060 print *, complex(i, x) 4061end program test_complex 4062@end smallexample 4063 4064@item @emph{See also}: 4065@ref{CMPLX} 4066@end table 4067 4068 4069 4070@node CONJG 4071@section @code{CONJG} --- Complex conjugate function 4072@fnindex CONJG 4073@fnindex DCONJG 4074@cindex complex conjugate 4075 4076@table @asis 4077@item @emph{Description}: 4078@code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)} 4079then the result is @code{(x, -y)} 4080 4081@item @emph{Standard}: 4082Fortran 77 and later, has overloads that are GNU extensions 4083 4084@item @emph{Class}: 4085Elemental function 4086 4087@item @emph{Syntax}: 4088@code{Z = CONJG(Z)} 4089 4090@item @emph{Arguments}: 4091@multitable @columnfractions .15 .70 4092@item @var{Z} @tab The type shall be @code{COMPLEX}. 4093@end multitable 4094 4095@item @emph{Return value}: 4096The return value is of type @code{COMPLEX}. 4097 4098@item @emph{Example}: 4099@smallexample 4100program test_conjg 4101 complex :: z = (2.0, 3.0) 4102 complex(8) :: dz = (2.71_8, -3.14_8) 4103 z= conjg(z) 4104 print *, z 4105 dz = dconjg(dz) 4106 print *, dz 4107end program test_conjg 4108@end smallexample 4109 4110@item @emph{Specific names}: 4111@multitable @columnfractions .20 .20 .20 .25 4112@item Name @tab Argument @tab Return type @tab Standard 4113@item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension 4114@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension 4115@end multitable 4116@end table 4117 4118 4119 4120@node COS 4121@section @code{COS} --- Cosine function 4122@fnindex COS 4123@fnindex DCOS 4124@fnindex CCOS 4125@fnindex ZCOS 4126@fnindex CDCOS 4127@cindex trigonometric function, cosine 4128@cindex cosine 4129 4130@table @asis 4131@item @emph{Description}: 4132@code{COS(X)} computes the cosine of @var{X}. 4133 4134@item @emph{Standard}: 4135Fortran 77 and later, has overloads that are GNU extensions 4136 4137@item @emph{Class}: 4138Elemental function 4139 4140@item @emph{Syntax}: 4141@code{RESULT = COS(X)} 4142 4143@item @emph{Arguments}: 4144@multitable @columnfractions .15 .70 4145@item @var{X} @tab The type shall be @code{REAL} or 4146@code{COMPLEX}. 4147@end multitable 4148 4149@item @emph{Return value}: 4150The return value is of the same type and kind as @var{X}. The real part 4151of the result is in radians. If @var{X} is of the type @code{REAL}, 4152the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}. 4153 4154@item @emph{Example}: 4155@smallexample 4156program test_cos 4157 real :: x = 0.0 4158 x = cos(x) 4159end program test_cos 4160@end smallexample 4161 4162@item @emph{Specific names}: 4163@multitable @columnfractions .20 .20 .20 .25 4164@item Name @tab Argument @tab Return type @tab Standard 4165@item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4166@item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4167@item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 4168@item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4169@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4170@end multitable 4171 4172@item @emph{See also}: 4173Inverse function: @ref{ACOS} 4174Degrees function: @ref{COSD} 4175 4176@end table 4177 4178 4179 4180@node COSD 4181@section @code{COSD} --- Cosine function, degrees 4182@fnindex COSD 4183@fnindex DCOSD 4184@fnindex CCOSD 4185@fnindex ZCOSD 4186@fnindex CDCOSD 4187@cindex trigonometric function, cosine, degrees 4188@cindex cosine, degrees 4189 4190@table @asis 4191@item @emph{Description}: 4192@code{COSD(X)} computes the cosine of @var{X} in degrees. 4193 4194This function is for compatibility only and should be avoided in favor of 4195standard constructs wherever possible. 4196 4197@item @emph{Standard}: 4198GNU Extension, enabled with @option{-fdec-math}. 4199 4200@item @emph{Class}: 4201Elemental function 4202 4203@item @emph{Syntax}: 4204@code{RESULT = COSD(X)} 4205 4206@item @emph{Arguments}: 4207@multitable @columnfractions .15 .70 4208@item @var{X} @tab The type shall be @code{REAL} or 4209@code{COMPLEX}. 4210@end multitable 4211 4212@item @emph{Return value}: 4213The return value is of the same type and kind as @var{X}. The real part 4214of the result is in degrees. If @var{X} is of the type @code{REAL}, 4215the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}. 4216 4217@item @emph{Example}: 4218@smallexample 4219program test_cosd 4220 real :: x = 0.0 4221 x = cosd(x) 4222end program test_cosd 4223@end smallexample 4224 4225@item @emph{Specific names}: 4226@multitable @columnfractions .20 .20 .20 .25 4227@item Name @tab Argument @tab Return type @tab Standard 4228@item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 4229@item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 4230@item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension 4231@item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4232@item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 4233@end multitable 4234 4235@item @emph{See also}: 4236Inverse function: @ref{ACOSD} 4237Radians function: @ref{COS} 4238 4239@end table 4240 4241 4242 4243@node COSH 4244@section @code{COSH} --- Hyperbolic cosine function 4245@fnindex COSH 4246@fnindex DCOSH 4247@cindex hyperbolic cosine 4248@cindex hyperbolic function, cosine 4249@cindex cosine, hyperbolic 4250 4251@table @asis 4252@item @emph{Description}: 4253@code{COSH(X)} computes the hyperbolic cosine of @var{X}. 4254 4255@item @emph{Standard}: 4256Fortran 77 and later, for a complex argument Fortran 2008 or later 4257 4258@item @emph{Class}: 4259Elemental function 4260 4261@item @emph{Syntax}: 4262@code{X = COSH(X)} 4263 4264@item @emph{Arguments}: 4265@multitable @columnfractions .15 .70 4266@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4267@end multitable 4268 4269@item @emph{Return value}: 4270The return value has same type and kind as @var{X}. If @var{X} is 4271complex, the imaginary part of the result is in radians. If @var{X} 4272is @code{REAL}, the return value has a lower bound of one, 4273@math{\cosh (x) \geq 1}. 4274 4275@item @emph{Example}: 4276@smallexample 4277program test_cosh 4278 real(8) :: x = 1.0_8 4279 x = cosh(x) 4280end program test_cosh 4281@end smallexample 4282 4283@item @emph{Specific names}: 4284@multitable @columnfractions .20 .20 .20 .25 4285@item Name @tab Argument @tab Return type @tab Standard 4286@item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 4287@item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 4288@end multitable 4289 4290@item @emph{See also}: 4291Inverse function: @ref{ACOSH} 4292 4293@end table 4294 4295 4296 4297@node COTAN 4298@section @code{COTAN} --- Cotangent function 4299@fnindex COTAN 4300@fnindex DCOTAN 4301@cindex trigonometric function, cotangent 4302@cindex cotangent 4303 4304@table @asis 4305@item @emph{Description}: 4306@code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)} 4307divided by @code{SIN(x)}, or @code{1 / TAN(x)}. 4308 4309This function is for compatibility only and should be avoided in favor of 4310standard constructs wherever possible. 4311 4312@item @emph{Standard}: 4313GNU Extension, enabled with @option{-fdec-math}. 4314 4315@item @emph{Class}: 4316Elemental function 4317 4318@item @emph{Syntax}: 4319@code{RESULT = COTAN(X)} 4320 4321@item @emph{Arguments}: 4322@multitable @columnfractions .15 .70 4323@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4324@end multitable 4325 4326@item @emph{Return value}: 4327The return value has same type and kind as @var{X}, and its value is in radians. 4328 4329@item @emph{Example}: 4330@smallexample 4331program test_cotan 4332 real(8) :: x = 0.165_8 4333 x = cotan(x) 4334end program test_cotan 4335@end smallexample 4336 4337@item @emph{Specific names}: 4338@multitable @columnfractions .20 .20 .20 .25 4339@item Name @tab Argument @tab Return type @tab Standard 4340@item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 4341@item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 4342@end multitable 4343 4344@item @emph{See also}: 4345Converse function: @ref{TAN} 4346Degrees function: @ref{COTAND} 4347@end table 4348 4349 4350 4351@node COTAND 4352@section @code{COTAND} --- Cotangent function, degrees 4353@fnindex COTAND 4354@fnindex DCOTAND 4355@cindex trigonometric function, cotangent, degrees 4356@cindex cotangent, degrees 4357 4358@table @asis 4359@item @emph{Description}: 4360@code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to 4361@code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}. 4362 4363@item @emph{Standard}: 4364GNU Extension, enabled with @option{-fdec-math}. 4365 4366This function is for compatibility only and should be avoided in favor of 4367standard constructs wherever possible. 4368 4369@item @emph{Class}: 4370Elemental function 4371 4372@item @emph{Syntax}: 4373@code{RESULT = COTAND(X)} 4374 4375@item @emph{Arguments}: 4376@multitable @columnfractions .15 .70 4377@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 4378@end multitable 4379 4380@item @emph{Return value}: 4381The return value has same type and kind as @var{X}, and its value is in degrees. 4382 4383@item @emph{Example}: 4384@smallexample 4385program test_cotand 4386 real(8) :: x = 0.165_8 4387 x = cotand(x) 4388end program test_cotand 4389@end smallexample 4390 4391@item @emph{Specific names}: 4392@multitable @columnfractions .20 .20 .20 .25 4393@item Name @tab Argument @tab Return type @tab Standard 4394@item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 4395@item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 4396@end multitable 4397 4398@item @emph{See also}: 4399Converse function: @ref{TAND} 4400Radians function: @ref{COTAN} 4401 4402@end table 4403 4404 4405 4406@node COUNT 4407@section @code{COUNT} --- Count function 4408@fnindex COUNT 4409@cindex array, conditionally count elements 4410@cindex array, element counting 4411@cindex array, number of elements 4412 4413@table @asis 4414@item @emph{Description}: 4415 4416Counts the number of @code{.TRUE.} elements in a logical @var{MASK}, 4417or, if the @var{DIM} argument is supplied, counts the number of 4418elements along each row of the array in the @var{DIM} direction. 4419If the array has zero size, or all of the elements of @var{MASK} are 4420@code{.FALSE.}, then the result is @code{0}. 4421 4422@item @emph{Standard}: 4423Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 4424 4425@item @emph{Class}: 4426Transformational function 4427 4428@item @emph{Syntax}: 4429@code{RESULT = COUNT(MASK [, DIM, KIND])} 4430 4431@item @emph{Arguments}: 4432@multitable @columnfractions .15 .70 4433@item @var{MASK} @tab The type shall be @code{LOGICAL}. 4434@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}. 4435@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 4436expression indicating the kind parameter of the result. 4437@end multitable 4438 4439@item @emph{Return value}: 4440The return value is of type @code{INTEGER} and of kind @var{KIND}. If 4441@var{KIND} is absent, the return value is of default integer kind. 4442If @var{DIM} is present, the result is an array with a rank one less 4443than the rank of @var{ARRAY}, and a size corresponding to the shape 4444of @var{ARRAY} with the @var{DIM} dimension removed. 4445 4446@item @emph{Example}: 4447@smallexample 4448program test_count 4449 integer, dimension(2,3) :: a, b 4450 logical, dimension(2,3) :: mask 4451 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) 4452 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /)) 4453 print '(3i3)', a(1,:) 4454 print '(3i3)', a(2,:) 4455 print * 4456 print '(3i3)', b(1,:) 4457 print '(3i3)', b(2,:) 4458 print * 4459 mask = a.ne.b 4460 print '(3l3)', mask(1,:) 4461 print '(3l3)', mask(2,:) 4462 print * 4463 print '(3i3)', count(mask) 4464 print * 4465 print '(3i3)', count(mask, 1) 4466 print * 4467 print '(3i3)', count(mask, 2) 4468end program test_count 4469@end smallexample 4470@end table 4471 4472 4473 4474@node CPU_TIME 4475@section @code{CPU_TIME} --- CPU elapsed time in seconds 4476@fnindex CPU_TIME 4477@cindex time, elapsed 4478 4479@table @asis 4480@item @emph{Description}: 4481Returns a @code{REAL} value representing the elapsed CPU time in 4482seconds. This is useful for testing segments of code to determine 4483execution time. 4484 4485If a time source is available, time will be reported with microsecond 4486resolution. If no time source is available, @var{TIME} is set to 4487@code{-1.0}. 4488 4489Note that @var{TIME} may contain a, system dependent, arbitrary offset 4490and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute 4491value is meaningless, only differences between subsequent calls to 4492this subroutine, as shown in the example below, should be used. 4493 4494 4495@item @emph{Standard}: 4496Fortran 95 and later 4497 4498@item @emph{Class}: 4499Subroutine 4500 4501@item @emph{Syntax}: 4502@code{CALL CPU_TIME(TIME)} 4503 4504@item @emph{Arguments}: 4505@multitable @columnfractions .15 .70 4506@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}. 4507@end multitable 4508 4509@item @emph{Return value}: 4510None 4511 4512@item @emph{Example}: 4513@smallexample 4514program test_cpu_time 4515 real :: start, finish 4516 call cpu_time(start) 4517 ! put code to test here 4518 call cpu_time(finish) 4519 print '("Time = ",f6.3," seconds.")',finish-start 4520end program test_cpu_time 4521@end smallexample 4522 4523@item @emph{See also}: 4524@ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME} 4525@end table 4526 4527 4528 4529@node CSHIFT 4530@section @code{CSHIFT} --- Circular shift elements of an array 4531@fnindex CSHIFT 4532@cindex array, shift circularly 4533@cindex array, permutation 4534@cindex array, rotate 4535 4536@table @asis 4537@item @emph{Description}: 4538@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of 4539@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is 4540taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the 4541range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. 4542If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted 4543by @var{SHIFT} places. If rank is greater than one, then all complete rank one 4544sections of @var{ARRAY} along the given dimension are shifted. Elements 4545shifted out one end of each rank one section are shifted back in the other end. 4546 4547@item @emph{Standard}: 4548Fortran 95 and later 4549 4550@item @emph{Class}: 4551Transformational function 4552 4553@item @emph{Syntax}: 4554@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])} 4555 4556@item @emph{Arguments}: 4557@multitable @columnfractions .15 .70 4558@item @var{ARRAY} @tab Shall be an array of any type. 4559@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 4560@item @var{DIM} @tab The type shall be @code{INTEGER}. 4561@end multitable 4562 4563@item @emph{Return value}: 4564Returns an array of same type and rank as the @var{ARRAY} argument. 4565 4566@item @emph{Example}: 4567@smallexample 4568program test_cshift 4569 integer, dimension(3,3) :: a 4570 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 4571 print '(3i3)', a(1,:) 4572 print '(3i3)', a(2,:) 4573 print '(3i3)', a(3,:) 4574 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2) 4575 print * 4576 print '(3i3)', a(1,:) 4577 print '(3i3)', a(2,:) 4578 print '(3i3)', a(3,:) 4579end program test_cshift 4580@end smallexample 4581@end table 4582 4583 4584 4585@node CTIME 4586@section @code{CTIME} --- Convert a time into a string 4587@fnindex CTIME 4588@cindex time, conversion to string 4589@cindex conversion, to string 4590 4591@table @asis 4592@item @emph{Description}: 4593@code{CTIME} converts a system time value, such as returned by 4594@ref{TIME8}, to a string. The output will be of the form @samp{Sat 4595Aug 19 18:13:14 1995}. 4596 4597This intrinsic is provided in both subroutine and function forms; however, 4598only one form can be used in any given program unit. 4599 4600@item @emph{Standard}: 4601GNU extension 4602 4603@item @emph{Class}: 4604Subroutine, function 4605 4606@item @emph{Syntax}: 4607@multitable @columnfractions .80 4608@item @code{CALL CTIME(TIME, RESULT)}. 4609@item @code{RESULT = CTIME(TIME)}. 4610@end multitable 4611 4612@item @emph{Arguments}: 4613@multitable @columnfractions .15 .70 4614@item @var{TIME} @tab The type shall be of type @code{INTEGER}. 4615@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and 4616of default kind. It is an @code{INTENT(OUT)} argument. If the length 4617of this variable is too short for the time and date string to fit 4618completely, it will be blank on procedure return. 4619@end multitable 4620 4621@item @emph{Return value}: 4622The converted date and time as a string. 4623 4624@item @emph{Example}: 4625@smallexample 4626program test_ctime 4627 integer(8) :: i 4628 character(len=30) :: date 4629 i = time8() 4630 4631 ! Do something, main part of the program 4632 4633 call ctime(i,date) 4634 print *, 'Program was started on ', date 4635end program test_ctime 4636@end smallexample 4637 4638@item @emph{See Also}: 4639@ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} 4640@end table 4641 4642 4643 4644@node DATE_AND_TIME 4645@section @code{DATE_AND_TIME} --- Date and time subroutine 4646@fnindex DATE_AND_TIME 4647@cindex date, current 4648@cindex current date 4649@cindex time, current 4650@cindex current time 4651 4652@table @asis 4653@item @emph{Description}: 4654@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and 4655time information from the real-time system clock. @var{DATE} is 4656@code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and 4657has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, 4658representing the difference with respect to Coordinated Universal Time (UTC). 4659Unavailable time and date parameters return blanks. 4660 4661@var{VALUES} is @code{INTENT(OUT)} and provides the following: 4662 4663@multitable @columnfractions .15 .30 .40 4664@item @tab @code{VALUE(1)}: @tab The year 4665@item @tab @code{VALUE(2)}: @tab The month 4666@item @tab @code{VALUE(3)}: @tab The day of the month 4667@item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes 4668@item @tab @code{VALUE(5)}: @tab The hour of the day 4669@item @tab @code{VALUE(6)}: @tab The minutes of the hour 4670@item @tab @code{VALUE(7)}: @tab The seconds of the minute 4671@item @tab @code{VALUE(8)}: @tab The milliseconds of the second 4672@end multitable 4673 4674@item @emph{Standard}: 4675Fortran 95 and later 4676 4677@item @emph{Class}: 4678Subroutine 4679 4680@item @emph{Syntax}: 4681@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])} 4682 4683@item @emph{Arguments}: 4684@multitable @columnfractions .15 .70 4685@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)} 4686or larger, and of default kind. 4687@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)} 4688or larger, and of default kind. 4689@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)} 4690or larger, and of default kind. 4691@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}. 4692@end multitable 4693 4694@item @emph{Return value}: 4695None 4696 4697@item @emph{Example}: 4698@smallexample 4699program test_time_and_date 4700 character(8) :: date 4701 character(10) :: time 4702 character(5) :: zone 4703 integer,dimension(8) :: values 4704 ! using keyword arguments 4705 call date_and_time(date,time,zone,values) 4706 call date_and_time(DATE=date,ZONE=zone) 4707 call date_and_time(TIME=time) 4708 call date_and_time(VALUES=values) 4709 print '(a,2x,a,2x,a)', date, time, zone 4710 print '(8i5)', values 4711end program test_time_and_date 4712@end smallexample 4713 4714@item @emph{See also}: 4715@ref{CPU_TIME}, @ref{SYSTEM_CLOCK} 4716@end table 4717 4718 4719 4720@node DBLE 4721@section @code{DBLE} --- Double conversion function 4722@fnindex DBLE 4723@cindex conversion, to real 4724 4725@table @asis 4726@item @emph{Description}: 4727@code{DBLE(A)} Converts @var{A} to double precision real type. 4728 4729@item @emph{Standard}: 4730Fortran 77 and later 4731 4732@item @emph{Class}: 4733Elemental function 4734 4735@item @emph{Syntax}: 4736@code{RESULT = DBLE(A)} 4737 4738@item @emph{Arguments}: 4739@multitable @columnfractions .15 .70 4740@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL}, 4741or @code{COMPLEX}. 4742@end multitable 4743 4744@item @emph{Return value}: 4745The return value is of type double precision real. 4746 4747@item @emph{Example}: 4748@smallexample 4749program test_dble 4750 real :: x = 2.18 4751 integer :: i = 5 4752 complex :: z = (2.3,1.14) 4753 print *, dble(x), dble(i), dble(z) 4754end program test_dble 4755@end smallexample 4756 4757@item @emph{See also}: 4758@ref{REAL} 4759@end table 4760 4761 4762 4763@node DCMPLX 4764@section @code{DCMPLX} --- Double complex conversion function 4765@fnindex DCMPLX 4766@cindex complex numbers, conversion to 4767@cindex conversion, to complex 4768 4769@table @asis 4770@item @emph{Description}: 4771@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is 4772converted to the real component. If @var{Y} is present it is converted to the 4773imaginary component. If @var{Y} is not present then the imaginary component is 4774set to 0.0. If @var{X} is complex then @var{Y} must not be present. 4775 4776@item @emph{Standard}: 4777GNU extension 4778 4779@item @emph{Class}: 4780Elemental function 4781 4782@item @emph{Syntax}: 4783@code{RESULT = DCMPLX(X [, Y])} 4784 4785@item @emph{Arguments}: 4786@multitable @columnfractions .15 .70 4787@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 4788or @code{COMPLEX}. 4789@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be 4790@code{INTEGER} or @code{REAL}. 4791@end multitable 4792 4793@item @emph{Return value}: 4794The return value is of type @code{COMPLEX(8)} 4795 4796@item @emph{Example}: 4797@smallexample 4798program test_dcmplx 4799 integer :: i = 42 4800 real :: x = 3.14 4801 complex :: z 4802 z = cmplx(i, x) 4803 print *, dcmplx(i) 4804 print *, dcmplx(x) 4805 print *, dcmplx(z) 4806 print *, dcmplx(x,i) 4807end program test_dcmplx 4808@end smallexample 4809@end table 4810 4811 4812@node DIGITS 4813@section @code{DIGITS} --- Significant binary digits function 4814@fnindex DIGITS 4815@cindex model representation, significant digits 4816 4817@table @asis 4818@item @emph{Description}: 4819@code{DIGITS(X)} returns the number of significant binary digits of the internal 4820model representation of @var{X}. For example, on a system using a 32-bit 4821floating point representation, a default real number would likely return 24. 4822 4823@item @emph{Standard}: 4824Fortran 95 and later 4825 4826@item @emph{Class}: 4827Inquiry function 4828 4829@item @emph{Syntax}: 4830@code{RESULT = DIGITS(X)} 4831 4832@item @emph{Arguments}: 4833@multitable @columnfractions .15 .70 4834@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4835@end multitable 4836 4837@item @emph{Return value}: 4838The return value is of type @code{INTEGER}. 4839 4840@item @emph{Example}: 4841@smallexample 4842program test_digits 4843 integer :: i = 12345 4844 real :: x = 3.143 4845 real(8) :: y = 2.33 4846 print *, digits(i) 4847 print *, digits(x) 4848 print *, digits(y) 4849end program test_digits 4850@end smallexample 4851@end table 4852 4853 4854 4855@node DIM 4856@section @code{DIM} --- Positive difference 4857@fnindex DIM 4858@fnindex IDIM 4859@fnindex DDIM 4860@cindex positive difference 4861 4862@table @asis 4863@item @emph{Description}: 4864@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive; 4865otherwise returns zero. 4866 4867@item @emph{Standard}: 4868Fortran 77 and later 4869 4870@item @emph{Class}: 4871Elemental function 4872 4873@item @emph{Syntax}: 4874@code{RESULT = DIM(X, Y)} 4875 4876@item @emph{Arguments}: 4877@multitable @columnfractions .15 .70 4878@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL} 4879@item @var{Y} @tab The type shall be the same type and kind as @var{X}. 4880@end multitable 4881 4882@item @emph{Return value}: 4883The return value is of type @code{INTEGER} or @code{REAL}. 4884 4885@item @emph{Example}: 4886@smallexample 4887program test_dim 4888 integer :: i 4889 real(8) :: x 4890 i = dim(4, 15) 4891 x = dim(4.345_8, 2.111_8) 4892 print *, i 4893 print *, x 4894end program test_dim 4895@end smallexample 4896 4897@item @emph{Specific names}: 4898@multitable @columnfractions .20 .20 .20 .25 4899@item Name @tab Argument @tab Return type @tab Standard 4900@item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 4901@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later 4902@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 4903@end multitable 4904@end table 4905 4906 4907 4908@node DOT_PRODUCT 4909@section @code{DOT_PRODUCT} --- Dot product function 4910@fnindex DOT_PRODUCT 4911@cindex dot product 4912@cindex vector product 4913@cindex product, vector 4914 4915@table @asis 4916@item @emph{Description}: 4917@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication 4918of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be 4919either numeric or logical and must be arrays of rank one and of equal size. If 4920the vectors are @code{INTEGER} or @code{REAL}, the result is 4921@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result 4922is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL}, 4923the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}. 4924 4925@item @emph{Standard}: 4926Fortran 95 and later 4927 4928@item @emph{Class}: 4929Transformational function 4930 4931@item @emph{Syntax}: 4932@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)} 4933 4934@item @emph{Arguments}: 4935@multitable @columnfractions .15 .70 4936@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1. 4937@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. 4938@end multitable 4939 4940@item @emph{Return value}: 4941If the arguments are numeric, the return value is a scalar of numeric type, 4942@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are 4943@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}. 4944 4945@item @emph{Example}: 4946@smallexample 4947program test_dot_prod 4948 integer, dimension(3) :: a, b 4949 a = (/ 1, 2, 3 /) 4950 b = (/ 4, 5, 6 /) 4951 print '(3i3)', a 4952 print * 4953 print '(3i3)', b 4954 print * 4955 print *, dot_product(a,b) 4956end program test_dot_prod 4957@end smallexample 4958@end table 4959 4960 4961 4962@node DPROD 4963@section @code{DPROD} --- Double product function 4964@fnindex DPROD 4965@cindex product, double-precision 4966 4967@table @asis 4968@item @emph{Description}: 4969@code{DPROD(X,Y)} returns the product @code{X*Y}. 4970 4971@item @emph{Standard}: 4972Fortran 77 and later 4973 4974@item @emph{Class}: 4975Elemental function 4976 4977@item @emph{Syntax}: 4978@code{RESULT = DPROD(X, Y)} 4979 4980@item @emph{Arguments}: 4981@multitable @columnfractions .15 .70 4982@item @var{X} @tab The type shall be @code{REAL}. 4983@item @var{Y} @tab The type shall be @code{REAL}. 4984@end multitable 4985 4986@item @emph{Return value}: 4987The return value is of type @code{REAL(8)}. 4988 4989@item @emph{Example}: 4990@smallexample 4991program test_dprod 4992 real :: x = 5.2 4993 real :: y = 2.3 4994 real(8) :: d 4995 d = dprod(x,y) 4996 print *, d 4997end program test_dprod 4998@end smallexample 4999 5000@item @emph{Specific names}: 5001@multitable @columnfractions .20 .20 .20 .25 5002@item Name @tab Argument @tab Return type @tab Standard 5003@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 5004@end multitable 5005 5006@end table 5007 5008 5009@node DREAL 5010@section @code{DREAL} --- Double real part function 5011@fnindex DREAL 5012@cindex complex numbers, real part 5013 5014@table @asis 5015@item @emph{Description}: 5016@code{DREAL(Z)} returns the real part of complex variable @var{Z}. 5017 5018@item @emph{Standard}: 5019GNU extension 5020 5021@item @emph{Class}: 5022Elemental function 5023 5024@item @emph{Syntax}: 5025@code{RESULT = DREAL(A)} 5026 5027@item @emph{Arguments}: 5028@multitable @columnfractions .15 .70 5029@item @var{A} @tab The type shall be @code{COMPLEX(8)}. 5030@end multitable 5031 5032@item @emph{Return value}: 5033The return value is of type @code{REAL(8)}. 5034 5035@item @emph{Example}: 5036@smallexample 5037program test_dreal 5038 complex(8) :: z = (1.3_8,7.2_8) 5039 print *, dreal(z) 5040end program test_dreal 5041@end smallexample 5042 5043@item @emph{See also}: 5044@ref{AIMAG} 5045 5046@end table 5047 5048 5049 5050@node DSHIFTL 5051@section @code{DSHIFTL} --- Combined left shift 5052@fnindex DSHIFTL 5053@cindex left shift, combined 5054@cindex shift, left 5055 5056@table @asis 5057@item @emph{Description}: 5058@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5059rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT} 5060bits of @var{J}, and the remaining bits are the rightmost bits of 5061@var{I}. 5062 5063@item @emph{Standard}: 5064Fortran 2008 and later 5065 5066@item @emph{Class}: 5067Elemental function 5068 5069@item @emph{Syntax}: 5070@code{RESULT = DSHIFTL(I, J, SHIFT)} 5071 5072@item @emph{Arguments}: 5073@multitable @columnfractions .15 .70 5074@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5075@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5076If both @var{I} and @var{J} have integer type, then they shall have 5077the same kind type parameter. @var{I} and @var{J} shall not both be 5078BOZ constants. 5079@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5080be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5081shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5082@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5083@end multitable 5084 5085@item @emph{Return value}: 5086If either @var{I} or @var{J} is a BOZ constant, it is first converted 5087as if by the intrinsic function @code{INT} to an integer type with the 5088kind type parameter of the other. 5089 5090@item @emph{See also}: 5091@ref{DSHIFTR} 5092@end table 5093 5094 5095@node DSHIFTR 5096@section @code{DSHIFTR} --- Combined right shift 5097@fnindex DSHIFTR 5098@cindex right shift, combined 5099@cindex shift, right 5100 5101@table @asis 5102@item @emph{Description}: 5103@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 5104leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT} 5105bits of @var{I}, and the remaining bits are the leftmost bits of 5106@var{J}. 5107 5108@item @emph{Standard}: 5109Fortran 2008 and later 5110 5111@item @emph{Class}: 5112Elemental function 5113 5114@item @emph{Syntax}: 5115@code{RESULT = DSHIFTR(I, J, SHIFT)} 5116 5117@item @emph{Arguments}: 5118@multitable @columnfractions .15 .70 5119@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5120@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 5121If both @var{I} and @var{J} have integer type, then they shall have 5122the same kind type parameter. @var{I} and @var{J} shall not both be 5123BOZ constants. 5124@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 5125be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 5126shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 5127@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 5128@end multitable 5129 5130@item @emph{Return value}: 5131If either @var{I} or @var{J} is a BOZ constant, it is first converted 5132as if by the intrinsic function @code{INT} to an integer type with the 5133kind type parameter of the other. 5134 5135@item @emph{See also}: 5136@ref{DSHIFTL} 5137@end table 5138 5139 5140@node DTIME 5141@section @code{DTIME} --- Execution time subroutine (or function) 5142@fnindex DTIME 5143@cindex time, elapsed 5144@cindex elapsed time 5145 5146@table @asis 5147@item @emph{Description}: 5148@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime 5149since the start of the process's execution in @var{TIME}. @var{VALUES} 5150returns the user and system components of this time in @code{VALUES(1)} and 5151@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + 5152VALUES(2)}. 5153 5154Subsequent invocations of @code{DTIME} return values accumulated since the 5155previous invocation. 5156 5157On some systems, the underlying timings are represented using types with 5158sufficiently small limits that overflows (wrap around) are possible, such as 515932-bit types. Therefore, the values returned by this intrinsic might be, or 5160become, negative, or numerically less than previous values, during a single 5161run of the compiled program. 5162 5163Please note, that this implementation is thread safe if used within OpenMP 5164directives, i.e., its state will be consistent while called from multiple 5165threads. However, if @code{DTIME} is called from multiple threads, the result 5166is still the time since the last invocation. This may not give the intended 5167results. If possible, use @code{CPU_TIME} instead. 5168 5169This intrinsic is provided in both subroutine and function forms; however, 5170only one form can be used in any given program unit. 5171 5172@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5173 5174@multitable @columnfractions .15 .30 .40 5175@item @tab @code{VALUES(1)}: @tab User time in seconds. 5176@item @tab @code{VALUES(2)}: @tab System time in seconds. 5177@item @tab @code{TIME}: @tab Run time since start in seconds. 5178@end multitable 5179 5180@item @emph{Standard}: 5181GNU extension 5182 5183@item @emph{Class}: 5184Subroutine, function 5185 5186@item @emph{Syntax}: 5187@multitable @columnfractions .80 5188@item @code{CALL DTIME(VALUES, TIME)}. 5189@item @code{TIME = DTIME(VALUES)}, (not recommended). 5190@end multitable 5191 5192@item @emph{Arguments}: 5193@multitable @columnfractions .15 .70 5194@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5195@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5196@end multitable 5197 5198@item @emph{Return value}: 5199Elapsed time in seconds since the last invocation or since the start of program 5200execution if not called before. 5201 5202@item @emph{Example}: 5203@smallexample 5204program test_dtime 5205 integer(8) :: i, j 5206 real, dimension(2) :: tarray 5207 real :: result 5208 call dtime(tarray, result) 5209 print *, result 5210 print *, tarray(1) 5211 print *, tarray(2) 5212 do i=1,100000000 ! Just a delay 5213 j = i * i - i 5214 end do 5215 call dtime(tarray, result) 5216 print *, result 5217 print *, tarray(1) 5218 print *, tarray(2) 5219end program test_dtime 5220@end smallexample 5221 5222@item @emph{See also}: 5223@ref{CPU_TIME} 5224 5225@end table 5226 5227 5228 5229@node EOSHIFT 5230@section @code{EOSHIFT} --- End-off shift elements of an array 5231@fnindex EOSHIFT 5232@cindex array, shift 5233 5234@table @asis 5235@item @emph{Description}: 5236@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on 5237elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is 5238omitted it is taken to be @code{1}. @var{DIM} is a scalar of type 5239@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the 5240rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of 5241@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, 5242then all complete rank one sections of @var{ARRAY} along the given dimension are 5243shifted. Elements shifted out one end of each rank one section are dropped. If 5244@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY} 5245is copied back in the other end. If @var{BOUNDARY} is not present then the 5246following are copied in depending on the type of @var{ARRAY}. 5247 5248@multitable @columnfractions .15 .80 5249@item @emph{Array Type} @tab @emph{Boundary Value} 5250@item Numeric @tab 0 of the type and kind of @var{ARRAY}. 5251@item Logical @tab @code{.FALSE.}. 5252@item Character(@var{len}) @tab @var{len} blanks. 5253@end multitable 5254 5255@item @emph{Standard}: 5256Fortran 95 and later 5257 5258@item @emph{Class}: 5259Transformational function 5260 5261@item @emph{Syntax}: 5262@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])} 5263 5264@item @emph{Arguments}: 5265@multitable @columnfractions .15 .70 5266@item @var{ARRAY} @tab May be any type, not scalar. 5267@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 5268@item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 5269@item @var{DIM} @tab The type shall be @code{INTEGER}. 5270@end multitable 5271 5272@item @emph{Return value}: 5273Returns an array of same type and rank as the @var{ARRAY} argument. 5274 5275@item @emph{Example}: 5276@smallexample 5277program test_eoshift 5278 integer, dimension(3,3) :: a 5279 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 5280 print '(3i3)', a(1,:) 5281 print '(3i3)', a(2,:) 5282 print '(3i3)', a(3,:) 5283 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) 5284 print * 5285 print '(3i3)', a(1,:) 5286 print '(3i3)', a(2,:) 5287 print '(3i3)', a(3,:) 5288end program test_eoshift 5289@end smallexample 5290@end table 5291 5292 5293 5294@node EPSILON 5295@section @code{EPSILON} --- Epsilon function 5296@fnindex EPSILON 5297@cindex model representation, epsilon 5298 5299@table @asis 5300@item @emph{Description}: 5301@code{EPSILON(X)} returns the smallest number @var{E} of the same kind 5302as @var{X} such that @math{1 + E > 1}. 5303 5304@item @emph{Standard}: 5305Fortran 95 and later 5306 5307@item @emph{Class}: 5308Inquiry function 5309 5310@item @emph{Syntax}: 5311@code{RESULT = EPSILON(X)} 5312 5313@item @emph{Arguments}: 5314@multitable @columnfractions .15 .70 5315@item @var{X} @tab The type shall be @code{REAL}. 5316@end multitable 5317 5318@item @emph{Return value}: 5319The return value is of same type as the argument. 5320 5321@item @emph{Example}: 5322@smallexample 5323program test_epsilon 5324 real :: x = 3.143 5325 real(8) :: y = 2.33 5326 print *, EPSILON(x) 5327 print *, EPSILON(y) 5328end program test_epsilon 5329@end smallexample 5330@end table 5331 5332 5333 5334@node ERF 5335@section @code{ERF} --- Error function 5336@fnindex ERF 5337@cindex error function 5338 5339@table @asis 5340@item @emph{Description}: 5341@code{ERF(X)} computes the error function of @var{X}. 5342 5343@item @emph{Standard}: 5344Fortran 2008 and later 5345 5346@item @emph{Class}: 5347Elemental function 5348 5349@item @emph{Syntax}: 5350@code{RESULT = ERF(X)} 5351 5352@item @emph{Arguments}: 5353@multitable @columnfractions .15 .70 5354@item @var{X} @tab The type shall be @code{REAL}. 5355@end multitable 5356 5357@item @emph{Return value}: 5358The return value is of type @code{REAL}, of the same kind as 5359@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }. 5360 5361@item @emph{Example}: 5362@smallexample 5363program test_erf 5364 real(8) :: x = 0.17_8 5365 x = erf(x) 5366end program test_erf 5367@end smallexample 5368 5369@item @emph{Specific names}: 5370@multitable @columnfractions .20 .20 .20 .25 5371@item Name @tab Argument @tab Return type @tab Standard 5372@item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5373@end multitable 5374@end table 5375 5376 5377 5378@node ERFC 5379@section @code{ERFC} --- Error function 5380@fnindex ERFC 5381@cindex error function, complementary 5382 5383@table @asis 5384@item @emph{Description}: 5385@code{ERFC(X)} computes the complementary error function of @var{X}. 5386 5387@item @emph{Standard}: 5388Fortran 2008 and later 5389 5390@item @emph{Class}: 5391Elemental function 5392 5393@item @emph{Syntax}: 5394@code{RESULT = ERFC(X)} 5395 5396@item @emph{Arguments}: 5397@multitable @columnfractions .15 .70 5398@item @var{X} @tab The type shall be @code{REAL}. 5399@end multitable 5400 5401@item @emph{Return value}: 5402The return value is of type @code{REAL} and of the same kind as @var{X}. 5403It lies in the range @math{ 0 \leq erfc (x) \leq 2 }. 5404 5405@item @emph{Example}: 5406@smallexample 5407program test_erfc 5408 real(8) :: x = 0.17_8 5409 x = erfc(x) 5410end program test_erfc 5411@end smallexample 5412 5413@item @emph{Specific names}: 5414@multitable @columnfractions .20 .20 .20 .25 5415@item Name @tab Argument @tab Return type @tab Standard 5416@item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 5417@end multitable 5418@end table 5419 5420 5421 5422@node ERFC_SCALED 5423@section @code{ERFC_SCALED} --- Error function 5424@fnindex ERFC_SCALED 5425@cindex error function, complementary, exponentially-scaled 5426 5427@table @asis 5428@item @emph{Description}: 5429@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary 5430error function of @var{X}. 5431 5432@item @emph{Standard}: 5433Fortran 2008 and later 5434 5435@item @emph{Class}: 5436Elemental function 5437 5438@item @emph{Syntax}: 5439@code{RESULT = ERFC_SCALED(X)} 5440 5441@item @emph{Arguments}: 5442@multitable @columnfractions .15 .70 5443@item @var{X} @tab The type shall be @code{REAL}. 5444@end multitable 5445 5446@item @emph{Return value}: 5447The return value is of type @code{REAL} and of the same kind as @var{X}. 5448 5449@item @emph{Example}: 5450@smallexample 5451program test_erfc_scaled 5452 real(8) :: x = 0.17_8 5453 x = erfc_scaled(x) 5454end program test_erfc_scaled 5455@end smallexample 5456@end table 5457 5458 5459 5460@node ETIME 5461@section @code{ETIME} --- Execution time subroutine (or function) 5462@fnindex ETIME 5463@cindex time, elapsed 5464 5465@table @asis 5466@item @emph{Description}: 5467@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime 5468since the start of the process's execution in @var{TIME}. @var{VALUES} 5469returns the user and system components of this time in @code{VALUES(1)} and 5470@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. 5471 5472On some systems, the underlying timings are represented using types with 5473sufficiently small limits that overflows (wrap around) are possible, such as 547432-bit types. Therefore, the values returned by this intrinsic might be, or 5475become, negative, or numerically less than previous values, during a single 5476run of the compiled program. 5477 5478This intrinsic is provided in both subroutine and function forms; however, 5479only one form can be used in any given program unit. 5480 5481@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5482 5483@multitable @columnfractions .15 .30 .60 5484@item @tab @code{VALUES(1)}: @tab User time in seconds. 5485@item @tab @code{VALUES(2)}: @tab System time in seconds. 5486@item @tab @code{TIME}: @tab Run time since start in seconds. 5487@end multitable 5488 5489@item @emph{Standard}: 5490GNU extension 5491 5492@item @emph{Class}: 5493Subroutine, function 5494 5495@item @emph{Syntax}: 5496@multitable @columnfractions .80 5497@item @code{CALL ETIME(VALUES, TIME)}. 5498@item @code{TIME = ETIME(VALUES)}, (not recommended). 5499@end multitable 5500 5501@item @emph{Arguments}: 5502@multitable @columnfractions .15 .70 5503@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5504@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5505@end multitable 5506 5507@item @emph{Return value}: 5508Elapsed time in seconds since the start of program execution. 5509 5510@item @emph{Example}: 5511@smallexample 5512program test_etime 5513 integer(8) :: i, j 5514 real, dimension(2) :: tarray 5515 real :: result 5516 call ETIME(tarray, result) 5517 print *, result 5518 print *, tarray(1) 5519 print *, tarray(2) 5520 do i=1,100000000 ! Just a delay 5521 j = i * i - i 5522 end do 5523 call ETIME(tarray, result) 5524 print *, result 5525 print *, tarray(1) 5526 print *, tarray(2) 5527end program test_etime 5528@end smallexample 5529 5530@item @emph{See also}: 5531@ref{CPU_TIME} 5532 5533@end table 5534 5535 5536 5537@node EVENT_QUERY 5538@section @code{EVENT_QUERY} --- Query whether a coarray event has occurred 5539@fnindex EVENT_QUERY 5540@cindex Events, EVENT_QUERY 5541 5542@table @asis 5543@item @emph{Description}: 5544@code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been 5545posted to the @var{EVENT} variable and not yet been removed by calling 5546@code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful, 5547it is assigned the value 0. If it is present and the invocation has failed, 5548it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}. 5549 5550@item @emph{Standard}: 5551TS 18508 or later 5552 5553@item @emph{Class}: 5554 subroutine 5555 5556@item @emph{Syntax}: 5557@code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])} 5558 5559@item @emph{Arguments}: 5560@multitable @columnfractions .15 .70 5561@item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE}, 5562defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed. 5563@item @var{COUNT} @tab (intent(out))Scalar integer with at least the 5564precision of default integer. 5565@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 5566@end multitable 5567 5568@item @emph{Example}: 5569@smallexample 5570program atomic 5571 use iso_fortran_env 5572 implicit none 5573 type(event_type) :: event_value_has_been_set[*] 5574 integer :: cnt 5575 if (this_image() == 1) then 5576 call event_query (event_value_has_been_set, cnt) 5577 if (cnt > 0) write(*,*) "Value has been set" 5578 elseif (this_image() == 2) then 5579 event post (event_value_has_been_set[1]) 5580 end if 5581end program atomic 5582@end smallexample 5583 5584@end table 5585 5586 5587 5588@node EXECUTE_COMMAND_LINE 5589@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command 5590@fnindex EXECUTE_COMMAND_LINE 5591@cindex system, system call 5592@cindex command line 5593 5594@table @asis 5595@item @emph{Description}: 5596@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or 5597asynchronously. 5598 5599The @code{COMMAND} argument is passed to the shell and executed (The 5600shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.). 5601If @code{WAIT} is present and has the value false, the execution of 5602the command is asynchronous if the system supports it; otherwise, the 5603command is executed synchronously using the C library's @code{system} 5604call. 5605 5606The three last arguments allow the user to get status information. After 5607synchronous execution, @code{EXITSTAT} contains the integer exit code of 5608the command, as returned by @code{system}. @code{CMDSTAT} is set to zero 5609if the command line was executed (whatever its exit status was). 5610@code{CMDMSG} is assigned an error message if an error has occurred. 5611 5612Note that the @code{system} function need not be thread-safe. It is 5613the responsibility of the user to ensure that @code{system} is not 5614called concurrently. 5615 5616For asynchronous execution on supported targets, the POSIX 5617@code{posix_spawn} or @code{fork} functions are used. Also, a signal 5618handler for the @code{SIGCHLD} signal is installed. 5619 5620@item @emph{Standard}: 5621Fortran 2008 and later 5622 5623@item @emph{Class}: 5624Subroutine 5625 5626@item @emph{Syntax}: 5627@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])} 5628 5629@item @emph{Arguments}: 5630@multitable @columnfractions .15 .70 5631@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar. 5632@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar. 5633@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5634default kind. 5635@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5636default kind. 5637@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the 5638default kind. 5639@end multitable 5640 5641@item @emph{Example}: 5642@smallexample 5643program test_exec 5644 integer :: i 5645 5646 call execute_command_line ("external_prog.exe", exitstat=i) 5647 print *, "Exit status of external_prog.exe was ", i 5648 5649 call execute_command_line ("reindex_files.exe", wait=.false.) 5650 print *, "Now reindexing files in the background" 5651 5652end program test_exec 5653@end smallexample 5654 5655 5656@item @emph{Note}: 5657 5658Because this intrinsic is implemented in terms of the @code{system} 5659function call, its behavior with respect to signaling is processor 5660dependent. In particular, on POSIX-compliant systems, the SIGINT and 5661SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As 5662such, if the parent process is terminated, the child process might not be 5663terminated alongside. 5664 5665 5666@item @emph{See also}: 5667@ref{SYSTEM} 5668@end table 5669 5670 5671 5672@node EXIT 5673@section @code{EXIT} --- Exit the program with status. 5674@fnindex EXIT 5675@cindex program termination 5676@cindex terminate program 5677 5678@table @asis 5679@item @emph{Description}: 5680@code{EXIT} causes immediate termination of the program with status. If status 5681is omitted it returns the canonical @emph{success} for the system. All Fortran 5682I/O units are closed. 5683 5684@item @emph{Standard}: 5685GNU extension 5686 5687@item @emph{Class}: 5688Subroutine 5689 5690@item @emph{Syntax}: 5691@code{CALL EXIT([STATUS])} 5692 5693@item @emph{Arguments}: 5694@multitable @columnfractions .15 .70 5695@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind. 5696@end multitable 5697 5698@item @emph{Return value}: 5699@code{STATUS} is passed to the parent process on exit. 5700 5701@item @emph{Example}: 5702@smallexample 5703program test_exit 5704 integer :: STATUS = 0 5705 print *, 'This program is going to exit.' 5706 call EXIT(STATUS) 5707end program test_exit 5708@end smallexample 5709 5710@item @emph{See also}: 5711@ref{ABORT}, @ref{KILL} 5712@end table 5713 5714 5715 5716@node EXP 5717@section @code{EXP} --- Exponential function 5718@fnindex EXP 5719@fnindex DEXP 5720@fnindex CEXP 5721@fnindex ZEXP 5722@fnindex CDEXP 5723@cindex exponential function 5724@cindex logarithm function, inverse 5725 5726@table @asis 5727@item @emph{Description}: 5728@code{EXP(X)} computes the base @math{e} exponential of @var{X}. 5729 5730@item @emph{Standard}: 5731Fortran 77 and later, has overloads that are GNU extensions 5732 5733@item @emph{Class}: 5734Elemental function 5735 5736@item @emph{Syntax}: 5737@code{RESULT = EXP(X)} 5738 5739@item @emph{Arguments}: 5740@multitable @columnfractions .15 .70 5741@item @var{X} @tab The type shall be @code{REAL} or 5742@code{COMPLEX}. 5743@end multitable 5744 5745@item @emph{Return value}: 5746The return value has same type and kind as @var{X}. 5747 5748@item @emph{Example}: 5749@smallexample 5750program test_exp 5751 real :: x = 1.0 5752 x = exp(x) 5753end program test_exp 5754@end smallexample 5755 5756@item @emph{Specific names}: 5757@multitable @columnfractions .20 .20 .20 .25 5758@item Name @tab Argument @tab Return type @tab Standard 5759@item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 5760@item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 5761@item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 5762@item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5763@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5764@end multitable 5765@end table 5766 5767 5768 5769@node EXPONENT 5770@section @code{EXPONENT} --- Exponent function 5771@fnindex EXPONENT 5772@cindex real number, exponent 5773@cindex floating point, exponent 5774 5775@table @asis 5776@item @emph{Description}: 5777@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X} 5778is zero the value returned is zero. 5779 5780@item @emph{Standard}: 5781Fortran 95 and later 5782 5783@item @emph{Class}: 5784Elemental function 5785 5786@item @emph{Syntax}: 5787@code{RESULT = EXPONENT(X)} 5788 5789@item @emph{Arguments}: 5790@multitable @columnfractions .15 .70 5791@item @var{X} @tab The type shall be @code{REAL}. 5792@end multitable 5793 5794@item @emph{Return value}: 5795The return value is of type default @code{INTEGER}. 5796 5797@item @emph{Example}: 5798@smallexample 5799program test_exponent 5800 real :: x = 1.0 5801 integer :: i 5802 i = exponent(x) 5803 print *, i 5804 print *, exponent(0.0) 5805end program test_exponent 5806@end smallexample 5807@end table 5808 5809 5810 5811@node EXTENDS_TYPE_OF 5812@section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension 5813@fnindex EXTENDS_TYPE_OF 5814 5815@table @asis 5816@item @emph{Description}: 5817Query dynamic type for extension. 5818 5819@item @emph{Standard}: 5820Fortran 2003 and later 5821 5822@item @emph{Class}: 5823Inquiry function 5824 5825@item @emph{Syntax}: 5826@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)} 5827 5828@item @emph{Arguments}: 5829@multitable @columnfractions .15 .70 5830@item @var{A} @tab Shall be an object of extensible declared type or 5831unlimited polymorphic. 5832@item @var{MOLD} @tab Shall be an object of extensible declared type or 5833unlimited polymorphic. 5834@end multitable 5835 5836@item @emph{Return value}: 5837The return value is a scalar of type default logical. It is true if and only if 5838the dynamic type of A is an extension type of the dynamic type of MOLD. 5839 5840 5841@item @emph{See also}: 5842@ref{SAME_TYPE_AS} 5843@end table 5844 5845 5846 5847@node FDATE 5848@section @code{FDATE} --- Get the current time as a string 5849@fnindex FDATE 5850@cindex time, current 5851@cindex current time 5852@cindex date, current 5853@cindex current date 5854 5855@table @asis 5856@item @emph{Description}: 5857@code{FDATE(DATE)} returns the current date (using the same format as 5858@ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE, 5859TIME())}. 5860 5861This intrinsic is provided in both subroutine and function forms; however, 5862only one form can be used in any given program unit. 5863 5864@item @emph{Standard}: 5865GNU extension 5866 5867@item @emph{Class}: 5868Subroutine, function 5869 5870@item @emph{Syntax}: 5871@multitable @columnfractions .80 5872@item @code{CALL FDATE(DATE)}. 5873@item @code{DATE = FDATE()}. 5874@end multitable 5875 5876@item @emph{Arguments}: 5877@multitable @columnfractions .15 .70 5878@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the 5879default kind. It is an @code{INTENT(OUT)} argument. If the length of 5880this variable is too short for the date and time string to fit 5881completely, it will be blank on procedure return. 5882@end multitable 5883 5884@item @emph{Return value}: 5885The current date and time as a string. 5886 5887@item @emph{Example}: 5888@smallexample 5889program test_fdate 5890 integer(8) :: i, j 5891 character(len=30) :: date 5892 call fdate(date) 5893 print *, 'Program started on ', date 5894 do i = 1, 100000000 ! Just a delay 5895 j = i * i - i 5896 end do 5897 call fdate(date) 5898 print *, 'Program ended on ', date 5899end program test_fdate 5900@end smallexample 5901 5902@item @emph{See also}: 5903@ref{DATE_AND_TIME}, @ref{CTIME} 5904@end table 5905 5906 5907@node FGET 5908@section @code{FGET} --- Read a single character in stream mode from stdin 5909@fnindex FGET 5910@cindex read character, stream mode 5911@cindex stream mode, read character 5912@cindex file operation, read character 5913 5914@table @asis 5915@item @emph{Description}: 5916Read a single character in stream mode from stdin by bypassing normal 5917formatted output. Stream I/O should not be mixed with normal record-oriented 5918(formatted or unformatted) I/O on the same unit; the results are unpredictable. 5919 5920This intrinsic is provided in both subroutine and function forms; however, 5921only one form can be used in any given program unit. 5922 5923Note that the @code{FGET} intrinsic is provided for backwards compatibility with 5924@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 5925Programmers should consider the use of new stream IO feature in new code 5926for future portability. See also @ref{Fortran 2003 status}. 5927 5928@item @emph{Standard}: 5929GNU extension 5930 5931@item @emph{Class}: 5932Subroutine, function 5933 5934@item @emph{Syntax}: 5935@multitable @columnfractions .80 5936@item @code{CALL FGET(C [, STATUS])} 5937@item @code{STATUS = FGET(C)} 5938@end multitable 5939 5940@item @emph{Arguments}: 5941@multitable @columnfractions .15 .70 5942@item @var{C} @tab The type shall be @code{CHARACTER} and of default 5943kind. 5944@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 5945Returns 0 on success, -1 on end-of-file, and a system specific positive 5946error code otherwise. 5947@end multitable 5948 5949@item @emph{Example}: 5950@smallexample 5951PROGRAM test_fget 5952 INTEGER, PARAMETER :: strlen = 100 5953 INTEGER :: status, i = 1 5954 CHARACTER(len=strlen) :: str = "" 5955 5956 WRITE (*,*) 'Enter text:' 5957 DO 5958 CALL fget(str(i:i), status) 5959 if (status /= 0 .OR. i > strlen) exit 5960 i = i + 1 5961 END DO 5962 WRITE (*,*) TRIM(str) 5963END PROGRAM 5964@end smallexample 5965 5966@item @emph{See also}: 5967@ref{FGETC}, @ref{FPUT}, @ref{FPUTC} 5968@end table 5969 5970 5971 5972@node FGETC 5973@section @code{FGETC} --- Read a single character in stream mode 5974@fnindex FGETC 5975@cindex read character, stream mode 5976@cindex stream mode, read character 5977@cindex file operation, read character 5978 5979@table @asis 5980@item @emph{Description}: 5981Read a single character in stream mode by bypassing normal formatted output. 5982Stream I/O should not be mixed with normal record-oriented (formatted or 5983unformatted) I/O on the same unit; the results are unpredictable. 5984 5985This intrinsic is provided in both subroutine and function forms; however, 5986only one form can be used in any given program unit. 5987 5988Note that the @code{FGET} intrinsic is provided for backwards compatibility 5989with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 5990Programmers should consider the use of new stream IO feature in new code 5991for future portability. See also @ref{Fortran 2003 status}. 5992 5993@item @emph{Standard}: 5994GNU extension 5995 5996@item @emph{Class}: 5997Subroutine, function 5998 5999@item @emph{Syntax}: 6000@multitable @columnfractions .80 6001@item @code{CALL FGETC(UNIT, C [, STATUS])} 6002@item @code{STATUS = FGETC(UNIT, C)} 6003@end multitable 6004 6005@item @emph{Arguments}: 6006@multitable @columnfractions .15 .70 6007@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6008@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6009kind. 6010@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6011Returns 0 on success, -1 on end-of-file and a system specific positive 6012error code otherwise. 6013@end multitable 6014 6015@item @emph{Example}: 6016@smallexample 6017PROGRAM test_fgetc 6018 INTEGER :: fd = 42, status 6019 CHARACTER :: c 6020 6021 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD") 6022 DO 6023 CALL fgetc(fd, c, status) 6024 IF (status /= 0) EXIT 6025 call fput(c) 6026 END DO 6027 CLOSE(UNIT=fd) 6028END PROGRAM 6029@end smallexample 6030 6031@item @emph{See also}: 6032@ref{FGET}, @ref{FPUT}, @ref{FPUTC} 6033@end table 6034 6035@node FINDLOC 6036@section @code{FINDLOC} --- Search an array for a value 6037@fnindex FINDLOC 6038@cindex findloc 6039 6040@table @asis 6041@item @emph{Description}: 6042Determines the location of the element in the array with the value 6043given in the @var{VALUE} argument, or, if the @var{DIM} argument is 6044supplied, determines the locations of the maximum element along each 6045row of the array in the @var{DIM} direction. If @var{MASK} is 6046present, only the elements for which @var{MASK} is @code{.TRUE.} are 6047considered. If more than one element in the array has the value 6048@var{VALUE}, the location returned is that of the first such element 6049in array element order if the @var{BACK} is not present or if it is 6050@code{.FALSE.}. If @var{BACK} is true, the location returned is that 6051of the last such element. If the array has zero size, or all of the 6052elements of @var{MASK} are @code{.FALSE.}, then the result is an array 6053of zeroes. Similarly, if @var{DIM} is supplied and all of the 6054elements of @var{MASK} along a given row are zero, the result value 6055for that row is zero. 6056 6057@item @emph{Standard}: 6058Fortran 2008 and later. 6059 6060@item @emph{Class}: 6061Transformational function 6062 6063@item @emph{Syntax}: 6064@multitable @columnfractions .80 6065@item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])} 6066@item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])} 6067@end multitable 6068 6069@item @emph{Arguments}: 6070@multitable @columnfractions .15 .70 6071@item @var{ARRAY} @tab Shall be an array of intrinsic type. 6072@item @var{VALUE} @tab A scalar of intrinsic type which is in type 6073conformance with @var{ARRAY}. 6074@item @var{DIM} @tab (Optional) Shall be a scalar of type 6075@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 6076inclusive. It may not be an optional dummy argument. 6077@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6078expression indicating the kind parameter of the result. 6079@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 6080@end multitable 6081 6082@item @emph{Return value}: 6083If @var{DIM} is absent, the result is a rank-one array with a length 6084equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 6085is an array with a rank one less than the rank of @var{ARRAY}, and a 6086size corresponding to the size of @var{ARRAY} with the @var{DIM} 6087dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 6088of one, the result is a scalar. If the optional argument @var{KIND} 6089is present, the result is an integer of kind @var{KIND}, otherwise it 6090is of default kind. 6091 6092@item @emph{See also}: 6093@ref{MAXLOC}, @ref{MINLOC} 6094 6095@end table 6096 6097@node FLOOR 6098@section @code{FLOOR} --- Integer floor function 6099@fnindex FLOOR 6100@cindex floor 6101@cindex rounding, floor 6102 6103@table @asis 6104@item @emph{Description}: 6105@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}. 6106 6107@item @emph{Standard}: 6108Fortran 95 and later 6109 6110@item @emph{Class}: 6111Elemental function 6112 6113@item @emph{Syntax}: 6114@code{RESULT = FLOOR(A [, KIND])} 6115 6116@item @emph{Arguments}: 6117@multitable @columnfractions .15 .70 6118@item @var{A} @tab The type shall be @code{REAL}. 6119@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6120expression indicating the kind parameter of the result. 6121@end multitable 6122 6123@item @emph{Return value}: 6124The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 6125and of default-kind @code{INTEGER} otherwise. 6126 6127@item @emph{Example}: 6128@smallexample 6129program test_floor 6130 real :: x = 63.29 6131 real :: y = -63.59 6132 print *, floor(x) ! returns 63 6133 print *, floor(y) ! returns -64 6134end program test_floor 6135@end smallexample 6136 6137@item @emph{See also}: 6138@ref{CEILING}, @ref{NINT} 6139 6140@end table 6141 6142 6143 6144@node FLUSH 6145@section @code{FLUSH} --- Flush I/O unit(s) 6146@fnindex FLUSH 6147@cindex file operation, flush 6148 6149@table @asis 6150@item @emph{Description}: 6151Flushes Fortran unit(s) currently open for output. Without the optional 6152argument, all units are flushed, otherwise just the unit specified. 6153 6154@item @emph{Standard}: 6155GNU extension 6156 6157@item @emph{Class}: 6158Subroutine 6159 6160@item @emph{Syntax}: 6161@code{CALL FLUSH(UNIT)} 6162 6163@item @emph{Arguments}: 6164@multitable @columnfractions .15 .70 6165@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}. 6166@end multitable 6167 6168@item @emph{Note}: 6169Beginning with the Fortran 2003 standard, there is a @code{FLUSH} 6170statement that should be preferred over the @code{FLUSH} intrinsic. 6171 6172The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement 6173have identical effect: they flush the runtime library's I/O buffer so 6174that the data becomes visible to other processes. This does not guarantee 6175that the data is committed to disk. 6176 6177On POSIX systems, you can request that all data is transferred to the 6178storage device by calling the @code{fsync} function, with the POSIX file 6179descriptor of the I/O unit as argument (retrieved with GNU intrinsic 6180@code{FNUM}). The following example shows how: 6181 6182@smallexample 6183 ! Declare the interface for POSIX fsync function 6184 interface 6185 function fsync (fd) bind(c,name="fsync") 6186 use iso_c_binding, only: c_int 6187 integer(c_int), value :: fd 6188 integer(c_int) :: fsync 6189 end function fsync 6190 end interface 6191 6192 ! Variable declaration 6193 integer :: ret 6194 6195 ! Opening unit 10 6196 open (10,file="foo") 6197 6198 ! ... 6199 ! Perform I/O on unit 10 6200 ! ... 6201 6202 ! Flush and sync 6203 flush(10) 6204 ret = fsync(fnum(10)) 6205 6206 ! Handle possible error 6207 if (ret /= 0) stop "Error calling FSYNC" 6208@end smallexample 6209 6210@end table 6211 6212 6213 6214@node FNUM 6215@section @code{FNUM} --- File number function 6216@fnindex FNUM 6217@cindex file operation, file number 6218 6219@table @asis 6220@item @emph{Description}: 6221@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the 6222open Fortran I/O unit @code{UNIT}. 6223 6224@item @emph{Standard}: 6225GNU extension 6226 6227@item @emph{Class}: 6228Function 6229 6230@item @emph{Syntax}: 6231@code{RESULT = FNUM(UNIT)} 6232 6233@item @emph{Arguments}: 6234@multitable @columnfractions .15 .70 6235@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6236@end multitable 6237 6238@item @emph{Return value}: 6239The return value is of type @code{INTEGER} 6240 6241@item @emph{Example}: 6242@smallexample 6243program test_fnum 6244 integer :: i 6245 open (unit=10, status = "scratch") 6246 i = fnum(10) 6247 print *, i 6248 close (10) 6249end program test_fnum 6250@end smallexample 6251@end table 6252 6253 6254 6255@node FPUT 6256@section @code{FPUT} --- Write a single character in stream mode to stdout 6257@fnindex FPUT 6258@cindex write character, stream mode 6259@cindex stream mode, write character 6260@cindex file operation, write character 6261 6262@table @asis 6263@item @emph{Description}: 6264Write a single character in stream mode to stdout by bypassing normal 6265formatted output. Stream I/O should not be mixed with normal record-oriented 6266(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6267 6268This intrinsic is provided in both subroutine and function forms; however, 6269only one form can be used in any given program unit. 6270 6271Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6272@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6273Programmers should consider the use of new stream IO feature in new code 6274for future portability. See also @ref{Fortran 2003 status}. 6275 6276@item @emph{Standard}: 6277GNU extension 6278 6279@item @emph{Class}: 6280Subroutine, function 6281 6282@item @emph{Syntax}: 6283@multitable @columnfractions .80 6284@item @code{CALL FPUT(C [, STATUS])} 6285@item @code{STATUS = FPUT(C)} 6286@end multitable 6287 6288@item @emph{Arguments}: 6289@multitable @columnfractions .15 .70 6290@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6291kind. 6292@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6293Returns 0 on success, -1 on end-of-file and a system specific positive 6294error code otherwise. 6295@end multitable 6296 6297@item @emph{Example}: 6298@smallexample 6299PROGRAM test_fput 6300 CHARACTER(len=10) :: str = "gfortran" 6301 INTEGER :: i 6302 DO i = 1, len_trim(str) 6303 CALL fput(str(i:i)) 6304 END DO 6305END PROGRAM 6306@end smallexample 6307 6308@item @emph{See also}: 6309@ref{FPUTC}, @ref{FGET}, @ref{FGETC} 6310@end table 6311 6312 6313 6314@node FPUTC 6315@section @code{FPUTC} --- Write a single character in stream mode 6316@fnindex FPUTC 6317@cindex write character, stream mode 6318@cindex stream mode, write character 6319@cindex file operation, write character 6320 6321@table @asis 6322@item @emph{Description}: 6323Write a single character in stream mode by bypassing normal formatted 6324output. Stream I/O should not be mixed with normal record-oriented 6325(formatted or unformatted) I/O on the same unit; the results are unpredictable. 6326 6327This intrinsic is provided in both subroutine and function forms; however, 6328only one form can be used in any given program unit. 6329 6330Note that the @code{FGET} intrinsic is provided for backwards compatibility with 6331@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 6332Programmers should consider the use of new stream IO feature in new code 6333for future portability. See also @ref{Fortran 2003 status}. 6334 6335@item @emph{Standard}: 6336GNU extension 6337 6338@item @emph{Class}: 6339Subroutine, function 6340 6341@item @emph{Syntax}: 6342@multitable @columnfractions .80 6343@item @code{CALL FPUTC(UNIT, C [, STATUS])} 6344@item @code{STATUS = FPUTC(UNIT, C)} 6345@end multitable 6346 6347@item @emph{Arguments}: 6348@multitable @columnfractions .15 .70 6349@item @var{UNIT} @tab The type shall be @code{INTEGER}. 6350@item @var{C} @tab The type shall be @code{CHARACTER} and of default 6351kind. 6352@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6353Returns 0 on success, -1 on end-of-file and a system specific positive 6354error code otherwise. 6355@end multitable 6356 6357@item @emph{Example}: 6358@smallexample 6359PROGRAM test_fputc 6360 CHARACTER(len=10) :: str = "gfortran" 6361 INTEGER :: fd = 42, i 6362 6363 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW") 6364 DO i = 1, len_trim(str) 6365 CALL fputc(fd, str(i:i)) 6366 END DO 6367 CLOSE(fd) 6368END PROGRAM 6369@end smallexample 6370 6371@item @emph{See also}: 6372@ref{FPUT}, @ref{FGET}, @ref{FGETC} 6373@end table 6374 6375 6376 6377@node FRACTION 6378@section @code{FRACTION} --- Fractional part of the model representation 6379@fnindex FRACTION 6380@cindex real number, fraction 6381@cindex floating point, fraction 6382 6383@table @asis 6384@item @emph{Description}: 6385@code{FRACTION(X)} returns the fractional part of the model 6386representation of @code{X}. 6387 6388@item @emph{Standard}: 6389Fortran 95 and later 6390 6391@item @emph{Class}: 6392Elemental function 6393 6394@item @emph{Syntax}: 6395@code{Y = FRACTION(X)} 6396 6397@item @emph{Arguments}: 6398@multitable @columnfractions .15 .70 6399@item @var{X} @tab The type of the argument shall be a @code{REAL}. 6400@end multitable 6401 6402@item @emph{Return value}: 6403The return value is of the same type and kind as the argument. 6404The fractional part of the model representation of @code{X} is returned; 6405it is @code{X * RADIX(X)**(-EXPONENT(X))}. 6406 6407@item @emph{Example}: 6408@smallexample 6409program test_fraction 6410 real :: x 6411 x = 178.1387e-4 6412 print *, fraction(x), x * radix(x)**(-exponent(x)) 6413end program test_fraction 6414@end smallexample 6415 6416@end table 6417 6418 6419 6420@node FREE 6421@section @code{FREE} --- Frees memory 6422@fnindex FREE 6423@cindex pointer, cray 6424 6425@table @asis 6426@item @emph{Description}: 6427Frees memory previously allocated by @code{MALLOC}. The @code{FREE} 6428intrinsic is an extension intended to be used with Cray pointers, and is 6429provided in GNU Fortran to allow user to compile legacy code. For 6430new code using Fortran 95 pointers, the memory de-allocation intrinsic is 6431@code{DEALLOCATE}. 6432 6433@item @emph{Standard}: 6434GNU extension 6435 6436@item @emph{Class}: 6437Subroutine 6438 6439@item @emph{Syntax}: 6440@code{CALL FREE(PTR)} 6441 6442@item @emph{Arguments}: 6443@multitable @columnfractions .15 .70 6444@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the 6445location of the memory that should be de-allocated. 6446@end multitable 6447 6448@item @emph{Return value}: 6449None 6450 6451@item @emph{Example}: 6452See @code{MALLOC} for an example. 6453 6454@item @emph{See also}: 6455@ref{MALLOC} 6456@end table 6457 6458 6459 6460@node FSEEK 6461@section @code{FSEEK} --- Low level file positioning subroutine 6462@fnindex FSEEK 6463@cindex file operation, seek 6464@cindex file operation, position 6465 6466@table @asis 6467@item @emph{Description}: 6468Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} 6469is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET}, 6470if set to 1, @var{OFFSET} is taken to be relative to the current position 6471@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}. 6472On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek 6473fails silently. 6474 6475This intrinsic routine is not fully backwards compatible with @command{g77}. 6476In @command{g77}, the @code{FSEEK} takes a statement label instead of a 6477@var{STATUS} variable. If FSEEK is used in old code, change 6478@smallexample 6479 CALL FSEEK(UNIT, OFFSET, WHENCE, *label) 6480@end smallexample 6481to 6482@smallexample 6483 INTEGER :: status 6484 CALL FSEEK(UNIT, OFFSET, WHENCE, status) 6485 IF (status /= 0) GOTO label 6486@end smallexample 6487 6488Please note that GNU Fortran provides the Fortran 2003 Stream facility. 6489Programmers should consider the use of new stream IO feature in new code 6490for future portability. See also @ref{Fortran 2003 status}. 6491 6492@item @emph{Standard}: 6493GNU extension 6494 6495@item @emph{Class}: 6496Subroutine 6497 6498@item @emph{Syntax}: 6499@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])} 6500 6501@item @emph{Arguments}: 6502@multitable @columnfractions .15 .70 6503@item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}. 6504@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}. 6505@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}. 6506Its value shall be either 0, 1 or 2. 6507@item @var{STATUS} @tab (Optional) shall be a scalar of type 6508@code{INTEGER(4)}. 6509@end multitable 6510 6511@item @emph{Example}: 6512@smallexample 6513PROGRAM test_fseek 6514 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2 6515 INTEGER :: fd, offset, ierr 6516 6517 ierr = 0 6518 offset = 5 6519 fd = 10 6520 6521 OPEN(UNIT=fd, FILE="fseek.test") 6522 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET 6523 print *, FTELL(fd), ierr 6524 6525 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end 6526 print *, FTELL(fd), ierr 6527 6528 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning 6529 print *, FTELL(fd), ierr 6530 6531 CLOSE(UNIT=fd) 6532END PROGRAM 6533@end smallexample 6534 6535@item @emph{See also}: 6536@ref{FTELL} 6537@end table 6538 6539 6540 6541@node FSTAT 6542@section @code{FSTAT} --- Get file status 6543@fnindex FSTAT 6544@cindex file system, file status 6545 6546@table @asis 6547@item @emph{Description}: 6548@code{FSTAT} is identical to @ref{STAT}, except that information about an 6549already opened file is obtained. 6550 6551The elements in @code{VALUES} are the same as described by @ref{STAT}. 6552 6553This intrinsic is provided in both subroutine and function forms; however, 6554only one form can be used in any given program unit. 6555 6556@item @emph{Standard}: 6557GNU extension 6558 6559@item @emph{Class}: 6560Subroutine, function 6561 6562@item @emph{Syntax}: 6563@multitable @columnfractions .80 6564@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])} 6565@item @code{STATUS = FSTAT(UNIT, VALUES)} 6566@end multitable 6567 6568@item @emph{Arguments}: 6569@multitable @columnfractions .15 .70 6570@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. 6571@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 6572@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 6573on success and a system specific error code otherwise. 6574@end multitable 6575 6576@item @emph{Example}: 6577See @ref{STAT} for an example. 6578 6579@item @emph{See also}: 6580To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT} 6581@end table 6582 6583 6584 6585@node FTELL 6586@section @code{FTELL} --- Current stream position 6587@fnindex FTELL 6588@cindex file operation, position 6589 6590@table @asis 6591@item @emph{Description}: 6592Retrieves the current position within an open file. 6593 6594This intrinsic is provided in both subroutine and function forms; however, 6595only one form can be used in any given program unit. 6596 6597@item @emph{Standard}: 6598GNU extension 6599 6600@item @emph{Class}: 6601Subroutine, function 6602 6603@item @emph{Syntax}: 6604@multitable @columnfractions .80 6605@item @code{CALL FTELL(UNIT, OFFSET)} 6606@item @code{OFFSET = FTELL(UNIT)} 6607@end multitable 6608 6609@item @emph{Arguments}: 6610@multitable @columnfractions .15 .70 6611@item @var{OFFSET} @tab Shall of type @code{INTEGER}. 6612@item @var{UNIT} @tab Shall of type @code{INTEGER}. 6613@end multitable 6614 6615@item @emph{Return value}: 6616In either syntax, @var{OFFSET} is set to the current offset of unit 6617number @var{UNIT}, or to @math{-1} if the unit is not currently open. 6618 6619@item @emph{Example}: 6620@smallexample 6621PROGRAM test_ftell 6622 INTEGER :: i 6623 OPEN(10, FILE="temp.dat") 6624 CALL ftell(10,i) 6625 WRITE(*,*) i 6626END PROGRAM 6627@end smallexample 6628 6629@item @emph{See also}: 6630@ref{FSEEK} 6631@end table 6632 6633 6634 6635@node GAMMA 6636@section @code{GAMMA} --- Gamma function 6637@fnindex GAMMA 6638@fnindex DGAMMA 6639@cindex Gamma function 6640@cindex Factorial function 6641 6642@table @asis 6643@item @emph{Description}: 6644@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive, 6645integer values of @var{X} the Gamma function simplifies to the factorial 6646function @math{\Gamma(x)=(x-1)!}. 6647 6648@tex 6649$$ 6650\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t 6651$$ 6652@end tex 6653 6654@item @emph{Standard}: 6655Fortran 2008 and later 6656 6657@item @emph{Class}: 6658Elemental function 6659 6660@item @emph{Syntax}: 6661@code{X = GAMMA(X)} 6662 6663@item @emph{Arguments}: 6664@multitable @columnfractions .15 .70 6665@item @var{X} @tab Shall be of type @code{REAL} and neither zero 6666nor a negative integer. 6667@end multitable 6668 6669@item @emph{Return value}: 6670The return value is of type @code{REAL} of the same kind as @var{X}. 6671 6672@item @emph{Example}: 6673@smallexample 6674program test_gamma 6675 real :: x = 1.0 6676 x = gamma(x) ! returns 1.0 6677end program test_gamma 6678@end smallexample 6679 6680@item @emph{Specific names}: 6681@multitable @columnfractions .20 .20 .20 .25 6682@item Name @tab Argument @tab Return type @tab Standard 6683@item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 6684@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 6685@end multitable 6686 6687@item @emph{See also}: 6688Logarithm of the Gamma function: @ref{LOG_GAMMA} 6689 6690@end table 6691 6692 6693 6694@node GERROR 6695@section @code{GERROR} --- Get last system error message 6696@fnindex GERROR 6697@cindex system, error handling 6698 6699@table @asis 6700@item @emph{Description}: 6701Returns the system error message corresponding to the last system error. 6702This resembles the functionality of @code{strerror(3)} in C. 6703 6704@item @emph{Standard}: 6705GNU extension 6706 6707@item @emph{Class}: 6708Subroutine 6709 6710@item @emph{Syntax}: 6711@code{CALL GERROR(RESULT)} 6712 6713@item @emph{Arguments}: 6714@multitable @columnfractions .15 .70 6715@item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default 6716@end multitable 6717 6718@item @emph{Example}: 6719@smallexample 6720PROGRAM test_gerror 6721 CHARACTER(len=100) :: msg 6722 CALL gerror(msg) 6723 WRITE(*,*) msg 6724END PROGRAM 6725@end smallexample 6726 6727@item @emph{See also}: 6728@ref{IERRNO}, @ref{PERROR} 6729@end table 6730 6731 6732 6733@node GETARG 6734@section @code{GETARG} --- Get command line arguments 6735@fnindex GETARG 6736@cindex command-line arguments 6737@cindex arguments, to program 6738 6739@table @asis 6740@item @emph{Description}: 6741Retrieve the @var{POS}-th argument that was passed on the 6742command line when the containing program was invoked. 6743 6744This intrinsic routine is provided for backwards compatibility with 6745GNU Fortran 77. In new code, programmers should consider the use of 6746the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 6747standard. 6748 6749@item @emph{Standard}: 6750GNU extension 6751 6752@item @emph{Class}: 6753Subroutine 6754 6755@item @emph{Syntax}: 6756@code{CALL GETARG(POS, VALUE)} 6757 6758@item @emph{Arguments}: 6759@multitable @columnfractions .15 .70 6760@item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than 6761the default integer kind; @math{@var{POS} \geq 0} 6762@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default 6763kind. 6764@item @var{VALUE} @tab Shall be of type @code{CHARACTER}. 6765@end multitable 6766 6767@item @emph{Return value}: 6768After @code{GETARG} returns, the @var{VALUE} argument holds the 6769@var{POS}th command line argument. If @var{VALUE} cannot hold the 6770argument, it is truncated to fit the length of @var{VALUE}. If there are 6771less than @var{POS} arguments specified at the command line, @var{VALUE} 6772will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set 6773to the name of the program (on systems that support this feature). 6774 6775@item @emph{Example}: 6776@smallexample 6777PROGRAM test_getarg 6778 INTEGER :: i 6779 CHARACTER(len=32) :: arg 6780 6781 DO i = 1, iargc() 6782 CALL getarg(i, arg) 6783 WRITE (*,*) arg 6784 END DO 6785END PROGRAM 6786@end smallexample 6787 6788@item @emph{See also}: 6789GNU Fortran 77 compatibility function: @ref{IARGC} 6790 6791Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, 6792@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 6793@end table 6794 6795 6796 6797@node GET_COMMAND 6798@section @code{GET_COMMAND} --- Get the entire command line 6799@fnindex GET_COMMAND 6800@cindex command-line arguments 6801@cindex arguments, to program 6802 6803@table @asis 6804@item @emph{Description}: 6805Retrieve the entire command line that was used to invoke the program. 6806 6807@item @emph{Standard}: 6808Fortran 2003 and later 6809 6810@item @emph{Class}: 6811Subroutine 6812 6813@item @emph{Syntax}: 6814@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])} 6815 6816@item @emph{Arguments}: 6817@multitable @columnfractions .15 .70 6818@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and 6819of default kind. 6820@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of 6821default kind. 6822@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of 6823default kind. 6824@end multitable 6825 6826@item @emph{Return value}: 6827If @var{COMMAND} is present, stores the entire command line that was used 6828to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is 6829assigned the length of the command line. If @var{STATUS} is present, it 6830is assigned 0 upon success of the command, -1 if @var{COMMAND} is too 6831short to store the command line, or a positive value in case of an error. 6832 6833@item @emph{Example}: 6834@smallexample 6835PROGRAM test_get_command 6836 CHARACTER(len=255) :: cmd 6837 CALL get_command(cmd) 6838 WRITE (*,*) TRIM(cmd) 6839END PROGRAM 6840@end smallexample 6841 6842@item @emph{See also}: 6843@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 6844@end table 6845 6846 6847 6848@node GET_COMMAND_ARGUMENT 6849@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments 6850@fnindex GET_COMMAND_ARGUMENT 6851@cindex command-line arguments 6852@cindex arguments, to program 6853 6854@table @asis 6855@item @emph{Description}: 6856Retrieve the @var{NUMBER}-th argument that was passed on the 6857command line when the containing program was invoked. 6858 6859@item @emph{Standard}: 6860Fortran 2003 and later 6861 6862@item @emph{Class}: 6863Subroutine 6864 6865@item @emph{Syntax}: 6866@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])} 6867 6868@item @emph{Arguments}: 6869@multitable @columnfractions .15 .70 6870@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of 6871default kind, @math{@var{NUMBER} \geq 0} 6872@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 6873and of default kind. 6874@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6875and of default kind. 6876@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6877and of default kind. 6878@end multitable 6879 6880@item @emph{Return value}: 6881After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the 6882@var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is 6883truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER} 6884arguments specified at the command line, @var{VALUE} will be filled with blanks. 6885If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on 6886systems that support this feature). The @var{LENGTH} argument contains the 6887length of the @var{NUMBER}-th command line argument. If the argument retrieval 6888fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated 6889command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is 6890zero. 6891 6892@item @emph{Example}: 6893@smallexample 6894PROGRAM test_get_command_argument 6895 INTEGER :: i 6896 CHARACTER(len=32) :: arg 6897 6898 i = 0 6899 DO 6900 CALL get_command_argument(i, arg) 6901 IF (LEN_TRIM(arg) == 0) EXIT 6902 6903 WRITE (*,*) TRIM(arg) 6904 i = i+1 6905 END DO 6906END PROGRAM 6907@end smallexample 6908 6909@item @emph{See also}: 6910@ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT} 6911@end table 6912 6913 6914 6915@node GETCWD 6916@section @code{GETCWD} --- Get current working directory 6917@fnindex GETCWD 6918@cindex system, working directory 6919 6920@table @asis 6921@item @emph{Description}: 6922Get current working directory. 6923 6924This intrinsic is provided in both subroutine and function forms; however, 6925only one form can be used in any given program unit. 6926 6927@item @emph{Standard}: 6928GNU extension 6929 6930@item @emph{Class}: 6931Subroutine, function 6932 6933@item @emph{Syntax}: 6934@multitable @columnfractions .80 6935@item @code{CALL GETCWD(C [, STATUS])} 6936@item @code{STATUS = GETCWD(C)} 6937@end multitable 6938 6939@item @emph{Arguments}: 6940@multitable @columnfractions .15 .70 6941@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. 6942@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, 6943a system specific and nonzero error code otherwise. 6944@end multitable 6945 6946@item @emph{Example}: 6947@smallexample 6948PROGRAM test_getcwd 6949 CHARACTER(len=255) :: cwd 6950 CALL getcwd(cwd) 6951 WRITE(*,*) TRIM(cwd) 6952END PROGRAM 6953@end smallexample 6954 6955@item @emph{See also}: 6956@ref{CHDIR} 6957@end table 6958 6959 6960 6961@node GETENV 6962@section @code{GETENV} --- Get an environmental variable 6963@fnindex GETENV 6964@cindex environment variable 6965 6966@table @asis 6967@item @emph{Description}: 6968Get the @var{VALUE} of the environmental variable @var{NAME}. 6969 6970This intrinsic routine is provided for backwards compatibility with 6971GNU Fortran 77. In new code, programmers should consider the use of 6972the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran 69732003 standard. 6974 6975Note that @code{GETENV} need not be thread-safe. It is the 6976responsibility of the user to ensure that the environment is not being 6977updated concurrently with a call to the @code{GETENV} intrinsic. 6978 6979@item @emph{Standard}: 6980GNU extension 6981 6982@item @emph{Class}: 6983Subroutine 6984 6985@item @emph{Syntax}: 6986@code{CALL GETENV(NAME, VALUE)} 6987 6988@item @emph{Arguments}: 6989@multitable @columnfractions .15 .70 6990@item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind. 6991@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. 6992@end multitable 6993 6994@item @emph{Return value}: 6995Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 6996not large enough to hold the data, it is truncated. If @var{NAME} 6997is not set, @var{VALUE} will be filled with blanks. 6998 6999@item @emph{Example}: 7000@smallexample 7001PROGRAM test_getenv 7002 CHARACTER(len=255) :: homedir 7003 CALL getenv("HOME", homedir) 7004 WRITE (*,*) TRIM(homedir) 7005END PROGRAM 7006@end smallexample 7007 7008@item @emph{See also}: 7009@ref{GET_ENVIRONMENT_VARIABLE} 7010@end table 7011 7012 7013 7014@node GET_ENVIRONMENT_VARIABLE 7015@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable 7016@fnindex GET_ENVIRONMENT_VARIABLE 7017@cindex environment variable 7018 7019@table @asis 7020@item @emph{Description}: 7021Get the @var{VALUE} of the environmental variable @var{NAME}. 7022 7023Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It 7024is the responsibility of the user to ensure that the environment is 7025not being updated concurrently with a call to the 7026@code{GET_ENVIRONMENT_VARIABLE} intrinsic. 7027 7028@item @emph{Standard}: 7029Fortran 2003 and later 7030 7031@item @emph{Class}: 7032Subroutine 7033 7034@item @emph{Syntax}: 7035@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)} 7036 7037@item @emph{Arguments}: 7038@multitable @columnfractions .15 .70 7039@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER} 7040and of default kind. 7041@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 7042and of default kind. 7043@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7044and of default kind. 7045@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 7046and of default kind. 7047@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL} 7048and of default kind. 7049@end multitable 7050 7051@item @emph{Return value}: 7052Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 7053not large enough to hold the data, it is truncated. If @var{NAME} 7054is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH} 7055contains the length needed for storing the environment variable @var{NAME} 7056or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present 7057but too short for the environment variable; it is 1 if the environment 7058variable does not exist and 2 if the processor does not support environment 7059variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is 7060present with the value @code{.FALSE.}, the trailing blanks in @var{NAME} 7061are significant; otherwise they are not part of the environment variable 7062name. 7063 7064@item @emph{Example}: 7065@smallexample 7066PROGRAM test_getenv 7067 CHARACTER(len=255) :: homedir 7068 CALL get_environment_variable("HOME", homedir) 7069 WRITE (*,*) TRIM(homedir) 7070END PROGRAM 7071@end smallexample 7072@end table 7073 7074 7075 7076@node GETGID 7077@section @code{GETGID} --- Group ID function 7078@fnindex GETGID 7079@cindex system, group ID 7080 7081@table @asis 7082@item @emph{Description}: 7083Returns the numerical group ID of the current process. 7084 7085@item @emph{Standard}: 7086GNU extension 7087 7088@item @emph{Class}: 7089Function 7090 7091@item @emph{Syntax}: 7092@code{RESULT = GETGID()} 7093 7094@item @emph{Return value}: 7095The return value of @code{GETGID} is an @code{INTEGER} of the default 7096kind. 7097 7098 7099@item @emph{Example}: 7100See @code{GETPID} for an example. 7101 7102@item @emph{See also}: 7103@ref{GETPID}, @ref{GETUID} 7104@end table 7105 7106 7107 7108@node GETLOG 7109@section @code{GETLOG} --- Get login name 7110@fnindex GETLOG 7111@cindex system, login name 7112@cindex login name 7113 7114@table @asis 7115@item @emph{Description}: 7116Gets the username under which the program is running. 7117 7118@item @emph{Standard}: 7119GNU extension 7120 7121@item @emph{Class}: 7122Subroutine 7123 7124@item @emph{Syntax}: 7125@code{CALL GETLOG(C)} 7126 7127@item @emph{Arguments}: 7128@multitable @columnfractions .15 .70 7129@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind. 7130@end multitable 7131 7132@item @emph{Return value}: 7133Stores the current user name in @var{LOGIN}. (On systems where POSIX 7134functions @code{geteuid} and @code{getpwuid} are not available, and 7135the @code{getlogin} function is not implemented either, this will 7136return a blank string.) 7137 7138@item @emph{Example}: 7139@smallexample 7140PROGRAM TEST_GETLOG 7141 CHARACTER(32) :: login 7142 CALL GETLOG(login) 7143 WRITE(*,*) login 7144END PROGRAM 7145@end smallexample 7146 7147@item @emph{See also}: 7148@ref{GETUID} 7149@end table 7150 7151 7152 7153@node GETPID 7154@section @code{GETPID} --- Process ID function 7155@fnindex GETPID 7156@cindex system, process ID 7157@cindex process ID 7158 7159@table @asis 7160@item @emph{Description}: 7161Returns the numerical process identifier of the current process. 7162 7163@item @emph{Standard}: 7164GNU extension 7165 7166@item @emph{Class}: 7167Function 7168 7169@item @emph{Syntax}: 7170@code{RESULT = GETPID()} 7171 7172@item @emph{Return value}: 7173The return value of @code{GETPID} is an @code{INTEGER} of the default 7174kind. 7175 7176 7177@item @emph{Example}: 7178@smallexample 7179program info 7180 print *, "The current process ID is ", getpid() 7181 print *, "Your numerical user ID is ", getuid() 7182 print *, "Your numerical group ID is ", getgid() 7183end program info 7184@end smallexample 7185 7186@item @emph{See also}: 7187@ref{GETGID}, @ref{GETUID} 7188@end table 7189 7190 7191 7192@node GETUID 7193@section @code{GETUID} --- User ID function 7194@fnindex GETUID 7195@cindex system, user ID 7196@cindex user id 7197 7198@table @asis 7199@item @emph{Description}: 7200Returns the numerical user ID of the current process. 7201 7202@item @emph{Standard}: 7203GNU extension 7204 7205@item @emph{Class}: 7206Function 7207 7208@item @emph{Syntax}: 7209@code{RESULT = GETUID()} 7210 7211@item @emph{Return value}: 7212The return value of @code{GETUID} is an @code{INTEGER} of the default 7213kind. 7214 7215 7216@item @emph{Example}: 7217See @code{GETPID} for an example. 7218 7219@item @emph{See also}: 7220@ref{GETPID}, @ref{GETLOG} 7221@end table 7222 7223 7224 7225@node GMTIME 7226@section @code{GMTIME} --- Convert time to GMT info 7227@fnindex GMTIME 7228@cindex time, conversion to GMT info 7229 7230@table @asis 7231@item @emph{Description}: 7232Given a system time value @var{TIME} (as provided by the @ref{TIME} 7233intrinsic), fills @var{VALUES} with values extracted from it appropriate 7234to the UTC time zone (Universal Coordinated Time, also known in some 7235countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}. 7236 7237This intrinsic routine is provided for backwards compatibility with 7238GNU Fortran 77. In new code, programmers should consider the use of 7239the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 7240standard. 7241 7242@item @emph{Standard}: 7243GNU extension 7244 7245@item @emph{Class}: 7246Subroutine 7247 7248@item @emph{Syntax}: 7249@code{CALL GMTIME(TIME, VALUES)} 7250 7251@item @emph{Arguments}: 7252@multitable @columnfractions .15 .70 7253@item @var{TIME} @tab An @code{INTEGER} scalar expression 7254corresponding to a system time, with @code{INTENT(IN)}. 7255@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 7256with @code{INTENT(OUT)}. 7257@end multitable 7258 7259@item @emph{Return value}: 7260The elements of @var{VALUES} are assigned as follows: 7261@enumerate 7262@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 7263seconds 7264@item Minutes after the hour, range 0--59 7265@item Hours past midnight, range 0--23 7266@item Day of month, range 1--31 7267@item Number of months since January, range 0--11 7268@item Years since 1900 7269@item Number of days since Sunday, range 0--6 7270@item Days since January 1, range 0--365 7271@item Daylight savings indicator: positive if daylight savings is in 7272effect, zero if not, and negative if the information is not available. 7273@end enumerate 7274 7275@item @emph{See also}: 7276@ref{DATE_AND_TIME}, @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} 7277 7278@end table 7279 7280 7281 7282@node HOSTNM 7283@section @code{HOSTNM} --- Get system host name 7284@fnindex HOSTNM 7285@cindex system, host name 7286 7287@table @asis 7288@item @emph{Description}: 7289Retrieves the host name of the system on which the program is running. 7290 7291This intrinsic is provided in both subroutine and function forms; however, 7292only one form can be used in any given program unit. 7293 7294@item @emph{Standard}: 7295GNU extension 7296 7297@item @emph{Class}: 7298Subroutine, function 7299 7300@item @emph{Syntax}: 7301@multitable @columnfractions .80 7302@item @code{CALL HOSTNM(C [, STATUS])} 7303@item @code{STATUS = HOSTNM(NAME)} 7304@end multitable 7305 7306@item @emph{Arguments}: 7307@multitable @columnfractions .15 .70 7308@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind. 7309@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 7310Returns 0 on success, or a system specific error code otherwise. 7311@end multitable 7312 7313@item @emph{Return value}: 7314In either syntax, @var{NAME} is set to the current hostname if it can 7315be obtained, or to a blank string otherwise. 7316 7317@end table 7318 7319 7320 7321@node HUGE 7322@section @code{HUGE} --- Largest number of a kind 7323@fnindex HUGE 7324@cindex limits, largest number 7325@cindex model representation, largest number 7326 7327@table @asis 7328@item @emph{Description}: 7329@code{HUGE(X)} returns the largest number that is not an infinity in 7330the model of the type of @code{X}. 7331 7332@item @emph{Standard}: 7333Fortran 95 and later 7334 7335@item @emph{Class}: 7336Inquiry function 7337 7338@item @emph{Syntax}: 7339@code{RESULT = HUGE(X)} 7340 7341@item @emph{Arguments}: 7342@multitable @columnfractions .15 .70 7343@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}. 7344@end multitable 7345 7346@item @emph{Return value}: 7347The return value is of the same type and kind as @var{X} 7348 7349@item @emph{Example}: 7350@smallexample 7351program test_huge_tiny 7352 print *, huge(0), huge(0.0), huge(0.0d0) 7353 print *, tiny(0.0), tiny(0.0d0) 7354end program test_huge_tiny 7355@end smallexample 7356@end table 7357 7358 7359 7360@node HYPOT 7361@section @code{HYPOT} --- Euclidean distance function 7362@fnindex HYPOT 7363@cindex Euclidean distance 7364 7365@table @asis 7366@item @emph{Description}: 7367@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to 7368@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow. 7369 7370@item @emph{Standard}: 7371Fortran 2008 and later 7372 7373@item @emph{Class}: 7374Elemental function 7375 7376@item @emph{Syntax}: 7377@code{RESULT = HYPOT(X, Y)} 7378 7379@item @emph{Arguments}: 7380@multitable @columnfractions .15 .70 7381@item @var{X} @tab The type shall be @code{REAL}. 7382@item @var{Y} @tab The type and kind type parameter shall be the same as 7383@var{X}. 7384@end multitable 7385 7386@item @emph{Return value}: 7387The return value has the same type and kind type parameter as @var{X}. 7388 7389@item @emph{Example}: 7390@smallexample 7391program test_hypot 7392 real(4) :: x = 1.e0_4, y = 0.5e0_4 7393 x = hypot(x,y) 7394end program test_hypot 7395@end smallexample 7396@end table 7397 7398 7399 7400@node IACHAR 7401@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence 7402@fnindex IACHAR 7403@cindex @acronym{ASCII} collating sequence 7404@cindex collating sequence, @acronym{ASCII} 7405@cindex conversion, to integer 7406 7407@table @asis 7408@item @emph{Description}: 7409@code{IACHAR(C)} returns the code for the @acronym{ASCII} character 7410in the first character position of @code{C}. 7411 7412@item @emph{Standard}: 7413Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 7414 7415@item @emph{Class}: 7416Elemental function 7417 7418@item @emph{Syntax}: 7419@code{RESULT = IACHAR(C [, KIND])} 7420 7421@item @emph{Arguments}: 7422@multitable @columnfractions .15 .70 7423@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 7424@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7425expression indicating the kind parameter of the result. 7426@end multitable 7427 7428@item @emph{Return value}: 7429The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7430@var{KIND} is absent, the return value is of default integer kind. 7431 7432@item @emph{Example}: 7433@smallexample 7434program test_iachar 7435 integer i 7436 i = iachar(' ') 7437end program test_iachar 7438@end smallexample 7439 7440@item @emph{Note}: 7441See @ref{ICHAR} for a discussion of converting between numerical values 7442and formatted string representations. 7443 7444@item @emph{See also}: 7445@ref{ACHAR}, @ref{CHAR}, @ref{ICHAR} 7446 7447@end table 7448 7449 7450 7451@node IALL 7452@section @code{IALL} --- Bitwise AND of array elements 7453@fnindex IALL 7454@cindex array, AND 7455@cindex bits, AND of array elements 7456 7457@table @asis 7458@item @emph{Description}: 7459Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM} 7460if the corresponding element in @var{MASK} is @code{TRUE}. 7461 7462@item @emph{Standard}: 7463Fortran 2008 and later 7464 7465@item @emph{Class}: 7466Transformational function 7467 7468@item @emph{Syntax}: 7469@multitable @columnfractions .80 7470@item @code{RESULT = IALL(ARRAY[, MASK])} 7471@item @code{RESULT = IALL(ARRAY, DIM[, MASK])} 7472@end multitable 7473 7474@item @emph{Arguments}: 7475@multitable @columnfractions .15 .70 7476@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7477@item @var{DIM} @tab (Optional) shall be a scalar of type 7478@code{INTEGER} with a value in the range from 1 to n, where n 7479equals the rank of @var{ARRAY}. 7480@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7481and either be a scalar or an array of the same shape as @var{ARRAY}. 7482@end multitable 7483 7484@item @emph{Return value}: 7485The result is of the same type as @var{ARRAY}. 7486 7487If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in 7488@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7489the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7490dimension @var{DIM} dropped is returned. 7491 7492@item @emph{Example}: 7493@smallexample 7494PROGRAM test_iall 7495 INTEGER(1) :: a(2) 7496 7497 a(1) = b'00100100' 7498 a(2) = b'01101010' 7499 7500 ! prints 00100000 7501 PRINT '(b8.8)', IALL(a) 7502END PROGRAM 7503@end smallexample 7504 7505@item @emph{See also}: 7506@ref{IANY}, @ref{IPARITY}, @ref{IAND} 7507@end table 7508 7509 7510 7511@node IAND 7512@section @code{IAND} --- Bitwise logical and 7513@fnindex IAND 7514@fnindex BIAND 7515@fnindex IIAND 7516@fnindex JIAND 7517@fnindex KIAND 7518@cindex bitwise logical and 7519@cindex logical and, bitwise 7520 7521@table @asis 7522@item @emph{Description}: 7523Bitwise logical @code{AND}. 7524 7525@item @emph{Standard}: 7526Fortran 95 and later, has overloads that are GNU extensions 7527 7528@item @emph{Class}: 7529Elemental function 7530 7531@item @emph{Syntax}: 7532@code{RESULT = IAND(I, J)} 7533 7534@item @emph{Arguments}: 7535@multitable @columnfractions .15 .70 7536@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 7537@item @var{J} @tab The type shall be @code{INTEGER} with the same 7538kind type parameter as @var{I} or a boz-literal-constant. 7539@var{I} and @var{J} shall not both be boz-literal-constants. 7540@end multitable 7541 7542@item @emph{Return value}: 7543The return type is @code{INTEGER} with the kind type parameter of the 7544arguments. 7545A boz-literal-constant is converted to an @code{INTEGER} with the kind 7546type parameter of the other argument as-if a call to @ref{INT} occurred. 7547 7548@item @emph{Example}: 7549@smallexample 7550PROGRAM test_iand 7551 INTEGER :: a, b 7552 DATA a / Z'F' /, b / Z'3' / 7553 WRITE (*,*) IAND(a, b) 7554END PROGRAM 7555@end smallexample 7556 7557@item @emph{Specific names}: 7558@multitable @columnfractions .20 .20 .20 .25 7559@item Name @tab Argument @tab Return type @tab Standard 7560@item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7561@item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7562@item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7563@item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7564@item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7565@end multitable 7566 7567@item @emph{See also}: 7568@ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 7569 7570@end table 7571 7572 7573 7574@node IANY 7575@section @code{IANY} --- Bitwise OR of array elements 7576@fnindex IANY 7577@cindex array, OR 7578@cindex bits, OR of array elements 7579 7580@table @asis 7581@item @emph{Description}: 7582Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along 7583dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 7584 7585@item @emph{Standard}: 7586Fortran 2008 and later 7587 7588@item @emph{Class}: 7589Transformational function 7590 7591@item @emph{Syntax}: 7592@multitable @columnfractions .80 7593@item @code{RESULT = IANY(ARRAY[, MASK])} 7594@item @code{RESULT = IANY(ARRAY, DIM[, MASK])} 7595@end multitable 7596 7597@item @emph{Arguments}: 7598@multitable @columnfractions .15 .70 7599@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7600@item @var{DIM} @tab (Optional) shall be a scalar of type 7601@code{INTEGER} with a value in the range from 1 to n, where n 7602equals the rank of @var{ARRAY}. 7603@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7604and either be a scalar or an array of the same shape as @var{ARRAY}. 7605@end multitable 7606 7607@item @emph{Return value}: 7608The result is of the same type as @var{ARRAY}. 7609 7610If @var{DIM} is absent, a scalar with the bitwise OR of all elements in 7611@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7612the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7613dimension @var{DIM} dropped is returned. 7614 7615@item @emph{Example}: 7616@smallexample 7617PROGRAM test_iany 7618 INTEGER(1) :: a(2) 7619 7620 a(1) = b'00100100' 7621 a(2) = b'01101010' 7622 7623 ! prints 01101110 7624 PRINT '(b8.8)', IANY(a) 7625END PROGRAM 7626@end smallexample 7627 7628@item @emph{See also}: 7629@ref{IPARITY}, @ref{IALL}, @ref{IOR} 7630@end table 7631 7632 7633 7634@node IARGC 7635@section @code{IARGC} --- Get the number of command line arguments 7636@fnindex IARGC 7637@cindex command-line arguments 7638@cindex command-line arguments, number of 7639@cindex arguments, to program 7640 7641@table @asis 7642@item @emph{Description}: 7643@code{IARGC} returns the number of arguments passed on the 7644command line when the containing program was invoked. 7645 7646This intrinsic routine is provided for backwards compatibility with 7647GNU Fortran 77. In new code, programmers should consider the use of 7648the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 7649standard. 7650 7651@item @emph{Standard}: 7652GNU extension 7653 7654@item @emph{Class}: 7655Function 7656 7657@item @emph{Syntax}: 7658@code{RESULT = IARGC()} 7659 7660@item @emph{Arguments}: 7661None. 7662 7663@item @emph{Return value}: 7664The number of command line arguments, type @code{INTEGER(4)}. 7665 7666@item @emph{Example}: 7667See @ref{GETARG} 7668 7669@item @emph{See also}: 7670GNU Fortran 77 compatibility subroutine: @ref{GETARG} 7671 7672Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, 7673@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 7674@end table 7675 7676 7677 7678@node IBCLR 7679@section @code{IBCLR} --- Clear bit 7680@fnindex IBCLR 7681@fnindex BBCLR 7682@fnindex IIBCLR 7683@fnindex JIBCLR 7684@fnindex KIBCLR 7685@cindex bits, unset 7686@cindex bits, clear 7687 7688@table @asis 7689@item @emph{Description}: 7690@code{IBCLR} returns the value of @var{I} with the bit at position 7691@var{POS} set to zero. 7692 7693@item @emph{Standard}: 7694Fortran 95 and later, has overloads that are GNU extensions 7695 7696@item @emph{Class}: 7697Elemental function 7698 7699@item @emph{Syntax}: 7700@code{RESULT = IBCLR(I, POS)} 7701 7702@item @emph{Arguments}: 7703@multitable @columnfractions .15 .70 7704@item @var{I} @tab The type shall be @code{INTEGER}. 7705@item @var{POS} @tab The type shall be @code{INTEGER}. 7706@end multitable 7707 7708@item @emph{Return value}: 7709The return value is of type @code{INTEGER} and of the same kind as 7710@var{I}. 7711 7712@item @emph{Specific names}: 7713@multitable @columnfractions .20 .20 .20 .25 7714@item Name @tab Argument @tab Return type @tab Standard 7715@item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7716@item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7717@item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7718@item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7719@item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7720@end multitable 7721 7722@item @emph{See also}: 7723@ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} 7724 7725@end table 7726 7727 7728 7729@node IBITS 7730@section @code{IBITS} --- Bit extraction 7731@fnindex IBITS 7732@fnindex BBITS 7733@fnindex IIBITS 7734@fnindex JIBITS 7735@fnindex KIBITS 7736@cindex bits, get 7737@cindex bits, extract 7738 7739@table @asis 7740@item @emph{Description}: 7741@code{IBITS} extracts a field of length @var{LEN} from @var{I}, 7742starting from bit position @var{POS} and extending left for @var{LEN} 7743bits. The result is right-justified and the remaining bits are 7744zeroed. The value of @code{POS+LEN} must be less than or equal to the 7745value @code{BIT_SIZE(I)}. 7746 7747@item @emph{Standard}: 7748Fortran 95 and later, has overloads that are GNU extensions 7749 7750@item @emph{Class}: 7751Elemental function 7752 7753@item @emph{Syntax}: 7754@code{RESULT = IBITS(I, POS, LEN)} 7755 7756@item @emph{Arguments}: 7757@multitable @columnfractions .15 .70 7758@item @var{I} @tab The type shall be @code{INTEGER}. 7759@item @var{POS} @tab The type shall be @code{INTEGER}. 7760@item @var{LEN} @tab The type shall be @code{INTEGER}. 7761@end multitable 7762 7763@item @emph{Return value}: 7764The return value is of type @code{INTEGER} and of the same kind as 7765@var{I}. 7766 7767@item @emph{Specific names}: 7768@multitable @columnfractions .20 .20 .20 .25 7769@item Name @tab Argument @tab Return type @tab Standard 7770@item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7771@item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7772@item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7773@item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7774@item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7775@end multitable 7776 7777@item @emph{See also}: 7778@ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR} 7779@end table 7780 7781 7782 7783@node IBSET 7784@section @code{IBSET} --- Set bit 7785@fnindex IBSET 7786@fnindex BBSET 7787@fnindex IIBSET 7788@fnindex JIBSET 7789@fnindex KIBSET 7790@cindex bits, set 7791 7792@table @asis 7793@item @emph{Description}: 7794@code{IBSET} returns the value of @var{I} with the bit at position 7795@var{POS} set to one. 7796 7797@item @emph{Standard}: 7798Fortran 95 and later, has overloads that are GNU extensions 7799 7800@item @emph{Class}: 7801Elemental function 7802 7803@item @emph{Syntax}: 7804@code{RESULT = IBSET(I, POS)} 7805 7806@item @emph{Arguments}: 7807@multitable @columnfractions .15 .70 7808@item @var{I} @tab The type shall be @code{INTEGER}. 7809@item @var{POS} @tab The type shall be @code{INTEGER}. 7810@end multitable 7811 7812@item @emph{Return value}: 7813The return value is of type @code{INTEGER} and of the same kind as 7814@var{I}. 7815 7816@item @emph{Specific names}: 7817@multitable @columnfractions .20 .20 .20 .25 7818@item Name @tab Argument @tab Return type @tab Standard 7819@item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 7820@item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 7821@item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 7822@item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 7823@item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 7824@end multitable 7825 7826@item @emph{See also}: 7827@ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} 7828 7829@end table 7830 7831 7832 7833@node ICHAR 7834@section @code{ICHAR} --- Character-to-integer conversion function 7835@fnindex ICHAR 7836@cindex conversion, to integer 7837 7838@table @asis 7839@item @emph{Description}: 7840@code{ICHAR(C)} returns the code for the character in the first character 7841position of @code{C} in the system's native character set. 7842The correspondence between characters and their codes is not necessarily 7843the same across different GNU Fortran implementations. 7844 7845@item @emph{Standard}: 7846Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 7847 7848@item @emph{Class}: 7849Elemental function 7850 7851@item @emph{Syntax}: 7852@code{RESULT = ICHAR(C [, KIND])} 7853 7854@item @emph{Arguments}: 7855@multitable @columnfractions .15 .70 7856@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 7857@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7858expression indicating the kind parameter of the result. 7859@end multitable 7860 7861@item @emph{Return value}: 7862The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7863@var{KIND} is absent, the return value is of default integer kind. 7864 7865@item @emph{Example}: 7866@smallexample 7867program test_ichar 7868 integer i 7869 i = ichar(' ') 7870end program test_ichar 7871@end smallexample 7872 7873@item @emph{Specific names}: 7874@multitable @columnfractions .20 .20 .20 .25 7875@item Name @tab Argument @tab Return type @tab Standard 7876@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later 7877@end multitable 7878 7879@item @emph{Note}: 7880No intrinsic exists to convert between a numeric value and a formatted 7881character string representation -- for instance, given the 7882@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or 7883@code{REAL} value with the value 154, or vice versa. Instead, this 7884functionality is provided by internal-file I/O, as in the following 7885example: 7886@smallexample 7887program read_val 7888 integer value 7889 character(len=10) string, string2 7890 string = '154' 7891 7892 ! Convert a string to a numeric value 7893 read (string,'(I10)') value 7894 print *, value 7895 7896 ! Convert a value to a formatted string 7897 write (string2,'(I10)') value 7898 print *, string2 7899end program read_val 7900@end smallexample 7901 7902@item @emph{See also}: 7903@ref{ACHAR}, @ref{CHAR}, @ref{IACHAR} 7904 7905@end table 7906 7907 7908 7909@node IDATE 7910@section @code{IDATE} --- Get current local time subroutine (day/month/year) 7911@fnindex IDATE 7912@cindex date, current 7913@cindex current date 7914 7915@table @asis 7916@item @emph{Description}: 7917@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the 7918current local time. The day (in the range 1-31), month (in the range 1-12), 7919and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively. 7920The year has four significant digits. 7921 7922This intrinsic routine is provided for backwards compatibility with 7923GNU Fortran 77. In new code, programmers should consider the use of 7924the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 7925standard. 7926 7927@item @emph{Standard}: 7928GNU extension 7929 7930@item @emph{Class}: 7931Subroutine 7932 7933@item @emph{Syntax}: 7934@code{CALL IDATE(VALUES)} 7935 7936@item @emph{Arguments}: 7937@multitable @columnfractions .15 .70 7938@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and 7939the kind shall be the default integer kind. 7940@end multitable 7941 7942@item @emph{Return value}: 7943Does not return anything. 7944 7945@item @emph{Example}: 7946@smallexample 7947program test_idate 7948 integer, dimension(3) :: tarray 7949 call idate(tarray) 7950 print *, tarray(1) 7951 print *, tarray(2) 7952 print *, tarray(3) 7953end program test_idate 7954@end smallexample 7955 7956@item @emph{See also}: 7957@ref{DATE_AND_TIME} 7958@end table 7959 7960 7961@node IEOR 7962@section @code{IEOR} --- Bitwise logical exclusive or 7963@fnindex IEOR 7964@fnindex BIEOR 7965@fnindex IIEOR 7966@fnindex JIEOR 7967@fnindex KIEOR 7968@cindex bitwise logical exclusive or 7969@cindex logical exclusive or, bitwise 7970 7971@table @asis 7972@item @emph{Description}: 7973@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and 7974@var{J}. 7975 7976@item @emph{Standard}: 7977Fortran 95 and later, has overloads that are GNU extensions 7978 7979@item @emph{Class}: 7980Elemental function 7981 7982@item @emph{Syntax}: 7983@code{RESULT = IEOR(I, J)} 7984 7985@item @emph{Arguments}: 7986@multitable @columnfractions .15 .70 7987@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 7988@item @var{J} @tab The type shall be @code{INTEGER} with the same 7989kind type parameter as @var{I} or a boz-literal-constant. 7990@var{I} and @var{J} shall not both be boz-literal-constants. 7991@end multitable 7992 7993@item @emph{Return value}: 7994The return type is @code{INTEGER} with the kind type parameter of the 7995arguments. 7996A boz-literal-constant is converted to an @code{INTEGER} with the kind 7997type parameter of the other argument as-if a call to @ref{INT} occurred. 7998 7999@item @emph{Specific names}: 8000@multitable @columnfractions .20 .20 .20 .25 8001@item Name @tab Argument @tab Return type @tab Standard 8002@item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 8003@item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8004@item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8005@item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8006@item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8007@end multitable 8008 8009@item @emph{See also}: 8010@ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 8011@end table 8012 8013 8014 8015@node IERRNO 8016@section @code{IERRNO} --- Get the last system error number 8017@fnindex IERRNO 8018@cindex system, error handling 8019 8020@table @asis 8021@item @emph{Description}: 8022Returns the last system error number, as given by the C @code{errno} 8023variable. 8024 8025@item @emph{Standard}: 8026GNU extension 8027 8028@item @emph{Class}: 8029Function 8030 8031@item @emph{Syntax}: 8032@code{RESULT = IERRNO()} 8033 8034@item @emph{Arguments}: 8035None. 8036 8037@item @emph{Return value}: 8038The return value is of type @code{INTEGER} and of the default integer 8039kind. 8040 8041@item @emph{See also}: 8042@ref{PERROR} 8043@end table 8044 8045 8046 8047@node IMAGE_INDEX 8048@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index 8049@fnindex IMAGE_INDEX 8050@cindex coarray, @code{IMAGE_INDEX} 8051@cindex images, cosubscript to image index conversion 8052 8053@table @asis 8054@item @emph{Description}: 8055Returns the image index belonging to a cosubscript. 8056 8057@item @emph{Standard}: 8058Fortran 2008 and later 8059 8060@item @emph{Class}: 8061Inquiry function. 8062 8063@item @emph{Syntax}: 8064@code{RESULT = IMAGE_INDEX(COARRAY, SUB)} 8065 8066@item @emph{Arguments}: None. 8067@multitable @columnfractions .15 .70 8068@item @var{COARRAY} @tab Coarray of any type. 8069@item @var{SUB} @tab default integer rank-1 array of a size equal to 8070the corank of @var{COARRAY}. 8071@end multitable 8072 8073 8074@item @emph{Return value}: 8075Scalar default integer with the value of the image index which corresponds 8076to the cosubscripts. For invalid cosubscripts the result is zero. 8077 8078@item @emph{Example}: 8079@smallexample 8080INTEGER :: array[2,-1:4,8,*] 8081! Writes 28 (or 0 if there are fewer than 28 images) 8082WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1]) 8083@end smallexample 8084 8085@item @emph{See also}: 8086@ref{THIS_IMAGE}, @ref{NUM_IMAGES} 8087@end table 8088 8089 8090 8091@node INDEX intrinsic 8092@section @code{INDEX} --- Position of a substring within a string 8093@fnindex INDEX 8094@cindex substring position 8095@cindex string, find substring 8096 8097@table @asis 8098@item @emph{Description}: 8099Returns the position of the start of the first occurrence of string 8100@var{SUBSTRING} as a substring in @var{STRING}, counting from one. If 8101@var{SUBSTRING} is not present in @var{STRING}, zero is returned. If 8102the @var{BACK} argument is present and true, the return value is the 8103start of the last occurrence rather than the first. 8104 8105@item @emph{Standard}: 8106Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8107 8108@item @emph{Class}: 8109Elemental function 8110 8111@item @emph{Syntax}: 8112@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])} 8113 8114@item @emph{Arguments}: 8115@multitable @columnfractions .15 .70 8116@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with 8117@code{INTENT(IN)} 8118@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with 8119@code{INTENT(IN)} 8120@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with 8121@code{INTENT(IN)} 8122@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8123expression indicating the kind parameter of the result. 8124@end multitable 8125 8126@item @emph{Return value}: 8127The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8128@var{KIND} is absent, the return value is of default integer kind. 8129 8130@item @emph{Specific names}: 8131@multitable @columnfractions .20 .20 .20 .25 8132@item Name @tab Argument @tab Return type @tab Standard 8133@item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later 8134@end multitable 8135 8136@item @emph{See also}: 8137@ref{SCAN}, @ref{VERIFY} 8138@end table 8139 8140 8141 8142@node INT 8143@section @code{INT} --- Convert to integer type 8144@fnindex INT 8145@fnindex IFIX 8146@fnindex IDINT 8147@cindex conversion, to integer 8148 8149@table @asis 8150@item @emph{Description}: 8151Convert to integer type 8152 8153@item @emph{Standard}: 8154Fortran 77 and later 8155 8156@item @emph{Class}: 8157Elemental function 8158 8159@item @emph{Syntax}: 8160@code{RESULT = INT(A [, KIND))} 8161 8162@item @emph{Arguments}: 8163@multitable @columnfractions .15 .70 8164@item @var{A} @tab Shall be of type @code{INTEGER}, 8165@code{REAL}, or @code{COMPLEX}. 8166@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8167expression indicating the kind parameter of the result. 8168@end multitable 8169 8170@item @emph{Return value}: 8171These functions return a @code{INTEGER} variable or array under 8172the following rules: 8173 8174@table @asis 8175@item (A) 8176If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 8177@item (B) 8178If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} 8179equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer 8180whose magnitude is the largest integer that does not exceed the magnitude 8181of @var{A} and whose sign is the same as the sign of @var{A}. 8182@item (C) 8183If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}. 8184@end table 8185 8186@item @emph{Example}: 8187@smallexample 8188program test_int 8189 integer :: i = 42 8190 complex :: z = (-3.7, 1.0) 8191 print *, int(i) 8192 print *, int(z), int(z,8) 8193end program 8194@end smallexample 8195 8196@item @emph{Specific names}: 8197@multitable @columnfractions .20 .20 .20 .25 8198@item Name @tab Argument @tab Return type @tab Standard 8199@item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8200@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 8201@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 8202@end multitable 8203 8204@end table 8205 8206 8207@node INT2 8208@section @code{INT2} --- Convert to 16-bit integer type 8209@fnindex INT2 8210@fnindex SHORT 8211@cindex conversion, to integer 8212 8213@table @asis 8214@item @emph{Description}: 8215Convert to a @code{KIND=2} integer type. This is equivalent to the 8216standard @code{INT} intrinsic with an optional argument of 8217@code{KIND=2}, and is only included for backwards compatibility. 8218 8219The @code{SHORT} intrinsic is equivalent to @code{INT2}. 8220 8221@item @emph{Standard}: 8222GNU extension 8223 8224@item @emph{Class}: 8225Elemental function 8226 8227@item @emph{Syntax}: 8228@code{RESULT = INT2(A)} 8229 8230@item @emph{Arguments}: 8231@multitable @columnfractions .15 .70 8232@item @var{A} @tab Shall be of type @code{INTEGER}, 8233@code{REAL}, or @code{COMPLEX}. 8234@end multitable 8235 8236@item @emph{Return value}: 8237The return value is a @code{INTEGER(2)} variable. 8238 8239@item @emph{See also}: 8240@ref{INT}, @ref{INT8}, @ref{LONG} 8241@end table 8242 8243 8244 8245@node INT8 8246@section @code{INT8} --- Convert to 64-bit integer type 8247@fnindex INT8 8248@cindex conversion, to integer 8249 8250@table @asis 8251@item @emph{Description}: 8252Convert to a @code{KIND=8} integer type. This is equivalent to the 8253standard @code{INT} intrinsic with an optional argument of 8254@code{KIND=8}, and is only included for backwards compatibility. 8255 8256@item @emph{Standard}: 8257GNU extension 8258 8259@item @emph{Class}: 8260Elemental function 8261 8262@item @emph{Syntax}: 8263@code{RESULT = INT8(A)} 8264 8265@item @emph{Arguments}: 8266@multitable @columnfractions .15 .70 8267@item @var{A} @tab Shall be of type @code{INTEGER}, 8268@code{REAL}, or @code{COMPLEX}. 8269@end multitable 8270 8271@item @emph{Return value}: 8272The return value is a @code{INTEGER(8)} variable. 8273 8274@item @emph{See also}: 8275@ref{INT}, @ref{INT2}, @ref{LONG} 8276@end table 8277 8278 8279 8280@node IOR 8281@section @code{IOR} --- Bitwise logical or 8282@fnindex IOR 8283@fnindex BIOR 8284@fnindex IIOR 8285@fnindex JIOR 8286@fnindex KIOR 8287@cindex bitwise logical or 8288@cindex logical or, bitwise 8289 8290@table @asis 8291@item @emph{Description}: 8292@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and 8293@var{J}. 8294 8295@item @emph{Standard}: 8296Fortran 95 and later, has overloads that are GNU extensions 8297 8298@item @emph{Class}: 8299Elemental function 8300 8301@item @emph{Syntax}: 8302@code{RESULT = IOR(I, J)} 8303 8304@item @emph{Arguments}: 8305@multitable @columnfractions .15 .70 8306@item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant. 8307@item @var{J} @tab The type shall be @code{INTEGER} with the same 8308kind type parameter as @var{I} or a boz-literal-constant. 8309@var{I} and @var{J} shall not both be boz-literal-constants. 8310@end multitable 8311 8312@item @emph{Return value}: 8313The return type is @code{INTEGER} with the kind type parameter of the 8314arguments. 8315A boz-literal-constant is converted to an @code{INTEGER} with the kind 8316type parameter of the other argument as-if a call to @ref{INT} occurred. 8317 8318@item @emph{Specific names}: 8319@multitable @columnfractions .20 .20 .20 .25 8320@item Name @tab Argument @tab Return type @tab Standard 8321@item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 8322@item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8323@item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8324@item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8325@item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8326@end multitable 8327 8328@item @emph{See also}: 8329@ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 8330@end table 8331 8332 8333 8334@node IPARITY 8335@section @code{IPARITY} --- Bitwise XOR of array elements 8336@fnindex IPARITY 8337@cindex array, parity 8338@cindex array, XOR 8339@cindex bits, XOR of array elements 8340 8341@table @asis 8342@item @emph{Description}: 8343Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along 8344dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 8345 8346@item @emph{Standard}: 8347Fortran 2008 and later 8348 8349@item @emph{Class}: 8350Transformational function 8351 8352@item @emph{Syntax}: 8353@multitable @columnfractions .80 8354@item @code{RESULT = IPARITY(ARRAY[, MASK])} 8355@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])} 8356@end multitable 8357 8358@item @emph{Arguments}: 8359@multitable @columnfractions .15 .70 8360@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 8361@item @var{DIM} @tab (Optional) shall be a scalar of type 8362@code{INTEGER} with a value in the range from 1 to n, where n 8363equals the rank of @var{ARRAY}. 8364@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 8365and either be a scalar or an array of the same shape as @var{ARRAY}. 8366@end multitable 8367 8368@item @emph{Return value}: 8369The result is of the same type as @var{ARRAY}. 8370 8371If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in 8372@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 8373the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 8374dimension @var{DIM} dropped is returned. 8375 8376@item @emph{Example}: 8377@smallexample 8378PROGRAM test_iparity 8379 INTEGER(1) :: a(2) 8380 8381 a(1) = b'00100100' 8382 a(2) = b'01101010' 8383 8384 ! prints 01001110 8385 PRINT '(b8.8)', IPARITY(a) 8386END PROGRAM 8387@end smallexample 8388 8389@item @emph{See also}: 8390@ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY} 8391@end table 8392 8393 8394 8395@node IRAND 8396@section @code{IRAND} --- Integer pseudo-random number 8397@fnindex IRAND 8398@cindex random number generation 8399 8400@table @asis 8401@item @emph{Description}: 8402@code{IRAND(FLAG)} returns a pseudo-random number from a uniform 8403distribution between 0 and a system-dependent limit (which is in most 8404cases 2147483647). If @var{FLAG} is 0, the next number 8405in the current sequence is returned; if @var{FLAG} is 1, the generator 8406is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 8407it is used as a new seed with @code{SRAND}. 8408 8409This intrinsic routine is provided for backwards compatibility with 8410GNU Fortran 77. It implements a simple modulo generator as provided 8411by @command{g77}. For new code, one should consider the use of 8412@ref{RANDOM_NUMBER} as it implements a superior algorithm. 8413 8414@item @emph{Standard}: 8415GNU extension 8416 8417@item @emph{Class}: 8418Function 8419 8420@item @emph{Syntax}: 8421@code{RESULT = IRAND(I)} 8422 8423@item @emph{Arguments}: 8424@multitable @columnfractions .15 .70 8425@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 8426@end multitable 8427 8428@item @emph{Return value}: 8429The return value is of @code{INTEGER(kind=4)} type. 8430 8431@item @emph{Example}: 8432@smallexample 8433program test_irand 8434 integer,parameter :: seed = 86456 8435 8436 call srand(seed) 8437 print *, irand(), irand(), irand(), irand() 8438 print *, irand(seed), irand(), irand(), irand() 8439end program test_irand 8440@end smallexample 8441 8442@end table 8443 8444 8445 8446@node IS_CONTIGUOUS 8447@section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous 8448@fnindex IS_IOSTAT_EOR 8449@cindex array, contiguity 8450 8451@table @asis 8452@item @emph{Description}: 8453@code{IS_CONTIGUOUS} tests whether an array is contiguous. 8454 8455@item @emph{Standard}: 8456Fortran 2008 and later 8457 8458@item @emph{Class}: 8459Inquiry function 8460 8461@item @emph{Syntax}: 8462@code{RESULT = IS_CONTIGUOUS(ARRAY)} 8463 8464@item @emph{Arguments}: 8465@multitable @columnfractions .15 .70 8466@item @var{ARRAY} @tab Shall be an array of any type. 8467@end multitable 8468 8469@item @emph{Return value}: 8470Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8471@var{ARRAY} is contiguous and false otherwise. 8472 8473@item @emph{Example}: 8474@smallexample 8475program test 8476 integer :: a(10) 8477 a = [1,2,3,4,5,6,7,8,9,10] 8478 call sub (a) ! every element, is contiguous 8479 call sub (a(::2)) ! every other element, is noncontiguous 8480contains 8481 subroutine sub (x) 8482 integer :: x(:) 8483 if (is_contiguous (x)) then 8484 write (*,*) 'X is contiguous' 8485 else 8486 write (*,*) 'X is not contiguous' 8487 end if 8488 end subroutine sub 8489end program test 8490@end smallexample 8491@end table 8492 8493 8494 8495@node IS_IOSTAT_END 8496@section @code{IS_IOSTAT_END} --- Test for end-of-file value 8497@fnindex IS_IOSTAT_END 8498@cindex @code{IOSTAT}, end of file 8499 8500@table @asis 8501@item @emph{Description}: 8502@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O 8503status ``end of file''. The function is equivalent to comparing the variable 8504with the @code{IOSTAT_END} parameter of the intrinsic module 8505@code{ISO_FORTRAN_ENV}. 8506 8507@item @emph{Standard}: 8508Fortran 2003 and later 8509 8510@item @emph{Class}: 8511Elemental function 8512 8513@item @emph{Syntax}: 8514@code{RESULT = IS_IOSTAT_END(I)} 8515 8516@item @emph{Arguments}: 8517@multitable @columnfractions .15 .70 8518@item @var{I} @tab Shall be of the type @code{INTEGER}. 8519@end multitable 8520 8521@item @emph{Return value}: 8522Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8523@var{I} has the value which indicates an end of file condition for 8524@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8525 8526@item @emph{Example}: 8527@smallexample 8528PROGRAM iostat 8529 IMPLICIT NONE 8530 INTEGER :: stat, i 8531 OPEN(88, FILE='test.dat') 8532 READ(88, *, IOSTAT=stat) i 8533 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE' 8534END PROGRAM 8535@end smallexample 8536@end table 8537 8538 8539 8540@node IS_IOSTAT_EOR 8541@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value 8542@fnindex IS_IOSTAT_EOR 8543@cindex @code{IOSTAT}, end of record 8544 8545@table @asis 8546@item @emph{Description}: 8547@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O 8548status ``end of record''. The function is equivalent to comparing the 8549variable with the @code{IOSTAT_EOR} parameter of the intrinsic module 8550@code{ISO_FORTRAN_ENV}. 8551 8552@item @emph{Standard}: 8553Fortran 2003 and later 8554 8555@item @emph{Class}: 8556Elemental function 8557 8558@item @emph{Syntax}: 8559@code{RESULT = IS_IOSTAT_EOR(I)} 8560 8561@item @emph{Arguments}: 8562@multitable @columnfractions .15 .70 8563@item @var{I} @tab Shall be of the type @code{INTEGER}. 8564@end multitable 8565 8566@item @emph{Return value}: 8567Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 8568@var{I} has the value which indicates an end of file condition for 8569@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 8570 8571@item @emph{Example}: 8572@smallexample 8573PROGRAM iostat 8574 IMPLICIT NONE 8575 INTEGER :: stat, i(50) 8576 OPEN(88, FILE='test.dat', FORM='UNFORMATTED') 8577 READ(88, IOSTAT=stat) i 8578 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD' 8579END PROGRAM 8580@end smallexample 8581@end table 8582 8583 8584@node ISATTY 8585@section @code{ISATTY} --- Whether a unit is a terminal device. 8586@fnindex ISATTY 8587@cindex system, terminal 8588 8589@table @asis 8590@item @emph{Description}: 8591Determine whether a unit is connected to a terminal device. 8592 8593@item @emph{Standard}: 8594GNU extension 8595 8596@item @emph{Class}: 8597Function 8598 8599@item @emph{Syntax}: 8600@code{RESULT = ISATTY(UNIT)} 8601 8602@item @emph{Arguments}: 8603@multitable @columnfractions .15 .70 8604@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 8605@end multitable 8606 8607@item @emph{Return value}: 8608Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal 8609device, @code{.FALSE.} otherwise. 8610 8611@item @emph{Example}: 8612@smallexample 8613PROGRAM test_isatty 8614 INTEGER(kind=1) :: unit 8615 DO unit = 1, 10 8616 write(*,*) isatty(unit=unit) 8617 END DO 8618END PROGRAM 8619@end smallexample 8620@item @emph{See also}: 8621@ref{TTYNAM} 8622@end table 8623 8624 8625 8626@node ISHFT 8627@section @code{ISHFT} --- Shift bits 8628@fnindex ISHFT 8629@fnindex BSHFT 8630@fnindex IISHFT 8631@fnindex JISHFT 8632@fnindex KISHFT 8633@cindex bits, shift 8634 8635@table @asis 8636@item @emph{Description}: 8637@code{ISHFT} returns a value corresponding to @var{I} with all of the 8638bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than 8639zero corresponds to a left shift, a value of zero corresponds to no 8640shift, and a value less than zero corresponds to a right shift. If the 8641absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the 8642value is undefined. Bits shifted out from the left end or right end are 8643lost; zeros are shifted in from the opposite end. 8644 8645@item @emph{Standard}: 8646Fortran 95 and later, has overloads that are GNU extensions 8647 8648@item @emph{Class}: 8649Elemental function 8650 8651@item @emph{Syntax}: 8652@code{RESULT = ISHFT(I, SHIFT)} 8653 8654@item @emph{Arguments}: 8655@multitable @columnfractions .15 .70 8656@item @var{I} @tab The type shall be @code{INTEGER}. 8657@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8658@end multitable 8659 8660@item @emph{Return value}: 8661The return value is of type @code{INTEGER} and of the same kind as 8662@var{I}. 8663 8664@item @emph{Specific names}: 8665@multitable @columnfractions .20 .20 .20 .25 8666@item Name @tab Argument @tab Return type @tab Standard 8667@item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 8668@item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8669@item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8670@item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8671@item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8672@end multitable 8673 8674@item @emph{See also}: 8675@ref{ISHFTC} 8676@end table 8677 8678 8679 8680@node ISHFTC 8681@section @code{ISHFTC} --- Shift bits circularly 8682@fnindex ISHFTC 8683@fnindex BSHFTC 8684@fnindex IISHFTC 8685@fnindex JISHFTC 8686@fnindex KISHFTC 8687@cindex bits, shift circular 8688 8689@table @asis 8690@item @emph{Description}: 8691@code{ISHFTC} returns a value corresponding to @var{I} with the 8692rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that 8693is, bits shifted out one end are shifted into the opposite end. A value 8694of @var{SHIFT} greater than zero corresponds to a left shift, a value of 8695zero corresponds to no shift, and a value less than zero corresponds to 8696a right shift. The absolute value of @var{SHIFT} must be less than 8697@var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be 8698equivalent to @code{BIT_SIZE(I)}. 8699 8700@item @emph{Standard}: 8701Fortran 95 and later, has overloads that are GNU extensions 8702 8703@item @emph{Class}: 8704Elemental function 8705 8706@item @emph{Syntax}: 8707@code{RESULT = ISHFTC(I, SHIFT [, SIZE])} 8708 8709@item @emph{Arguments}: 8710@multitable @columnfractions .15 .70 8711@item @var{I} @tab The type shall be @code{INTEGER}. 8712@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8713@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER}; 8714the value must be greater than zero and less than or equal to 8715@code{BIT_SIZE(I)}. 8716@end multitable 8717 8718@item @emph{Return value}: 8719The return value is of type @code{INTEGER} and of the same kind as 8720@var{I}. 8721 8722@item @emph{Specific names}: 8723@multitable @columnfractions .20 .20 .20 .25 8724@item Name @tab Argument @tab Return type @tab Standard 8725@item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 8726@item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 8727@item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 8728@item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 8729@item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 8730@end multitable 8731 8732@item @emph{See also}: 8733@ref{ISHFT} 8734@end table 8735 8736 8737 8738@node ISNAN 8739@section @code{ISNAN} --- Test for a NaN 8740@fnindex ISNAN 8741@cindex IEEE, ISNAN 8742 8743@table @asis 8744@item @emph{Description}: 8745@code{ISNAN} tests whether a floating-point value is an IEEE 8746Not-a-Number (NaN). 8747@item @emph{Standard}: 8748GNU extension 8749 8750@item @emph{Class}: 8751Elemental function 8752 8753@item @emph{Syntax}: 8754@code{ISNAN(X)} 8755 8756@item @emph{Arguments}: 8757@multitable @columnfractions .15 .70 8758@item @var{X} @tab Variable of the type @code{REAL}. 8759 8760@end multitable 8761 8762@item @emph{Return value}: 8763Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE} 8764if @var{X} is a NaN and @code{FALSE} otherwise. 8765 8766@item @emph{Example}: 8767@smallexample 8768program test_nan 8769 implicit none 8770 real :: x 8771 x = -1.0 8772 x = sqrt(x) 8773 if (isnan(x)) stop '"x" is a NaN' 8774end program test_nan 8775@end smallexample 8776@end table 8777 8778 8779 8780@node ITIME 8781@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) 8782@fnindex ITIME 8783@cindex time, current 8784@cindex current time 8785 8786@table @asis 8787@item @emph{Description}: 8788@code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the 8789current local time. The hour (in the range 1-24), minute (in the range 1-60), 8790and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES}, 8791respectively. 8792 8793This intrinsic routine is provided for backwards compatibility with 8794GNU Fortran 77. In new code, programmers should consider the use of 8795the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 8796standard. 8797 8798@item @emph{Standard}: 8799GNU extension 8800 8801@item @emph{Class}: 8802Subroutine 8803 8804@item @emph{Syntax}: 8805@code{CALL ITIME(VALUES)} 8806 8807@item @emph{Arguments}: 8808@multitable @columnfractions .15 .70 8809@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} 8810and the kind shall be the default integer kind. 8811@end multitable 8812 8813@item @emph{Return value}: 8814Does not return anything. 8815 8816 8817@item @emph{Example}: 8818@smallexample 8819program test_itime 8820 integer, dimension(3) :: tarray 8821 call itime(tarray) 8822 print *, tarray(1) 8823 print *, tarray(2) 8824 print *, tarray(3) 8825end program test_itime 8826@end smallexample 8827 8828@item @emph{See also}: 8829@ref{DATE_AND_TIME} 8830@end table 8831 8832 8833 8834@node KILL 8835@section @code{KILL} --- Send a signal to a process 8836@fnindex KILL 8837 8838@table @asis 8839@item @emph{Description}: 8840@item @emph{Standard}: 8841Sends the signal specified by @var{SIG} to the process @var{PID}. 8842See @code{kill(2)}. 8843 8844This intrinsic is provided in both subroutine and function forms; 8845however, only one form can be used in any given program unit. 8846 8847@item @emph{Class}: 8848Subroutine, function 8849 8850@item @emph{Syntax}: 8851@multitable @columnfractions .80 8852@item @code{CALL KILL(PID, SIG [, STATUS])} 8853@item @code{STATUS = KILL(PID, SIG)} 8854@end multitable 8855 8856@item @emph{Arguments}: 8857@multitable @columnfractions .15 .70 8858@item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 8859@item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}. 8860@item @var{STATUS} @tab [Subroutine](Optional) 8861Shall be a scalar @code{INTEGER}. 8862Returns 0 on success; otherwise a system-specific error code is returned. 8863@item @var{STATUS} @tab [Function] The kind type parameter is that of 8864@code{pid}. 8865Returns 0 on success; otherwise a system-specific error code is returned. 8866@end multitable 8867 8868@item @emph{See also}: 8869@ref{ABORT}, @ref{EXIT} 8870@end table 8871 8872 8873@node KIND 8874@section @code{KIND} --- Kind of an entity 8875@fnindex KIND 8876@cindex kind 8877 8878@table @asis 8879@item @emph{Description}: 8880@code{KIND(X)} returns the kind value of the entity @var{X}. 8881 8882@item @emph{Standard}: 8883Fortran 95 and later 8884 8885@item @emph{Class}: 8886Inquiry function 8887 8888@item @emph{Syntax}: 8889@code{K = KIND(X)} 8890 8891@item @emph{Arguments}: 8892@multitable @columnfractions .15 .70 8893@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER}, 8894@code{REAL}, @code{COMPLEX} or @code{CHARACTER}. 8895@end multitable 8896 8897@item @emph{Return value}: 8898The return value is a scalar of type @code{INTEGER} and of the default 8899integer kind. 8900 8901@item @emph{Example}: 8902@smallexample 8903program test_kind 8904 integer,parameter :: kc = kind(' ') 8905 integer,parameter :: kl = kind(.true.) 8906 8907 print *, "The default character kind is ", kc 8908 print *, "The default logical kind is ", kl 8909end program test_kind 8910@end smallexample 8911 8912@end table 8913 8914 8915 8916@node LBOUND 8917@section @code{LBOUND} --- Lower dimension bounds of an array 8918@fnindex LBOUND 8919@cindex array, lower bound 8920 8921@table @asis 8922@item @emph{Description}: 8923Returns the lower bounds of an array, or a single lower bound 8924along the @var{DIM} dimension. 8925@item @emph{Standard}: 8926Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 8927 8928@item @emph{Class}: 8929Inquiry function 8930 8931@item @emph{Syntax}: 8932@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])} 8933 8934@item @emph{Arguments}: 8935@multitable @columnfractions .15 .70 8936@item @var{ARRAY} @tab Shall be an array, of any type. 8937@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 8938@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8939expression indicating the kind parameter of the result. 8940@end multitable 8941 8942@item @emph{Return value}: 8943The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8944@var{KIND} is absent, the return value is of default integer kind. 8945If @var{DIM} is absent, the result is an array of the lower bounds of 8946@var{ARRAY}. If @var{DIM} is present, the result is a scalar 8947corresponding to the lower bound of the array along that dimension. If 8948@var{ARRAY} is an expression rather than a whole array or array 8949structure component, or if it has a zero extent along the relevant 8950dimension, the lower bound is taken to be 1. 8951 8952@item @emph{See also}: 8953@ref{UBOUND}, @ref{LCOBOUND} 8954@end table 8955 8956 8957 8958@node LCOBOUND 8959@section @code{LCOBOUND} --- Lower codimension bounds of an array 8960@fnindex LCOBOUND 8961@cindex coarray, lower bound 8962 8963@table @asis 8964@item @emph{Description}: 8965Returns the lower bounds of a coarray, or a single lower cobound 8966along the @var{DIM} codimension. 8967@item @emph{Standard}: 8968Fortran 2008 and later 8969 8970@item @emph{Class}: 8971Inquiry function 8972 8973@item @emph{Syntax}: 8974@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])} 8975 8976@item @emph{Arguments}: 8977@multitable @columnfractions .15 .70 8978@item @var{ARRAY} @tab Shall be an coarray, of any type. 8979@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 8980@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8981expression indicating the kind parameter of the result. 8982@end multitable 8983 8984@item @emph{Return value}: 8985The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8986@var{KIND} is absent, the return value is of default integer kind. 8987If @var{DIM} is absent, the result is an array of the lower cobounds of 8988@var{COARRAY}. If @var{DIM} is present, the result is a scalar 8989corresponding to the lower cobound of the array along that codimension. 8990 8991@item @emph{See also}: 8992@ref{UCOBOUND}, @ref{LBOUND} 8993@end table 8994 8995 8996 8997@node LEADZ 8998@section @code{LEADZ} --- Number of leading zero bits of an integer 8999@fnindex LEADZ 9000@cindex zero bits 9001 9002@table @asis 9003@item @emph{Description}: 9004@code{LEADZ} returns the number of leading zero bits of an integer. 9005 9006@item @emph{Standard}: 9007Fortran 2008 and later 9008 9009@item @emph{Class}: 9010Elemental function 9011 9012@item @emph{Syntax}: 9013@code{RESULT = LEADZ(I)} 9014 9015@item @emph{Arguments}: 9016@multitable @columnfractions .15 .70 9017@item @var{I} @tab Shall be of type @code{INTEGER}. 9018@end multitable 9019 9020@item @emph{Return value}: 9021The type of the return value is the default @code{INTEGER}. 9022If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 9023 9024@item @emph{Example}: 9025@smallexample 9026PROGRAM test_leadz 9027 WRITE (*,*) BIT_SIZE(1) ! prints 32 9028 WRITE (*,*) LEADZ(1) ! prints 31 9029END PROGRAM 9030@end smallexample 9031 9032@item @emph{See also}: 9033@ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR} 9034@end table 9035 9036 9037 9038@node LEN 9039@section @code{LEN} --- Length of a character entity 9040@fnindex LEN 9041@cindex string, length 9042 9043@table @asis 9044@item @emph{Description}: 9045Returns the length of a character string. If @var{STRING} is an array, 9046the length of an element of @var{STRING} is returned. Note that 9047@var{STRING} need not be defined when this intrinsic is invoked, since 9048only the length, not the content, of @var{STRING} is needed. 9049 9050@item @emph{Standard}: 9051Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 9052 9053@item @emph{Class}: 9054Inquiry function 9055 9056@item @emph{Syntax}: 9057@code{L = LEN(STRING [, KIND])} 9058 9059@item @emph{Arguments}: 9060@multitable @columnfractions .15 .70 9061@item @var{STRING} @tab Shall be a scalar or array of type 9062@code{CHARACTER}, with @code{INTENT(IN)} 9063@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9064expression indicating the kind parameter of the result. 9065@end multitable 9066 9067@item @emph{Return value}: 9068The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9069@var{KIND} is absent, the return value is of default integer kind. 9070 9071 9072@item @emph{Specific names}: 9073@multitable @columnfractions .20 .20 .20 .25 9074@item Name @tab Argument @tab Return type @tab Standard 9075@item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later 9076@end multitable 9077 9078 9079@item @emph{See also}: 9080@ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR} 9081@end table 9082 9083 9084 9085@node LEN_TRIM 9086@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters 9087@fnindex LEN_TRIM 9088@cindex string, length, without trailing whitespace 9089 9090@table @asis 9091@item @emph{Description}: 9092Returns the length of a character string, ignoring any trailing blanks. 9093 9094@item @emph{Standard}: 9095Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 9096 9097@item @emph{Class}: 9098Elemental function 9099 9100@item @emph{Syntax}: 9101@code{RESULT = LEN_TRIM(STRING [, KIND])} 9102 9103@item @emph{Arguments}: 9104@multitable @columnfractions .15 .70 9105@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9106with @code{INTENT(IN)} 9107@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9108expression indicating the kind parameter of the result. 9109@end multitable 9110 9111@item @emph{Return value}: 9112The return value is of type @code{INTEGER} and of kind @var{KIND}. If 9113@var{KIND} is absent, the return value is of default integer kind. 9114 9115@item @emph{See also}: 9116@ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR} 9117@end table 9118 9119 9120 9121@node LGE 9122@section @code{LGE} --- Lexical greater than or equal 9123@fnindex LGE 9124@cindex lexical comparison of strings 9125@cindex string, comparison 9126 9127@table @asis 9128@item @emph{Description}: 9129Determines whether one string is lexically greater than or equal to 9130another string, where the two strings are interpreted as containing 9131ASCII character codes. If the String A and String B are not the same 9132length, the shorter is compared as if spaces were appended to it to form 9133a value that has the same length as the longer. 9134 9135In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9136@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9137operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9138that the latter use the processor's character ordering (which is not 9139ASCII on some targets), whereas the former always use the ASCII 9140ordering. 9141 9142@item @emph{Standard}: 9143Fortran 77 and later 9144 9145@item @emph{Class}: 9146Elemental function 9147 9148@item @emph{Syntax}: 9149@code{RESULT = LGE(STRING_A, STRING_B)} 9150 9151@item @emph{Arguments}: 9152@multitable @columnfractions .15 .70 9153@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9154@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9155@end multitable 9156 9157@item @emph{Return value}: 9158Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.} 9159otherwise, based on the ASCII ordering. 9160 9161@item @emph{Specific names}: 9162@multitable @columnfractions .20 .20 .20 .25 9163@item Name @tab Argument @tab Return type @tab Standard 9164@item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9165@end multitable 9166 9167@item @emph{See also}: 9168@ref{LGT}, @ref{LLE}, @ref{LLT} 9169@end table 9170 9171 9172 9173@node LGT 9174@section @code{LGT} --- Lexical greater than 9175@fnindex LGT 9176@cindex lexical comparison of strings 9177@cindex string, comparison 9178 9179@table @asis 9180@item @emph{Description}: 9181Determines whether one string is lexically greater than another string, 9182where the two strings are interpreted as containing ASCII character 9183codes. If the String A and String B are not the same length, the 9184shorter is compared as if spaces were appended to it to form a value 9185that has the same length as the longer. 9186 9187In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9188@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9189operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9190that the latter use the processor's character ordering (which is not 9191ASCII on some targets), whereas the former always use the ASCII 9192ordering. 9193 9194@item @emph{Standard}: 9195Fortran 77 and later 9196 9197@item @emph{Class}: 9198Elemental function 9199 9200@item @emph{Syntax}: 9201@code{RESULT = LGT(STRING_A, STRING_B)} 9202 9203@item @emph{Arguments}: 9204@multitable @columnfractions .15 .70 9205@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9206@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9207@end multitable 9208 9209@item @emph{Return value}: 9210Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.} 9211otherwise, based on the ASCII ordering. 9212 9213@item @emph{Specific names}: 9214@multitable @columnfractions .20 .20 .20 .25 9215@item Name @tab Argument @tab Return type @tab Standard 9216@item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9217@end multitable 9218 9219@item @emph{See also}: 9220@ref{LGE}, @ref{LLE}, @ref{LLT} 9221@end table 9222 9223 9224 9225@node LINK 9226@section @code{LINK} --- Create a hard link 9227@fnindex LINK 9228@cindex file system, create link 9229@cindex file system, hard link 9230 9231@table @asis 9232@item @emph{Description}: 9233Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null 9234character (@code{CHAR(0)}) can be used to mark the end of the names in 9235@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 9236names are ignored. If the @var{STATUS} argument is supplied, it 9237contains 0 on success or a nonzero error code upon return; see 9238@code{link(2)}. 9239 9240This intrinsic is provided in both subroutine and function forms; 9241however, only one form can be used in any given program unit. 9242 9243@item @emph{Standard}: 9244GNU extension 9245 9246@item @emph{Class}: 9247Subroutine, function 9248 9249@item @emph{Syntax}: 9250@multitable @columnfractions .80 9251@item @code{CALL LINK(PATH1, PATH2 [, STATUS])} 9252@item @code{STATUS = LINK(PATH1, PATH2)} 9253@end multitable 9254 9255@item @emph{Arguments}: 9256@multitable @columnfractions .15 .70 9257@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 9258@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 9259@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 9260@end multitable 9261 9262@item @emph{See also}: 9263@ref{SYMLNK}, @ref{UNLINK} 9264@end table 9265 9266 9267 9268@node LLE 9269@section @code{LLE} --- Lexical less than or equal 9270@fnindex LLE 9271@cindex lexical comparison of strings 9272@cindex string, comparison 9273 9274@table @asis 9275@item @emph{Description}: 9276Determines whether one string is lexically less than or equal to another 9277string, where the two strings are interpreted as containing ASCII 9278character codes. If the String A and String B are not the same length, 9279the shorter is compared as if spaces were appended to it to form a value 9280that has the same length as the longer. 9281 9282In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9283@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9284operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9285that the latter use the processor's character ordering (which is not 9286ASCII on some targets), whereas the former always use the ASCII 9287ordering. 9288 9289@item @emph{Standard}: 9290Fortran 77 and later 9291 9292@item @emph{Class}: 9293Elemental function 9294 9295@item @emph{Syntax}: 9296@code{RESULT = LLE(STRING_A, STRING_B)} 9297 9298@item @emph{Arguments}: 9299@multitable @columnfractions .15 .70 9300@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9301@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9302@end multitable 9303 9304@item @emph{Return value}: 9305Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.} 9306otherwise, based on the ASCII ordering. 9307 9308@item @emph{Specific names}: 9309@multitable @columnfractions .20 .20 .20 .25 9310@item Name @tab Argument @tab Return type @tab Standard 9311@item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9312@end multitable 9313 9314@item @emph{See also}: 9315@ref{LGE}, @ref{LGT}, @ref{LLT} 9316@end table 9317 9318 9319 9320@node LLT 9321@section @code{LLT} --- Lexical less than 9322@fnindex LLT 9323@cindex lexical comparison of strings 9324@cindex string, comparison 9325 9326@table @asis 9327@item @emph{Description}: 9328Determines whether one string is lexically less than another string, 9329where the two strings are interpreted as containing ASCII character 9330codes. If the String A and String B are not the same length, the 9331shorter is compared as if spaces were appended to it to form a value 9332that has the same length as the longer. 9333 9334In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 9335@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 9336operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 9337that the latter use the processor's character ordering (which is not 9338ASCII on some targets), whereas the former always use the ASCII 9339ordering. 9340 9341@item @emph{Standard}: 9342Fortran 77 and later 9343 9344@item @emph{Class}: 9345Elemental function 9346 9347@item @emph{Syntax}: 9348@code{RESULT = LLT(STRING_A, STRING_B)} 9349 9350@item @emph{Arguments}: 9351@multitable @columnfractions .15 .70 9352@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 9353@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 9354@end multitable 9355 9356@item @emph{Return value}: 9357Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.} 9358otherwise, based on the ASCII ordering. 9359 9360@item @emph{Specific names}: 9361@multitable @columnfractions .20 .20 .20 .25 9362@item Name @tab Argument @tab Return type @tab Standard 9363@item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 9364@end multitable 9365 9366@item @emph{See also}: 9367@ref{LGE}, @ref{LGT}, @ref{LLE} 9368@end table 9369 9370 9371 9372@node LNBLNK 9373@section @code{LNBLNK} --- Index of the last non-blank character in a string 9374@fnindex LNBLNK 9375@cindex string, find non-blank character 9376 9377@table @asis 9378@item @emph{Description}: 9379Returns the length of a character string, ignoring any trailing blanks. 9380This is identical to the standard @code{LEN_TRIM} intrinsic, and is only 9381included for backwards compatibility. 9382 9383@item @emph{Standard}: 9384GNU extension 9385 9386@item @emph{Class}: 9387Elemental function 9388 9389@item @emph{Syntax}: 9390@code{RESULT = LNBLNK(STRING)} 9391 9392@item @emph{Arguments}: 9393@multitable @columnfractions .15 .70 9394@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 9395with @code{INTENT(IN)} 9396@end multitable 9397 9398@item @emph{Return value}: 9399The return value is of @code{INTEGER(kind=4)} type. 9400 9401@item @emph{See also}: 9402@ref{INDEX intrinsic}, @ref{LEN_TRIM} 9403@end table 9404 9405 9406 9407@node LOC 9408@section @code{LOC} --- Returns the address of a variable 9409@fnindex LOC 9410@cindex location of a variable in memory 9411 9412@table @asis 9413@item @emph{Description}: 9414@code{LOC(X)} returns the address of @var{X} as an integer. 9415 9416@item @emph{Standard}: 9417GNU extension 9418 9419@item @emph{Class}: 9420Inquiry function 9421 9422@item @emph{Syntax}: 9423@code{RESULT = LOC(X)} 9424 9425@item @emph{Arguments}: 9426@multitable @columnfractions .15 .70 9427@item @var{X} @tab Variable of any type. 9428@end multitable 9429 9430@item @emph{Return value}: 9431The return value is of type @code{INTEGER}, with a @code{KIND} 9432corresponding to the size (in bytes) of a memory address on the target 9433machine. 9434 9435@item @emph{Example}: 9436@smallexample 9437program test_loc 9438 integer :: i 9439 real :: r 9440 i = loc(r) 9441 print *, i 9442end program test_loc 9443@end smallexample 9444@end table 9445 9446 9447 9448@node LOG 9449@section @code{LOG} --- Natural logarithm function 9450@fnindex LOG 9451@fnindex ALOG 9452@fnindex DLOG 9453@fnindex CLOG 9454@fnindex ZLOG 9455@fnindex CDLOG 9456@cindex exponential function, inverse 9457@cindex logarithm function 9458@cindex natural logarithm function 9459 9460@table @asis 9461@item @emph{Description}: 9462@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the 9463logarithm to the base @math{e}. 9464 9465@item @emph{Standard}: 9466Fortran 77 and later 9467 9468@item @emph{Class}: 9469Elemental function 9470 9471@item @emph{Syntax}: 9472@code{RESULT = LOG(X)} 9473 9474@item @emph{Arguments}: 9475@multitable @columnfractions .15 .70 9476@item @var{X} @tab The type shall be @code{REAL} or 9477@code{COMPLEX}. 9478@end multitable 9479 9480@item @emph{Return value}: 9481The return value is of type @code{REAL} or @code{COMPLEX}. 9482The kind type parameter is the same as @var{X}. 9483If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range 9484@math{-\pi < \omega \leq \pi}. 9485 9486@item @emph{Example}: 9487@smallexample 9488program test_log 9489 real(8) :: x = 2.7182818284590451_8 9490 complex :: z = (1.0, 2.0) 9491 x = log(x) ! will yield (approximately) 1 9492 z = log(z) 9493end program test_log 9494@end smallexample 9495 9496@item @emph{Specific names}: 9497@multitable @columnfractions .20 .20 .20 .25 9498@item Name @tab Argument @tab Return type @tab Standard 9499@item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu 9500@item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu 9501@item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu 9502@item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 9503@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 9504@end multitable 9505@end table 9506 9507 9508 9509@node LOG10 9510@section @code{LOG10} --- Base 10 logarithm function 9511@fnindex LOG10 9512@fnindex ALOG10 9513@fnindex DLOG10 9514@cindex exponential function, inverse 9515@cindex logarithm function with base 10 9516@cindex base 10 logarithm function 9517 9518@table @asis 9519@item @emph{Description}: 9520@code{LOG10(X)} computes the base 10 logarithm of @var{X}. 9521 9522@item @emph{Standard}: 9523Fortran 77 and later 9524 9525@item @emph{Class}: 9526Elemental function 9527 9528@item @emph{Syntax}: 9529@code{RESULT = LOG10(X)} 9530 9531@item @emph{Arguments}: 9532@multitable @columnfractions .15 .70 9533@item @var{X} @tab The type shall be @code{REAL}. 9534@end multitable 9535 9536@item @emph{Return value}: 9537The return value is of type @code{REAL} or @code{COMPLEX}. 9538The kind type parameter is the same as @var{X}. 9539 9540@item @emph{Example}: 9541@smallexample 9542program test_log10 9543 real(8) :: x = 10.0_8 9544 x = log10(x) 9545end program test_log10 9546@end smallexample 9547 9548@item @emph{Specific names}: 9549@multitable @columnfractions .20 .20 .20 .25 9550@item Name @tab Argument @tab Return type @tab Standard 9551@item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 9552@item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 9553@end multitable 9554@end table 9555 9556 9557 9558@node LOG_GAMMA 9559@section @code{LOG_GAMMA} --- Logarithm of the Gamma function 9560@fnindex LOG_GAMMA 9561@fnindex LGAMMA 9562@fnindex ALGAMA 9563@fnindex DLGAMA 9564@cindex Gamma function, logarithm of 9565 9566@table @asis 9567@item @emph{Description}: 9568@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value 9569of the Gamma (@math{\Gamma}) function. 9570 9571@item @emph{Standard}: 9572Fortran 2008 and later 9573 9574@item @emph{Class}: 9575Elemental function 9576 9577@item @emph{Syntax}: 9578@code{X = LOG_GAMMA(X)} 9579 9580@item @emph{Arguments}: 9581@multitable @columnfractions .15 .70 9582@item @var{X} @tab Shall be of type @code{REAL} and neither zero 9583nor a negative integer. 9584@end multitable 9585 9586@item @emph{Return value}: 9587The return value is of type @code{REAL} of the same kind as @var{X}. 9588 9589@item @emph{Example}: 9590@smallexample 9591program test_log_gamma 9592 real :: x = 1.0 9593 x = lgamma(x) ! returns 0.0 9594end program test_log_gamma 9595@end smallexample 9596 9597@item @emph{Specific names}: 9598@multitable @columnfractions .20 .20 .20 .25 9599@item Name @tab Argument @tab Return type @tab Standard 9600@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 9601@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 9602@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 9603@end multitable 9604 9605@item @emph{See also}: 9606Gamma function: @ref{GAMMA} 9607 9608@end table 9609 9610 9611 9612@node LOGICAL 9613@section @code{LOGICAL} --- Convert to logical type 9614@fnindex LOGICAL 9615@cindex conversion, to logical 9616 9617@table @asis 9618@item @emph{Description}: 9619Converts one kind of @code{LOGICAL} variable to another. 9620 9621@item @emph{Standard}: 9622Fortran 95 and later 9623 9624@item @emph{Class}: 9625Elemental function 9626 9627@item @emph{Syntax}: 9628@code{RESULT = LOGICAL(L [, KIND])} 9629 9630@item @emph{Arguments}: 9631@multitable @columnfractions .15 .70 9632@item @var{L} @tab The type shall be @code{LOGICAL}. 9633@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 9634expression indicating the kind parameter of the result. 9635@end multitable 9636 9637@item @emph{Return value}: 9638The return value is a @code{LOGICAL} value equal to @var{L}, with a 9639kind corresponding to @var{KIND}, or of the default logical kind if 9640@var{KIND} is not given. 9641 9642@item @emph{See also}: 9643@ref{INT}, @ref{REAL}, @ref{CMPLX} 9644@end table 9645 9646 9647 9648@node LONG 9649@section @code{LONG} --- Convert to integer type 9650@fnindex LONG 9651@cindex conversion, to integer 9652 9653@table @asis 9654@item @emph{Description}: 9655Convert to a @code{KIND=4} integer type, which is the same size as a C 9656@code{long} integer. This is equivalent to the standard @code{INT} 9657intrinsic with an optional argument of @code{KIND=4}, and is only 9658included for backwards compatibility. 9659 9660@item @emph{Standard}: 9661GNU extension 9662 9663@item @emph{Class}: 9664Elemental function 9665 9666@item @emph{Syntax}: 9667@code{RESULT = LONG(A)} 9668 9669@item @emph{Arguments}: 9670@multitable @columnfractions .15 .70 9671@item @var{A} @tab Shall be of type @code{INTEGER}, 9672@code{REAL}, or @code{COMPLEX}. 9673@end multitable 9674 9675@item @emph{Return value}: 9676The return value is a @code{INTEGER(4)} variable. 9677 9678@item @emph{See also}: 9679@ref{INT}, @ref{INT2}, @ref{INT8} 9680@end table 9681 9682 9683 9684@node LSHIFT 9685@section @code{LSHIFT} --- Left shift bits 9686@fnindex LSHIFT 9687@cindex bits, shift left 9688 9689@table @asis 9690@item @emph{Description}: 9691@code{LSHIFT} returns a value corresponding to @var{I} with all of the 9692bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be 9693nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 9694the result value is undefined. Bits shifted out from the left end are 9695lost; zeros are shifted in from the opposite end. 9696 9697This function has been superseded by the @code{ISHFT} intrinsic, which 9698is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic, 9699which is standard in Fortran 2008 and later. 9700 9701@item @emph{Standard}: 9702GNU extension 9703 9704@item @emph{Class}: 9705Elemental function 9706 9707@item @emph{Syntax}: 9708@code{RESULT = LSHIFT(I, SHIFT)} 9709 9710@item @emph{Arguments}: 9711@multitable @columnfractions .15 .70 9712@item @var{I} @tab The type shall be @code{INTEGER}. 9713@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 9714@end multitable 9715 9716@item @emph{Return value}: 9717The return value is of type @code{INTEGER} and of the same kind as 9718@var{I}. 9719 9720@item @emph{See also}: 9721@ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL}, 9722@ref{SHIFTR} 9723 9724@end table 9725 9726 9727 9728@node LSTAT 9729@section @code{LSTAT} --- Get file status 9730@fnindex LSTAT 9731@cindex file system, file status 9732 9733@table @asis 9734@item @emph{Description}: 9735@code{LSTAT} is identical to @ref{STAT}, except that if path is a 9736symbolic link, then the link itself is statted, not the file that it 9737refers to. 9738 9739The elements in @code{VALUES} are the same as described by @ref{STAT}. 9740 9741This intrinsic is provided in both subroutine and function forms; 9742however, only one form can be used in any given program unit. 9743 9744@item @emph{Standard}: 9745GNU extension 9746 9747@item @emph{Class}: 9748Subroutine, function 9749 9750@item @emph{Syntax}: 9751@multitable @columnfractions .80 9752@item @code{CALL LSTAT(NAME, VALUES [, STATUS])} 9753@item @code{STATUS = LSTAT(NAME, VALUES)} 9754@end multitable 9755 9756@item @emph{Arguments}: 9757@multitable @columnfractions .15 .70 9758@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default 9759kind, a valid path within the file system. 9760@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 9761@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. 9762Returns 0 on success and a system specific error code otherwise. 9763@end multitable 9764 9765@item @emph{Example}: 9766See @ref{STAT} for an example. 9767 9768@item @emph{See also}: 9769To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT} 9770@end table 9771 9772 9773 9774@node LTIME 9775@section @code{LTIME} --- Convert time to local time info 9776@fnindex LTIME 9777@cindex time, conversion to local time info 9778 9779@table @asis 9780@item @emph{Description}: 9781Given a system time value @var{TIME} (as provided by the @ref{TIME} 9782intrinsic), fills @var{VALUES} with values extracted from it appropriate 9783to the local time zone using @code{localtime(3)}. 9784 9785This intrinsic routine is provided for backwards compatibility with 9786GNU Fortran 77. In new code, programmers should consider the use of 9787the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 9788standard. 9789 9790@item @emph{Standard}: 9791GNU extension 9792 9793@item @emph{Class}: 9794Subroutine 9795 9796@item @emph{Syntax}: 9797@code{CALL LTIME(TIME, VALUES)} 9798 9799@item @emph{Arguments}: 9800@multitable @columnfractions .15 .70 9801@item @var{TIME} @tab An @code{INTEGER} scalar expression 9802corresponding to a system time, with @code{INTENT(IN)}. 9803@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 9804with @code{INTENT(OUT)}. 9805@end multitable 9806 9807@item @emph{Return value}: 9808The elements of @var{VALUES} are assigned as follows: 9809@enumerate 9810@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 9811seconds 9812@item Minutes after the hour, range 0--59 9813@item Hours past midnight, range 0--23 9814@item Day of month, range 1--31 9815@item Number of months since January, range 0--11 9816@item Years since 1900 9817@item Number of days since Sunday, range 0--6 9818@item Days since January 1, range 0--365 9819@item Daylight savings indicator: positive if daylight savings is in 9820effect, zero if not, and negative if the information is not available. 9821@end enumerate 9822 9823@item @emph{See also}: 9824@ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8} 9825 9826@end table 9827 9828 9829 9830@node MALLOC 9831@section @code{MALLOC} --- Allocate dynamic memory 9832@fnindex MALLOC 9833@cindex pointer, cray 9834 9835@table @asis 9836@item @emph{Description}: 9837@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and 9838returns the address of the allocated memory. The @code{MALLOC} intrinsic 9839is an extension intended to be used with Cray pointers, and is provided 9840in GNU Fortran to allow the user to compile legacy code. For new code 9841using Fortran 95 pointers, the memory allocation intrinsic is 9842@code{ALLOCATE}. 9843 9844@item @emph{Standard}: 9845GNU extension 9846 9847@item @emph{Class}: 9848Function 9849 9850@item @emph{Syntax}: 9851@code{PTR = MALLOC(SIZE)} 9852 9853@item @emph{Arguments}: 9854@multitable @columnfractions .15 .70 9855@item @var{SIZE} @tab The type shall be @code{INTEGER}. 9856@end multitable 9857 9858@item @emph{Return value}: 9859The return value is of type @code{INTEGER(K)}, with @var{K} such that 9860variables of type @code{INTEGER(K)} have the same size as 9861C pointers (@code{sizeof(void *)}). 9862 9863@item @emph{Example}: 9864The following example demonstrates the use of @code{MALLOC} and 9865@code{FREE} with Cray pointers. 9866 9867@smallexample 9868program test_malloc 9869 implicit none 9870 integer i 9871 real*8 x(*), z 9872 pointer(ptr_x,x) 9873 9874 ptr_x = malloc(20*8) 9875 do i = 1, 20 9876 x(i) = sqrt(1.0d0 / i) 9877 end do 9878 z = 0 9879 do i = 1, 20 9880 z = z + x(i) 9881 print *, z 9882 end do 9883 call free(ptr_x) 9884end program test_malloc 9885@end smallexample 9886 9887@item @emph{See also}: 9888@ref{FREE} 9889@end table 9890 9891 9892 9893@node MASKL 9894@section @code{MASKL} --- Left justified mask 9895@fnindex MASKL 9896@cindex mask, left justified 9897 9898@table @asis 9899@item @emph{Description}: 9900@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the 9901remaining bits set to 0. 9902 9903@item @emph{Standard}: 9904Fortran 2008 and later 9905 9906@item @emph{Class}: 9907Elemental function 9908 9909@item @emph{Syntax}: 9910@code{RESULT = MASKL(I[, KIND])} 9911 9912@item @emph{Arguments}: 9913@multitable @columnfractions .15 .70 9914@item @var{I} @tab Shall be of type @code{INTEGER}. 9915@item @var{KIND} @tab Shall be a scalar constant expression of type 9916@code{INTEGER}. 9917@end multitable 9918 9919@item @emph{Return value}: 9920The return value is of type @code{INTEGER}. If @var{KIND} is present, it 9921specifies the kind value of the return type; otherwise, it is of the 9922default integer kind. 9923 9924@item @emph{See also}: 9925@ref{MASKR} 9926@end table 9927 9928 9929 9930@node MASKR 9931@section @code{MASKR} --- Right justified mask 9932@fnindex MASKR 9933@cindex mask, right justified 9934 9935@table @asis 9936@item @emph{Description}: 9937@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the 9938remaining bits set to 0. 9939 9940@item @emph{Standard}: 9941Fortran 2008 and later 9942 9943@item @emph{Class}: 9944Elemental function 9945 9946@item @emph{Syntax}: 9947@code{RESULT = MASKR(I[, KIND])} 9948 9949@item @emph{Arguments}: 9950@multitable @columnfractions .15 .70 9951@item @var{I} @tab Shall be of type @code{INTEGER}. 9952@item @var{KIND} @tab Shall be a scalar constant expression of type 9953@code{INTEGER}. 9954@end multitable 9955 9956@item @emph{Return value}: 9957The return value is of type @code{INTEGER}. If @var{KIND} is present, it 9958specifies the kind value of the return type; otherwise, it is of the 9959default integer kind. 9960 9961@item @emph{See also}: 9962@ref{MASKL} 9963@end table 9964 9965 9966 9967@node MATMUL 9968@section @code{MATMUL} --- matrix multiplication 9969@fnindex MATMUL 9970@cindex matrix multiplication 9971@cindex product, matrix 9972 9973@table @asis 9974@item @emph{Description}: 9975Performs a matrix multiplication on numeric or logical arguments. 9976 9977@item @emph{Standard}: 9978Fortran 95 and later 9979 9980@item @emph{Class}: 9981Transformational function 9982 9983@item @emph{Syntax}: 9984@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)} 9985 9986@item @emph{Arguments}: 9987@multitable @columnfractions .15 .70 9988@item @var{MATRIX_A} @tab An array of @code{INTEGER}, 9989@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of 9990one or two. 9991@item @var{MATRIX_B} @tab An array of @code{INTEGER}, 9992@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric 9993type; otherwise, an array of @code{LOGICAL} type. The rank shall be one 9994or two, and the first (or only) dimension of @var{MATRIX_B} shall be 9995equal to the last (or only) dimension of @var{MATRIX_A}. 9996@var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays. 9997@end multitable 9998 9999@item @emph{Return value}: 10000The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and 10001kind of the result follow the usual type and kind promotion rules, as 10002for the @code{*} or @code{.AND.} operators. 10003 10004@item @emph{See also}: 10005@end table 10006 10007 10008 10009@node MAX 10010@section @code{MAX} --- Maximum value of an argument list 10011@fnindex MAX 10012@fnindex MAX0 10013@fnindex AMAX0 10014@fnindex MAX1 10015@fnindex AMAX1 10016@fnindex DMAX1 10017@cindex maximum value 10018 10019@table @asis 10020@item @emph{Description}: 10021Returns the argument with the largest (most positive) value. 10022 10023@item @emph{Standard}: 10024Fortran 77 and later 10025 10026@item @emph{Class}: 10027Elemental function 10028 10029@item @emph{Syntax}: 10030@code{RESULT = MAX(A1, A2 [, A3 [, ...]])} 10031 10032@item @emph{Arguments}: 10033@multitable @columnfractions .15 .70 10034@item @var{A1} @tab The type shall be @code{INTEGER} or 10035@code{REAL}. 10036@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10037as @var{A1}. (As a GNU extension, arguments of different kinds are 10038permitted.) 10039@end multitable 10040 10041@item @emph{Return value}: 10042The return value corresponds to the maximum value among the arguments, 10043and has the same type and kind as the first argument. 10044 10045@item @emph{Specific names}: 10046@multitable @columnfractions .20 .20 .20 .25 10047@item Name @tab Argument @tab Return type @tab Standard 10048@item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10049@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later 10050@item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later 10051@item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10052@item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10053@end multitable 10054 10055@item @emph{See also}: 10056@ref{MAXLOC} @ref{MAXVAL}, @ref{MIN} 10057 10058@end table 10059 10060 10061 10062@node MAXEXPONENT 10063@section @code{MAXEXPONENT} --- Maximum exponent of a real kind 10064@fnindex MAXEXPONENT 10065@cindex model representation, maximum exponent 10066 10067@table @asis 10068@item @emph{Description}: 10069@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the 10070type of @code{X}. 10071 10072@item @emph{Standard}: 10073Fortran 95 and later 10074 10075@item @emph{Class}: 10076Inquiry function 10077 10078@item @emph{Syntax}: 10079@code{RESULT = MAXEXPONENT(X)} 10080 10081@item @emph{Arguments}: 10082@multitable @columnfractions .15 .70 10083@item @var{X} @tab Shall be of type @code{REAL}. 10084@end multitable 10085 10086@item @emph{Return value}: 10087The return value is of type @code{INTEGER} and of the default integer 10088kind. 10089 10090@item @emph{Example}: 10091@smallexample 10092program exponents 10093 real(kind=4) :: x 10094 real(kind=8) :: y 10095 10096 print *, minexponent(x), maxexponent(x) 10097 print *, minexponent(y), maxexponent(y) 10098end program exponents 10099@end smallexample 10100@end table 10101 10102 10103 10104@node MAXLOC 10105@section @code{MAXLOC} --- Location of the maximum value within an array 10106@fnindex MAXLOC 10107@cindex array, location of maximum element 10108 10109@table @asis 10110@item @emph{Description}: 10111Determines the location of the element in the array with the maximum 10112value, or, if the @var{DIM} argument is supplied, determines the 10113locations of the maximum element along each row of the array in the 10114@var{DIM} direction. If @var{MASK} is present, only the elements for 10115which @var{MASK} is @code{.TRUE.} are considered. If more than one 10116element in the array has the maximum value, the location returned is 10117that of the first such element in array element order if the 10118@var{BACK} is not present, or is false; if @var{BACK} is true, the location 10119returned is that of the last such element. If the array has zero 10120size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10121the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10122and all of the elements of @var{MASK} along a given row are zero, the 10123result value for that row is zero. 10124 10125@item @emph{Standard}: 10126Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the 10127@var{KIND} argument are available in Fortran 2003 and later. 10128The @var{BACK} argument is available in Fortran 2008 and later. 10129 10130@item @emph{Class}: 10131Transformational function 10132 10133@item @emph{Syntax}: 10134@multitable @columnfractions .80 10135@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} 10136@item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])} 10137@end multitable 10138 10139@item @emph{Arguments}: 10140@multitable @columnfractions .15 .70 10141@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10142@code{REAL}. 10143@item @var{DIM} @tab (Optional) Shall be a scalar of type 10144@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10145inclusive. It may not be an optional dummy argument. 10146@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10147and conformable with @var{ARRAY}. 10148@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10149expression indicating the kind parameter of the result. 10150@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 10151@end multitable 10152 10153@item @emph{Return value}: 10154If @var{DIM} is absent, the result is a rank-one array with a length 10155equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10156is an array with a rank one less than the rank of @var{ARRAY}, and a 10157size corresponding to the size of @var{ARRAY} with the @var{DIM} 10158dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10159of one, the result is a scalar. If the optional argument @var{KIND} 10160is present, the result is an integer of kind @var{KIND}, otherwise it 10161is of default kind. 10162 10163@item @emph{See also}: 10164@ref{FINDLOC}, @ref{MAX}, @ref{MAXVAL} 10165 10166@end table 10167 10168 10169 10170@node MAXVAL 10171@section @code{MAXVAL} --- Maximum value of an array 10172@fnindex MAXVAL 10173@cindex array, maximum value 10174@cindex maximum value 10175 10176@table @asis 10177@item @emph{Description}: 10178Determines the maximum value of the elements in an array value, or, if 10179the @var{DIM} argument is supplied, determines the maximum value along 10180each row of the array in the @var{DIM} direction. If @var{MASK} is 10181present, only the elements for which @var{MASK} is @code{.TRUE.} are 10182considered. If the array has zero size, or all of the elements of 10183@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)} 10184if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character 10185type. 10186 10187@item @emph{Standard}: 10188Fortran 95 and later 10189 10190@item @emph{Class}: 10191Transformational function 10192 10193@item @emph{Syntax}: 10194@multitable @columnfractions .80 10195@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])} 10196@item @code{RESULT = MAXVAL(ARRAY [, MASK])} 10197@end multitable 10198 10199@item @emph{Arguments}: 10200@multitable @columnfractions .15 .70 10201@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10202@code{REAL}. 10203@item @var{DIM} @tab (Optional) Shall be a scalar of type 10204@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10205inclusive. It may not be an optional dummy argument. 10206@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10207and conformable with @var{ARRAY}. 10208@end multitable 10209 10210@item @emph{Return value}: 10211If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10212is a scalar. If @var{DIM} is present, the result is an array with a 10213rank one less than the rank of @var{ARRAY}, and a size corresponding to 10214the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10215cases, the result is of the same type and kind as @var{ARRAY}. 10216 10217@item @emph{See also}: 10218@ref{MAX}, @ref{MAXLOC} 10219@end table 10220 10221 10222 10223@node MCLOCK 10224@section @code{MCLOCK} --- Time function 10225@fnindex MCLOCK 10226@cindex time, clock ticks 10227@cindex clock ticks 10228 10229@table @asis 10230@item @emph{Description}: 10231Returns the number of clock ticks since the start of the process, based 10232on the function @code{clock(3)} in the C standard library. 10233 10234This intrinsic is not fully portable, such as to systems with 32-bit 10235@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 10236the values returned by this intrinsic might be, or become, negative, or 10237numerically less than previous values, during a single run of the 10238compiled program. 10239 10240@item @emph{Standard}: 10241GNU extension 10242 10243@item @emph{Class}: 10244Function 10245 10246@item @emph{Syntax}: 10247@code{RESULT = MCLOCK()} 10248 10249@item @emph{Return value}: 10250The return value is a scalar of type @code{INTEGER(4)}, equal to the 10251number of clock ticks since the start of the process, or @code{-1} if 10252the system does not support @code{clock(3)}. 10253 10254@item @emph{See also}: 10255@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME} 10256 10257@end table 10258 10259 10260 10261@node MCLOCK8 10262@section @code{MCLOCK8} --- Time function (64-bit) 10263@fnindex MCLOCK8 10264@cindex time, clock ticks 10265@cindex clock ticks 10266 10267@table @asis 10268@item @emph{Description}: 10269Returns the number of clock ticks since the start of the process, based 10270on the function @code{clock(3)} in the C standard library. 10271 10272@emph{Warning:} this intrinsic does not increase the range of the timing 10273values over that returned by @code{clock(3)}. On a system with a 32-bit 10274@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though 10275it is converted to a 64-bit @code{INTEGER(8)} value. That means 10276overflows of the 32-bit value can still occur. Therefore, the values 10277returned by this intrinsic might be or become negative or numerically 10278less than previous values during a single run of the compiled program. 10279 10280@item @emph{Standard}: 10281GNU extension 10282 10283@item @emph{Class}: 10284Function 10285 10286@item @emph{Syntax}: 10287@code{RESULT = MCLOCK8()} 10288 10289@item @emph{Return value}: 10290The return value is a scalar of type @code{INTEGER(8)}, equal to the 10291number of clock ticks since the start of the process, or @code{-1} if 10292the system does not support @code{clock(3)}. 10293 10294@item @emph{See also}: 10295@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} 10296 10297@end table 10298 10299 10300 10301@node MERGE 10302@section @code{MERGE} --- Merge variables 10303@fnindex MERGE 10304@cindex array, merge arrays 10305@cindex array, combine arrays 10306 10307@table @asis 10308@item @emph{Description}: 10309Select values from two arrays according to a logical mask. The result 10310is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to 10311@var{FSOURCE} if it is @code{.FALSE.}. 10312 10313@item @emph{Standard}: 10314Fortran 95 and later 10315 10316@item @emph{Class}: 10317Elemental function 10318 10319@item @emph{Syntax}: 10320@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)} 10321 10322@item @emph{Arguments}: 10323@multitable @columnfractions .15 .70 10324@item @var{TSOURCE} @tab May be of any type. 10325@item @var{FSOURCE} @tab Shall be of the same type and type parameters 10326as @var{TSOURCE}. 10327@item @var{MASK} @tab Shall be of type @code{LOGICAL}. 10328@end multitable 10329 10330@item @emph{Return value}: 10331The result is of the same type and type parameters as @var{TSOURCE}. 10332 10333@end table 10334 10335 10336 10337@node MERGE_BITS 10338@section @code{MERGE_BITS} --- Merge of bits under mask 10339@fnindex MERGE_BITS 10340@cindex bits, merge 10341 10342@table @asis 10343@item @emph{Description}: 10344@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J} 10345as determined by the mask. The i-th bit of the result is equal to the 10346i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to 10347the i-th bit of @var{J} otherwise. 10348 10349@item @emph{Standard}: 10350Fortran 2008 and later 10351 10352@item @emph{Class}: 10353Elemental function 10354 10355@item @emph{Syntax}: 10356@code{RESULT = MERGE_BITS(I, J, MASK)} 10357 10358@item @emph{Arguments}: 10359@multitable @columnfractions .15 .70 10360@item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant. 10361@item @var{J} @tab Shall be of type @code{INTEGER} with the same 10362kind type parameter as @var{I} or a boz-literal-constant. 10363@var{I} and @var{J} shall not both be boz-literal-constants. 10364@item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant 10365and of the same kind as @var{I}. 10366@end multitable 10367 10368@item @emph{Return value}: 10369The result is of the same type and kind as @var{I}. 10370 10371@end table 10372 10373 10374 10375@node MIN 10376@section @code{MIN} --- Minimum value of an argument list 10377@fnindex MIN 10378@fnindex MIN0 10379@fnindex AMIN0 10380@fnindex MIN1 10381@fnindex AMIN1 10382@fnindex DMIN1 10383@cindex minimum value 10384 10385@table @asis 10386@item @emph{Description}: 10387Returns the argument with the smallest (most negative) value. 10388 10389@item @emph{Standard}: 10390Fortran 77 and later 10391 10392@item @emph{Class}: 10393Elemental function 10394 10395@item @emph{Syntax}: 10396@code{RESULT = MIN(A1, A2 [, A3, ...])} 10397 10398@item @emph{Arguments}: 10399@multitable @columnfractions .15 .70 10400@item @var{A1} @tab The type shall be @code{INTEGER} or 10401@code{REAL}. 10402@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 10403as @var{A1}. (As a GNU extension, arguments of different kinds are 10404permitted.) 10405@end multitable 10406 10407@item @emph{Return value}: 10408The return value corresponds to the maximum value among the arguments, 10409and has the same type and kind as the first argument. 10410 10411@item @emph{Specific names}: 10412@multitable @columnfractions .20 .20 .20 .25 10413@item Name @tab Argument @tab Return type @tab Standard 10414@item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10415@item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10416@item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 10417@item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 10418@item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 10419@end multitable 10420 10421@item @emph{See also}: 10422@ref{MAX}, @ref{MINLOC}, @ref{MINVAL} 10423@end table 10424 10425 10426 10427@node MINEXPONENT 10428@section @code{MINEXPONENT} --- Minimum exponent of a real kind 10429@fnindex MINEXPONENT 10430@cindex model representation, minimum exponent 10431 10432@table @asis 10433@item @emph{Description}: 10434@code{MINEXPONENT(X)} returns the minimum exponent in the model of the 10435type of @code{X}. 10436 10437@item @emph{Standard}: 10438Fortran 95 and later 10439 10440@item @emph{Class}: 10441Inquiry function 10442 10443@item @emph{Syntax}: 10444@code{RESULT = MINEXPONENT(X)} 10445 10446@item @emph{Arguments}: 10447@multitable @columnfractions .15 .70 10448@item @var{X} @tab Shall be of type @code{REAL}. 10449@end multitable 10450 10451@item @emph{Return value}: 10452The return value is of type @code{INTEGER} and of the default integer 10453kind. 10454 10455@item @emph{Example}: 10456See @code{MAXEXPONENT} for an example. 10457@end table 10458 10459 10460 10461@node MINLOC 10462@section @code{MINLOC} --- Location of the minimum value within an array 10463@fnindex MINLOC 10464@cindex array, location of minimum element 10465 10466@table @asis 10467@item @emph{Description}: 10468Determines the location of the element in the array with the minimum 10469value, or, if the @var{DIM} argument is supplied, determines the 10470locations of the minimum element along each row of the array in the 10471@var{DIM} direction. If @var{MASK} is present, only the elements for 10472which @var{MASK} is @code{.TRUE.} are considered. If more than one 10473element in the array has the minimum value, the location returned is 10474that of the first such element in array element order if the 10475@var{BACK} is not present, or is false; if @var{BACK} is true, the location 10476returned is that of the last such element. If the array has 10477zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 10478the result is an array of zeroes. Similarly, if @var{DIM} is supplied 10479and all of the elements of @var{MASK} along a given row are zero, the 10480result value for that row is zero. 10481 10482@item @emph{Standard}: 10483Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the 10484@var{KIND} argument are available in Fortran 2003 and later. 10485The @var{BACK} argument is available in Fortran 2008 and later. 10486 10487@item @emph{Class}: 10488Transformational function 10489 10490@item @emph{Syntax}: 10491@multitable @columnfractions .80 10492@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])} 10493@item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])} 10494@end multitable 10495 10496@item @emph{Arguments}: 10497@multitable @columnfractions .15 .70 10498@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 10499@code{REAL} or @code{CHARACTER}. 10500@item @var{DIM} @tab (Optional) Shall be a scalar of type 10501@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10502inclusive. It may not be an optional dummy argument. 10503@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10504and conformable with @var{ARRAY}. 10505@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10506expression indicating the kind parameter of the result. 10507@item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}. 10508@end multitable 10509 10510@item @emph{Return value}: 10511If @var{DIM} is absent, the result is a rank-one array with a length 10512equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 10513is an array with a rank one less than the rank of @var{ARRAY}, and a 10514size corresponding to the size of @var{ARRAY} with the @var{DIM} 10515dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 10516of one, the result is a scalar. If the optional argument @var{KIND} 10517is present, the result is an integer of kind @var{KIND}, otherwise it 10518is of default kind. 10519 10520@item @emph{See also}: 10521@ref{FINDLOC}, @ref{MIN}, @ref{MINVAL} 10522 10523@end table 10524 10525 10526 10527@node MINVAL 10528@section @code{MINVAL} --- Minimum value of an array 10529@fnindex MINVAL 10530@cindex array, minimum value 10531@cindex minimum value 10532 10533@table @asis 10534@item @emph{Description}: 10535Determines the minimum value of the elements in an array value, or, if 10536the @var{DIM} argument is supplied, determines the minimum value along 10537each row of the array in the @var{DIM} direction. If @var{MASK} is 10538present, only the elements for which @var{MASK} is @code{.TRUE.} are 10539considered. If the array has zero size, or all of the elements of 10540@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if 10541@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if 10542@var{ARRAY} is of character type. 10543 10544@item @emph{Standard}: 10545Fortran 95 and later 10546 10547@item @emph{Class}: 10548Transformational function 10549 10550@item @emph{Syntax}: 10551@multitable @columnfractions .80 10552@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])} 10553@item @code{RESULT = MINVAL(ARRAY [, MASK])} 10554@end multitable 10555 10556@item @emph{Arguments}: 10557@multitable @columnfractions .15 .70 10558@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 10559@code{REAL}. 10560@item @var{DIM} @tab (Optional) Shall be a scalar of type 10561@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 10562inclusive. It may not be an optional dummy argument. 10563@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 10564and conformable with @var{ARRAY}. 10565@end multitable 10566 10567@item @emph{Return value}: 10568If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 10569is a scalar. If @var{DIM} is present, the result is an array with a 10570rank one less than the rank of @var{ARRAY}, and a size corresponding to 10571the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 10572cases, the result is of the same type and kind as @var{ARRAY}. 10573 10574@item @emph{See also}: 10575@ref{MIN}, @ref{MINLOC} 10576 10577@end table 10578 10579 10580 10581@node MOD 10582@section @code{MOD} --- Remainder function 10583@fnindex MOD 10584@fnindex AMOD 10585@fnindex DMOD 10586@fnindex BMOD 10587@fnindex IMOD 10588@fnindex JMOD 10589@fnindex KMOD 10590@cindex remainder 10591@cindex division, remainder 10592 10593@table @asis 10594@item @emph{Description}: 10595@code{MOD(A,P)} computes the remainder of the division of A by P@. 10596 10597@item @emph{Standard}: 10598Fortran 77 and later, has overloads that are GNU extensions 10599 10600@item @emph{Class}: 10601Elemental function 10602 10603@item @emph{Syntax}: 10604@code{RESULT = MOD(A, P)} 10605 10606@item @emph{Arguments}: 10607@multitable @columnfractions .15 .70 10608@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10609@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A} 10610and not equal to zero. 10611@end multitable 10612 10613@item @emph{Return value}: 10614The return value is the result of @code{A - (INT(A/P) * P)}. The type 10615and kind of the return value is the same as that of the arguments. The 10616returned value has the same sign as A and a magnitude less than the 10617magnitude of P. 10618 10619@item @emph{Example}: 10620@smallexample 10621program test_mod 10622 print *, mod(17,3) 10623 print *, mod(17.5,5.5) 10624 print *, mod(17.5d0,5.5) 10625 print *, mod(17.5,5.5d0) 10626 10627 print *, mod(-17,3) 10628 print *, mod(-17.5,5.5) 10629 print *, mod(-17.5d0,5.5) 10630 print *, mod(-17.5,5.5d0) 10631 10632 print *, mod(17,-3) 10633 print *, mod(17.5,-5.5) 10634 print *, mod(17.5d0,-5.5) 10635 print *, mod(17.5,-5.5d0) 10636end program test_mod 10637@end smallexample 10638 10639@item @emph{Specific names}: 10640@multitable @columnfractions .20 .20 .20 .25 10641@item Name @tab Arguments @tab Return type @tab Standard 10642@item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later 10643@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later 10644@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later 10645@item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension 10646@item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension 10647@item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension 10648@item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension 10649@end multitable 10650 10651@item @emph{See also}: 10652@ref{MODULO} 10653 10654@end table 10655 10656 10657 10658@node MODULO 10659@section @code{MODULO} --- Modulo function 10660@fnindex MODULO 10661@cindex modulo 10662@cindex division, modulo 10663 10664@table @asis 10665@item @emph{Description}: 10666@code{MODULO(A,P)} computes the @var{A} modulo @var{P}. 10667 10668@item @emph{Standard}: 10669Fortran 95 and later 10670 10671@item @emph{Class}: 10672Elemental function 10673 10674@item @emph{Syntax}: 10675@code{RESULT = MODULO(A, P)} 10676 10677@item @emph{Arguments}: 10678@multitable @columnfractions .15 .70 10679@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 10680@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}. 10681It shall not be zero. 10682@end multitable 10683 10684@item @emph{Return value}: 10685The type and kind of the result are those of the arguments. 10686@table @asis 10687@item If @var{A} and @var{P} are of type @code{INTEGER}: 10688@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where 10689@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P} 10690(exclusive). 10691@item If @var{A} and @var{P} are of type @code{REAL}: 10692@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}. 10693@end table 10694The returned value has the same sign as P and a magnitude less than 10695the magnitude of P. 10696 10697@item @emph{Example}: 10698@smallexample 10699program test_modulo 10700 print *, modulo(17,3) 10701 print *, modulo(17.5,5.5) 10702 10703 print *, modulo(-17,3) 10704 print *, modulo(-17.5,5.5) 10705 10706 print *, modulo(17,-3) 10707 print *, modulo(17.5,-5.5) 10708end program 10709@end smallexample 10710 10711@item @emph{See also}: 10712@ref{MOD} 10713 10714@end table 10715 10716 10717 10718@node MOVE_ALLOC 10719@section @code{MOVE_ALLOC} --- Move allocation from one object to another 10720@fnindex MOVE_ALLOC 10721@cindex moving allocation 10722@cindex allocation, moving 10723 10724@table @asis 10725@item @emph{Description}: 10726@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to 10727@var{TO}. @var{FROM} will become deallocated in the process. 10728 10729@item @emph{Standard}: 10730Fortran 2003 and later 10731 10732@item @emph{Class}: 10733Pure subroutine 10734 10735@item @emph{Syntax}: 10736@code{CALL MOVE_ALLOC(FROM, TO)} 10737 10738@item @emph{Arguments}: 10739@multitable @columnfractions .15 .70 10740@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be 10741of any type and kind. 10742@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be 10743of the same type, kind and rank as @var{FROM}. 10744@end multitable 10745 10746@item @emph{Return value}: 10747None 10748 10749@item @emph{Example}: 10750@smallexample 10751program test_move_alloc 10752 integer, allocatable :: a(:), b(:) 10753 10754 allocate(a(3)) 10755 a = [ 1, 2, 3 ] 10756 call move_alloc(a, b) 10757 print *, allocated(a), allocated(b) 10758 print *, b 10759end program test_move_alloc 10760@end smallexample 10761@end table 10762 10763 10764 10765@node MVBITS 10766@section @code{MVBITS} --- Move bits from one integer to another 10767@fnindex MVBITS 10768@fnindex BMVBITS 10769@fnindex IMVBITS 10770@fnindex JMVBITS 10771@fnindex KMVBITS 10772@cindex bits, move 10773 10774@table @asis 10775@item @emph{Description}: 10776Moves @var{LEN} bits from positions @var{FROMPOS} through 10777@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through 10778@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not 10779affected by the movement of bits is unchanged. The values of 10780@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than 10781@code{BIT_SIZE(FROM)}. 10782 10783@item @emph{Standard}: 10784Fortran 95 and later, has overloads that are GNU extensions 10785 10786@item @emph{Class}: 10787Elemental subroutine 10788 10789@item @emph{Syntax}: 10790@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)} 10791 10792@item @emph{Arguments}: 10793@multitable @columnfractions .15 .70 10794@item @var{FROM} @tab The type shall be @code{INTEGER}. 10795@item @var{FROMPOS} @tab The type shall be @code{INTEGER}. 10796@item @var{LEN} @tab The type shall be @code{INTEGER}. 10797@item @var{TO} @tab The type shall be @code{INTEGER}, of the 10798same kind as @var{FROM}. 10799@item @var{TOPOS} @tab The type shall be @code{INTEGER}. 10800@end multitable 10801 10802@item @emph{Specific names}: 10803@multitable @columnfractions .20 .20 .20 .25 10804@item Name @tab Argument @tab Return type @tab Standard 10805@item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 10806@item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 10807@item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 10808@item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 10809@item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 10810@end multitable 10811 10812@item @emph{See also}: 10813@ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR} 10814@end table 10815 10816 10817 10818@node NEAREST 10819@section @code{NEAREST} --- Nearest representable number 10820@fnindex NEAREST 10821@cindex real number, nearest different 10822@cindex floating point, nearest different 10823 10824@table @asis 10825@item @emph{Description}: 10826@code{NEAREST(X, S)} returns the processor-representable number nearest 10827to @code{X} in the direction indicated by the sign of @code{S}. 10828 10829@item @emph{Standard}: 10830Fortran 95 and later 10831 10832@item @emph{Class}: 10833Elemental function 10834 10835@item @emph{Syntax}: 10836@code{RESULT = NEAREST(X, S)} 10837 10838@item @emph{Arguments}: 10839@multitable @columnfractions .15 .70 10840@item @var{X} @tab Shall be of type @code{REAL}. 10841@item @var{S} @tab Shall be of type @code{REAL} and 10842not equal to zero. 10843@end multitable 10844 10845@item @emph{Return value}: 10846The return value is of the same type as @code{X}. If @code{S} is 10847positive, @code{NEAREST} returns the processor-representable number 10848greater than @code{X} and nearest to it. If @code{S} is negative, 10849@code{NEAREST} returns the processor-representable number smaller than 10850@code{X} and nearest to it. 10851 10852@item @emph{Example}: 10853@smallexample 10854program test_nearest 10855 real :: x, y 10856 x = nearest(42.0, 1.0) 10857 y = nearest(42.0, -1.0) 10858 write (*,"(3(G20.15))") x, y, x - y 10859end program test_nearest 10860@end smallexample 10861@end table 10862 10863 10864 10865@node NEW_LINE 10866@section @code{NEW_LINE} --- New line character 10867@fnindex NEW_LINE 10868@cindex newline 10869@cindex output, newline 10870 10871@table @asis 10872@item @emph{Description}: 10873@code{NEW_LINE(C)} returns the new-line character. 10874 10875@item @emph{Standard}: 10876Fortran 2003 and later 10877 10878@item @emph{Class}: 10879Inquiry function 10880 10881@item @emph{Syntax}: 10882@code{RESULT = NEW_LINE(C)} 10883 10884@item @emph{Arguments}: 10885@multitable @columnfractions .15 .70 10886@item @var{C} @tab The argument shall be a scalar or array of the 10887type @code{CHARACTER}. 10888@end multitable 10889 10890@item @emph{Return value}: 10891Returns a @var{CHARACTER} scalar of length one with the new-line character of 10892the same kind as parameter @var{C}. 10893 10894@item @emph{Example}: 10895@smallexample 10896program newline 10897 implicit none 10898 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' 10899end program newline 10900@end smallexample 10901@end table 10902 10903 10904 10905@node NINT 10906@section @code{NINT} --- Nearest whole number 10907@fnindex NINT 10908@fnindex IDNINT 10909@cindex rounding, nearest whole number 10910 10911@table @asis 10912@item @emph{Description}: 10913@code{NINT(A)} rounds its argument to the nearest whole number. 10914 10915@item @emph{Standard}: 10916Fortran 77 and later, with @var{KIND} argument Fortran 90 and later 10917 10918@item @emph{Class}: 10919Elemental function 10920 10921@item @emph{Syntax}: 10922@code{RESULT = NINT(A [, KIND])} 10923 10924@item @emph{Arguments}: 10925@multitable @columnfractions .15 .70 10926@item @var{A} @tab The type of the argument shall be @code{REAL}. 10927@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10928expression indicating the kind parameter of the result. 10929@end multitable 10930 10931@item @emph{Return value}: 10932Returns @var{A} with the fractional portion of its magnitude eliminated by 10933rounding to the nearest whole number and with its sign preserved, 10934converted to an @code{INTEGER} of the default kind. 10935 10936@item @emph{Example}: 10937@smallexample 10938program test_nint 10939 real(4) x4 10940 real(8) x8 10941 x4 = 1.234E0_4 10942 x8 = 4.321_8 10943 print *, nint(x4), idnint(x8) 10944end program test_nint 10945@end smallexample 10946 10947@item @emph{Specific names}: 10948@multitable @columnfractions .20 .20 .20 .25 10949@item Name @tab Argument @tab Return Type @tab Standard 10950@item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later 10951@item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later 10952@end multitable 10953 10954@item @emph{See also}: 10955@ref{CEILING}, @ref{FLOOR} 10956 10957@end table 10958 10959 10960 10961@node NORM2 10962@section @code{NORM2} --- Euclidean vector norms 10963@fnindex NORM2 10964@cindex Euclidean vector norm 10965@cindex L2 vector norm 10966@cindex norm, Euclidean 10967 10968@table @asis 10969@item @emph{Description}: 10970Calculates the Euclidean vector norm (@math{L_2} norm) of 10971of @var{ARRAY} along dimension @var{DIM}. 10972 10973@item @emph{Standard}: 10974Fortran 2008 and later 10975 10976@item @emph{Class}: 10977Transformational function 10978 10979@item @emph{Syntax}: 10980@multitable @columnfractions .80 10981@item @code{RESULT = NORM2(ARRAY[, DIM])} 10982@end multitable 10983 10984@item @emph{Arguments}: 10985@multitable @columnfractions .15 .70 10986@item @var{ARRAY} @tab Shall be an array of type @code{REAL} 10987@item @var{DIM} @tab (Optional) shall be a scalar of type 10988@code{INTEGER} with a value in the range from 1 to n, where n 10989equals the rank of @var{ARRAY}. 10990@end multitable 10991 10992@item @emph{Return value}: 10993The result is of the same type as @var{ARRAY}. 10994 10995If @var{DIM} is absent, a scalar with the square root of the sum of all 10996elements in @var{ARRAY} squared is returned. Otherwise, an array of 10997rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a 10998shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped 10999is returned. 11000 11001@item @emph{Example}: 11002@smallexample 11003PROGRAM test_sum 11004 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] 11005 print *, NORM2(x) ! = sqrt(55.) ~ 7.416 11006END PROGRAM 11007@end smallexample 11008@end table 11009 11010 11011 11012@node NOT 11013@section @code{NOT} --- Logical negation 11014@fnindex NOT 11015@fnindex BNOT 11016@fnindex INOT 11017@fnindex JNOT 11018@fnindex KNOT 11019@cindex bits, negate 11020@cindex bitwise logical not 11021@cindex logical not, bitwise 11022 11023@table @asis 11024@item @emph{Description}: 11025@code{NOT} returns the bitwise Boolean inverse of @var{I}. 11026 11027@item @emph{Standard}: 11028Fortran 95 and later, has overloads that are GNU extensions 11029 11030@item @emph{Class}: 11031Elemental function 11032 11033@item @emph{Syntax}: 11034@code{RESULT = NOT(I)} 11035 11036@item @emph{Arguments}: 11037@multitable @columnfractions .15 .70 11038@item @var{I} @tab The type shall be @code{INTEGER}. 11039@end multitable 11040 11041@item @emph{Return value}: 11042The return type is @code{INTEGER}, of the same kind as the 11043argument. 11044 11045@item @emph{Specific names}: 11046@multitable @columnfractions .20 .20 .20 .25 11047@item Name @tab Argument @tab Return type @tab Standard 11048@item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later 11049@item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension 11050@item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension 11051@item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension 11052@item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension 11053@end multitable 11054 11055@item @emph{See also}: 11056@ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR} 11057 11058@end table 11059 11060 11061 11062@node NULL 11063@section @code{NULL} --- Function that returns an disassociated pointer 11064@fnindex NULL 11065@cindex pointer, status 11066@cindex pointer, disassociated 11067 11068@table @asis 11069@item @emph{Description}: 11070Returns a disassociated pointer. 11071 11072If @var{MOLD} is present, a disassociated pointer of the same type is 11073returned, otherwise the type is determined by context. 11074 11075In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003 11076includes cases where it is required. 11077 11078@item @emph{Standard}: 11079Fortran 95 and later 11080 11081@item @emph{Class}: 11082Transformational function 11083 11084@item @emph{Syntax}: 11085@code{PTR => NULL([MOLD])} 11086 11087@item @emph{Arguments}: 11088@multitable @columnfractions .15 .70 11089@item @var{MOLD} @tab (Optional) shall be a pointer of any association 11090status and of any type. 11091@end multitable 11092 11093@item @emph{Return value}: 11094A disassociated pointer. 11095 11096@item @emph{Example}: 11097@smallexample 11098REAL, POINTER, DIMENSION(:) :: VEC => NULL () 11099@end smallexample 11100 11101@item @emph{See also}: 11102@ref{ASSOCIATED} 11103@end table 11104 11105 11106 11107@node NUM_IMAGES 11108@section @code{NUM_IMAGES} --- Function that returns the number of images 11109@fnindex NUM_IMAGES 11110@cindex coarray, @code{NUM_IMAGES} 11111@cindex images, number of 11112 11113@table @asis 11114@item @emph{Description}: 11115Returns the number of images. 11116 11117@item @emph{Standard}: 11118Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument, 11119Technical Specification (TS) 18508 or later 11120 11121 11122@item @emph{Class}: 11123Transformational function 11124 11125@item @emph{Syntax}: 11126@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} 11127 11128@item @emph{Arguments}: 11129@multitable @columnfractions .15 .70 11130@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 11131@item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression 11132@end multitable 11133 11134@item @emph{Return value}: 11135Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, 11136the number of images in the current team is returned. For values smaller or 11137equal distance to the initial team, it returns the number of images index 11138on the ancestor team which has a distance of @var{DISTANCE} from the invoking 11139team. If @var{DISTANCE} is larger than the distance to the initial team, the 11140number of images of the initial team is returned. If @var{FAILED} is not present 11141the total number of images is returned; if it has the value @code{.TRUE.}, 11142the number of failed images is returned, otherwise, the number of images which 11143do have not the failed status. 11144 11145@item @emph{Example}: 11146@smallexample 11147INTEGER :: value[*] 11148INTEGER :: i 11149value = THIS_IMAGE() 11150SYNC ALL 11151IF (THIS_IMAGE() == 1) THEN 11152 DO i = 1, NUM_IMAGES() 11153 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 11154 END DO 11155END IF 11156@end smallexample 11157 11158@item @emph{See also}: 11159@ref{THIS_IMAGE}, @ref{IMAGE_INDEX} 11160@end table 11161 11162 11163 11164@node OR 11165@section @code{OR} --- Bitwise logical OR 11166@fnindex OR 11167@cindex bitwise logical or 11168@cindex logical or, bitwise 11169 11170@table @asis 11171@item @emph{Description}: 11172Bitwise logical @code{OR}. 11173 11174This intrinsic routine is provided for backwards compatibility with 11175GNU Fortran 77. For integer arguments, programmers should consider 11176the use of the @ref{IOR} intrinsic defined by the Fortran standard. 11177 11178@item @emph{Standard}: 11179GNU extension 11180 11181@item @emph{Class}: 11182Function 11183 11184@item @emph{Syntax}: 11185@code{RESULT = OR(I, J)} 11186 11187@item @emph{Arguments}: 11188@multitable @columnfractions .15 .70 11189@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 11190type or a scalar @code{LOGICAL} type or a boz-literal-constant. 11191@item @var{J} @tab The type shall be the same as the type of @var{I} or 11192a boz-literal-constant. @var{I} and @var{J} shall not both be 11193boz-literal-constants. If either @var{I} and @var{J} is a 11194boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 11195@end multitable 11196 11197@item @emph{Return value}: 11198The return type is either a scalar @code{INTEGER} or a scalar 11199@code{LOGICAL}. If the kind type parameters differ, then the 11200smaller kind type is implicitly converted to larger kind, and the 11201return has the larger kind. A boz-literal-constant is 11202converted to an @code{INTEGER} with the kind type parameter of 11203the other argument as-if a call to @ref{INT} occurred. 11204 11205@item @emph{Example}: 11206@smallexample 11207PROGRAM test_or 11208 LOGICAL :: T = .TRUE., F = .FALSE. 11209 INTEGER :: a, b 11210 DATA a / Z'F' /, b / Z'3' / 11211 11212 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F) 11213 WRITE (*,*) OR(a, b) 11214END PROGRAM 11215@end smallexample 11216 11217@item @emph{See also}: 11218Fortran 95 elemental function: @ref{IOR} 11219@end table 11220 11221 11222 11223@node PACK 11224@section @code{PACK} --- Pack an array into an array of rank one 11225@fnindex PACK 11226@cindex array, packing 11227@cindex array, reduce dimension 11228@cindex array, gather elements 11229 11230@table @asis 11231@item @emph{Description}: 11232Stores the elements of @var{ARRAY} in an array of rank one. 11233 11234The beginning of the resulting array is made up of elements whose @var{MASK} 11235equals @code{TRUE}. Afterwards, positions are filled with elements taken from 11236@var{VECTOR}. 11237 11238@item @emph{Standard}: 11239Fortran 95 and later 11240 11241@item @emph{Class}: 11242Transformational function 11243 11244@item @emph{Syntax}: 11245@code{RESULT = PACK(ARRAY, MASK[,VECTOR])} 11246 11247@item @emph{Arguments}: 11248@multitable @columnfractions .15 .70 11249@item @var{ARRAY} @tab Shall be an array of any type. 11250@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and 11251of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} 11252scalar. 11253@item @var{VECTOR} @tab (Optional) shall be an array of the same type 11254as @var{ARRAY} and of rank one. If present, the number of elements in 11255@var{VECTOR} shall be equal to or greater than the number of true elements 11256in @var{MASK}. If @var{MASK} is scalar, the number of elements in 11257@var{VECTOR} shall be equal to or greater than the number of elements in 11258@var{ARRAY}. 11259@end multitable 11260 11261@item @emph{Return value}: 11262The result is an array of rank one and the same type as that of @var{ARRAY}. 11263If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the 11264number of @code{TRUE} values in @var{MASK} otherwise. 11265 11266@item @emph{Example}: 11267Gathering nonzero elements from an array: 11268@smallexample 11269PROGRAM test_pack_1 11270 INTEGER :: m(6) 11271 m = (/ 1, 0, 0, 0, 5, 0 /) 11272 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5" 11273END PROGRAM 11274@end smallexample 11275 11276Gathering nonzero elements from an array and appending elements from @var{VECTOR}: 11277@smallexample 11278PROGRAM test_pack_2 11279 INTEGER :: m(4) 11280 m = (/ 1, 0, 0, 2 /) 11281 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4" 11282END PROGRAM 11283@end smallexample 11284 11285@item @emph{See also}: 11286@ref{UNPACK} 11287@end table 11288 11289 11290 11291@node PARITY 11292@section @code{PARITY} --- Reduction with exclusive OR 11293@fnindex PARITY 11294@cindex Parity 11295@cindex Reduction, XOR 11296@cindex XOR reduction 11297 11298@table @asis 11299@item @emph{Description}: 11300Calculates the parity, i.e. the reduction using @code{.XOR.}, 11301of @var{MASK} along dimension @var{DIM}. 11302 11303@item @emph{Standard}: 11304Fortran 2008 and later 11305 11306@item @emph{Class}: 11307Transformational function 11308 11309@item @emph{Syntax}: 11310@multitable @columnfractions .80 11311@item @code{RESULT = PARITY(MASK[, DIM])} 11312@end multitable 11313 11314@item @emph{Arguments}: 11315@multitable @columnfractions .15 .70 11316@item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL} 11317@item @var{DIM} @tab (Optional) shall be a scalar of type 11318@code{INTEGER} with a value in the range from 1 to n, where n 11319equals the rank of @var{MASK}. 11320@end multitable 11321 11322@item @emph{Return value}: 11323The result is of the same type as @var{MASK}. 11324 11325If @var{DIM} is absent, a scalar with the parity of all elements in 11326@var{MASK} is returned, i.e. true if an odd number of elements is 11327@code{.true.} and false otherwise. If @var{DIM} is present, an array 11328of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, 11329and a shape similar to that of @var{MASK} with dimension @var{DIM} 11330dropped is returned. 11331 11332@item @emph{Example}: 11333@smallexample 11334PROGRAM test_sum 11335 LOGICAL :: x(2) = [ .true., .false. ] 11336 print *, PARITY(x) ! prints "T" (true). 11337END PROGRAM 11338@end smallexample 11339@end table 11340 11341 11342 11343@node PERROR 11344@section @code{PERROR} --- Print system error message 11345@fnindex PERROR 11346@cindex system, error handling 11347 11348@table @asis 11349@item @emph{Description}: 11350Prints (on the C @code{stderr} stream) a newline-terminated error 11351message corresponding to the last system error. This is prefixed by 11352@var{STRING}, a colon and a space. See @code{perror(3)}. 11353 11354@item @emph{Standard}: 11355GNU extension 11356 11357@item @emph{Class}: 11358Subroutine 11359 11360@item @emph{Syntax}: 11361@code{CALL PERROR(STRING)} 11362 11363@item @emph{Arguments}: 11364@multitable @columnfractions .15 .70 11365@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the 11366default kind. 11367@end multitable 11368 11369@item @emph{See also}: 11370@ref{IERRNO} 11371@end table 11372 11373 11374 11375@node POPCNT 11376@section @code{POPCNT} --- Number of bits set 11377@fnindex POPCNT 11378@cindex binary representation 11379@cindex bits set 11380 11381@table @asis 11382@item @emph{Description}: 11383@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary 11384representation of @code{I}. 11385 11386@item @emph{Standard}: 11387Fortran 2008 and later 11388 11389@item @emph{Class}: 11390Elemental function 11391 11392@item @emph{Syntax}: 11393@code{RESULT = POPCNT(I)} 11394 11395@item @emph{Arguments}: 11396@multitable @columnfractions .15 .70 11397@item @var{I} @tab Shall be of type @code{INTEGER}. 11398@end multitable 11399 11400@item @emph{Return value}: 11401The return value is of type @code{INTEGER} and of the default integer 11402kind. 11403 11404@item @emph{See also}: 11405@ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ} 11406 11407@item @emph{Example}: 11408@smallexample 11409program test_population 11410 print *, popcnt(127), poppar(127) 11411 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11412 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11413end program test_population 11414@end smallexample 11415@end table 11416 11417 11418@node POPPAR 11419@section @code{POPPAR} --- Parity of the number of bits set 11420@fnindex POPPAR 11421@cindex binary representation 11422@cindex parity 11423 11424@table @asis 11425@item @emph{Description}: 11426@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity 11427of the number of bits set ('1' bits) in the binary representation of 11428@code{I}. It is equal to 0 if @code{I} has an even number of bits set, 11429and 1 for an odd number of '1' bits. 11430 11431@item @emph{Standard}: 11432Fortran 2008 and later 11433 11434@item @emph{Class}: 11435Elemental function 11436 11437@item @emph{Syntax}: 11438@code{RESULT = POPPAR(I)} 11439 11440@item @emph{Arguments}: 11441@multitable @columnfractions .15 .70 11442@item @var{I} @tab Shall be of type @code{INTEGER}. 11443@end multitable 11444 11445@item @emph{Return value}: 11446The return value is of type @code{INTEGER} and of the default integer 11447kind. 11448 11449@item @emph{See also}: 11450@ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ} 11451 11452@item @emph{Example}: 11453@smallexample 11454program test_population 11455 print *, popcnt(127), poppar(127) 11456 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 11457 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 11458end program test_population 11459@end smallexample 11460@end table 11461 11462 11463 11464@node PRECISION 11465@section @code{PRECISION} --- Decimal precision of a real kind 11466@fnindex PRECISION 11467@cindex model representation, precision 11468 11469@table @asis 11470@item @emph{Description}: 11471@code{PRECISION(X)} returns the decimal precision in the model of the 11472type of @code{X}. 11473 11474@item @emph{Standard}: 11475Fortran 95 and later 11476 11477@item @emph{Class}: 11478Inquiry function 11479 11480@item @emph{Syntax}: 11481@code{RESULT = PRECISION(X)} 11482 11483@item @emph{Arguments}: 11484@multitable @columnfractions .15 .70 11485@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. 11486@end multitable 11487 11488@item @emph{Return value}: 11489The return value is of type @code{INTEGER} and of the default integer 11490kind. 11491 11492@item @emph{See also}: 11493@ref{SELECTED_REAL_KIND}, @ref{RANGE} 11494 11495@item @emph{Example}: 11496@smallexample 11497program prec_and_range 11498 real(kind=4) :: x(2) 11499 complex(kind=8) :: y 11500 11501 print *, precision(x), range(x) 11502 print *, precision(y), range(y) 11503end program prec_and_range 11504@end smallexample 11505@end table 11506 11507 11508 11509@node PRESENT 11510@section @code{PRESENT} --- Determine whether an optional dummy argument is specified 11511@fnindex PRESENT 11512 11513@table @asis 11514@item @emph{Description}: 11515Determines whether an optional dummy argument is present. 11516 11517@item @emph{Standard}: 11518Fortran 95 and later 11519 11520@item @emph{Class}: 11521Inquiry function 11522 11523@item @emph{Syntax}: 11524@code{RESULT = PRESENT(A)} 11525 11526@item @emph{Arguments}: 11527@multitable @columnfractions .15 .70 11528@item @var{A} @tab May be of any type and may be a pointer, scalar or array 11529value, or a dummy procedure. It shall be the name of an optional dummy argument 11530accessible within the current subroutine or function. 11531@end multitable 11532 11533@item @emph{Return value}: 11534Returns either @code{TRUE} if the optional argument @var{A} is present, or 11535@code{FALSE} otherwise. 11536 11537@item @emph{Example}: 11538@smallexample 11539PROGRAM test_present 11540 WRITE(*,*) f(), f(42) ! "F T" 11541CONTAINS 11542 LOGICAL FUNCTION f(x) 11543 INTEGER, INTENT(IN), OPTIONAL :: x 11544 f = PRESENT(x) 11545 END FUNCTION 11546END PROGRAM 11547@end smallexample 11548@end table 11549 11550 11551 11552@node PRODUCT 11553@section @code{PRODUCT} --- Product of array elements 11554@fnindex PRODUCT 11555@cindex array, product 11556@cindex array, multiply elements 11557@cindex array, conditionally multiply elements 11558@cindex multiply array elements 11559 11560@table @asis 11561@item @emph{Description}: 11562Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if 11563the corresponding element in @var{MASK} is @code{TRUE}. 11564 11565@item @emph{Standard}: 11566Fortran 95 and later 11567 11568@item @emph{Class}: 11569Transformational function 11570 11571@item @emph{Syntax}: 11572@multitable @columnfractions .80 11573@item @code{RESULT = PRODUCT(ARRAY[, MASK])} 11574@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])} 11575@end multitable 11576 11577@item @emph{Arguments}: 11578@multitable @columnfractions .15 .70 11579@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 11580@code{REAL} or @code{COMPLEX}. 11581@item @var{DIM} @tab (Optional) shall be a scalar of type 11582@code{INTEGER} with a value in the range from 1 to n, where n 11583equals the rank of @var{ARRAY}. 11584@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 11585and either be a scalar or an array of the same shape as @var{ARRAY}. 11586@end multitable 11587 11588@item @emph{Return value}: 11589The result is of the same type as @var{ARRAY}. 11590 11591If @var{DIM} is absent, a scalar with the product of all elements in 11592@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 11593the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 11594dimension @var{DIM} dropped is returned. 11595 11596 11597@item @emph{Example}: 11598@smallexample 11599PROGRAM test_product 11600 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 11601 print *, PRODUCT(x) ! all elements, product = 120 11602 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15 11603END PROGRAM 11604@end smallexample 11605 11606@item @emph{See also}: 11607@ref{SUM} 11608@end table 11609 11610 11611 11612@node RADIX 11613@section @code{RADIX} --- Base of a model number 11614@fnindex RADIX 11615@cindex model representation, base 11616@cindex model representation, radix 11617 11618@table @asis 11619@item @emph{Description}: 11620@code{RADIX(X)} returns the base of the model representing the entity @var{X}. 11621 11622@item @emph{Standard}: 11623Fortran 95 and later 11624 11625@item @emph{Class}: 11626Inquiry function 11627 11628@item @emph{Syntax}: 11629@code{RESULT = RADIX(X)} 11630 11631@item @emph{Arguments}: 11632@multitable @columnfractions .15 .70 11633@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL} 11634@end multitable 11635 11636@item @emph{Return value}: 11637The return value is a scalar of type @code{INTEGER} and of the default 11638integer kind. 11639 11640@item @emph{See also}: 11641@ref{SELECTED_REAL_KIND} 11642 11643@item @emph{Example}: 11644@smallexample 11645program test_radix 11646 print *, "The radix for the default integer kind is", radix(0) 11647 print *, "The radix for the default real kind is", radix(0.0) 11648end program test_radix 11649@end smallexample 11650 11651@end table 11652 11653 11654 11655@node RAN 11656@section @code{RAN} --- Real pseudo-random number 11657@fnindex RAN 11658@cindex random number generation 11659 11660@table @asis 11661@item @emph{Description}: 11662For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is 11663provided as an alias for @code{RAND}. See @ref{RAND} for complete 11664documentation. 11665 11666@item @emph{Standard}: 11667GNU extension 11668 11669@item @emph{Class}: 11670Function 11671 11672@item @emph{See also}: 11673@ref{RAND}, @ref{RANDOM_NUMBER} 11674@end table 11675 11676 11677 11678@node RAND 11679@section @code{RAND} --- Real pseudo-random number 11680@fnindex RAND 11681@cindex random number generation 11682 11683@table @asis 11684@item @emph{Description}: 11685@code{RAND(FLAG)} returns a pseudo-random number from a uniform 11686distribution between 0 and 1. If @var{FLAG} is 0, the next number 11687in the current sequence is returned; if @var{FLAG} is 1, the generator 11688is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 11689it is used as a new seed with @code{SRAND}. 11690 11691This intrinsic routine is provided for backwards compatibility with 11692GNU Fortran 77. It implements a simple modulo generator as provided 11693by @command{g77}. For new code, one should consider the use of 11694@ref{RANDOM_NUMBER} as it implements a superior algorithm. 11695 11696@item @emph{Standard}: 11697GNU extension 11698 11699@item @emph{Class}: 11700Function 11701 11702@item @emph{Syntax}: 11703@code{RESULT = RAND(I)} 11704 11705@item @emph{Arguments}: 11706@multitable @columnfractions .15 .70 11707@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 11708@end multitable 11709 11710@item @emph{Return value}: 11711The return value is of @code{REAL} type and the default kind. 11712 11713@item @emph{Example}: 11714@smallexample 11715program test_rand 11716 integer,parameter :: seed = 86456 11717 11718 call srand(seed) 11719 print *, rand(), rand(), rand(), rand() 11720 print *, rand(seed), rand(), rand(), rand() 11721end program test_rand 11722@end smallexample 11723 11724@item @emph{See also}: 11725@ref{SRAND}, @ref{RANDOM_NUMBER} 11726 11727@end table 11728 11729 11730@node RANDOM_INIT 11731@section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator 11732@fnindex RANDOM_INIT 11733@cindex random number generation, initialization 11734 11735@table @asis 11736@item @emph{Description}: 11737Initializes the state of the pseudorandom number generator used by 11738@code{RANDOM_NUMBER}. 11739 11740@item @emph{Standard}: 11741Fortran 2018 11742 11743@item @emph{Class}: 11744Subroutine 11745 11746@item @emph{Syntax}: 11747@code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)} 11748 11749@item @emph{Arguments}: 11750@multitable @columnfractions .20 .75 11751@item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type, 11752and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to 11753a processor-dependent value that is the same each time @code{RANDOM_INIT} 11754is called from the same image. The term ``same image'' means a single 11755instance of program execution. The sequence of random numbers is different 11756for repeated execution of the program. If it is @code{.false.}, the seed 11757is set to a processor-dependent value. 11758@item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a 11759@code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.}, 11760the seed is set to a processor-dependent value that is distinct from th 11761seed set by a call to @code{RANDOM_INIT} in another image. If it is 11762@code{.false.}, the seed is set value that does depend which image called 11763@code{RANDOM_INIT}. 11764@end multitable 11765 11766@item @emph{Example}: 11767@smallexample 11768program test_random_seed 11769 implicit none 11770 real x(3), y(3) 11771 call random_init(.true., .true.) 11772 call random_number(x) 11773 call random_init(.true., .true.) 11774 call random_number(y) 11775 ! x and y are the same sequence 11776 if (any(x /= y)) call abort 11777end program test_random_seed 11778@end smallexample 11779 11780@item @emph{See also}: 11781@ref{RANDOM_NUMBER}, @ref{RANDOM_SEED} 11782@end table 11783 11784 11785@node RANDOM_NUMBER 11786@section @code{RANDOM_NUMBER} --- Pseudo-random number 11787@fnindex RANDOM_NUMBER 11788@cindex random number generation 11789 11790@table @asis 11791@item @emph{Description}: 11792Returns a single pseudorandom number or an array of pseudorandom numbers 11793from the uniform distribution over the range @math{ 0 \leq x < 1}. 11794 11795The runtime-library implements the xorshift1024* random number 11796generator (RNG). This generator has a period of @math{2^{1024} - 1}, 11797and when using multiple threads up to @math{2^{512}} threads can each 11798generate @math{2^{512}} random numbers before any aliasing occurs. 11799 11800Note that in a multi-threaded program (e.g. using OpenMP directives), 11801each thread will have its own random number state. For details of the 11802seeding procedure, see the documentation for the @code{RANDOM_SEED} 11803intrinsic. 11804 11805 11806@item @emph{Standard}: 11807Fortran 95 and later 11808 11809@item @emph{Class}: 11810Subroutine 11811 11812@item @emph{Syntax}: 11813@code{RANDOM_NUMBER(HARVEST)} 11814 11815@item @emph{Arguments}: 11816@multitable @columnfractions .15 .70 11817@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}. 11818@end multitable 11819 11820@item @emph{Example}: 11821@smallexample 11822program test_random_number 11823 REAL :: r(5,5) 11824 CALL RANDOM_NUMBER(r) 11825end program 11826@end smallexample 11827 11828@item @emph{See also}: 11829@ref{RANDOM_SEED}, @ref{RANDOM_INIT} 11830@end table 11831 11832 11833 11834@node RANDOM_SEED 11835@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence 11836@fnindex RANDOM_SEED 11837@cindex random number generation, seeding 11838@cindex seeding a random number generator 11839 11840@table @asis 11841@item @emph{Description}: 11842Restarts or queries the state of the pseudorandom number generator used by 11843@code{RANDOM_NUMBER}. 11844 11845If @code{RANDOM_SEED} is called without arguments, it is seeded with 11846random data retrieved from the operating system. 11847 11848As an extension to the Fortran standard, the GFortran 11849@code{RANDOM_NUMBER} supports multiple threads. Each thread in a 11850multi-threaded program has its own seed. When @code{RANDOM_SEED} is 11851called either without arguments or with the @var{PUT} argument, the 11852given seed is copied into a master seed as well as the seed of the 11853current thread. When a new thread uses @code{RANDOM_NUMBER} for the 11854first time, the seed is copied from the master seed, and forwarded 11855@math{N * 2^{512}} steps to guarantee that the random stream does not 11856alias any other stream in the system, where @var{N} is the number of 11857threads that have used @code{RANDOM_NUMBER} so far during the program 11858execution. 11859 11860@item @emph{Standard}: 11861Fortran 95 and later 11862 11863@item @emph{Class}: 11864Subroutine 11865 11866@item @emph{Syntax}: 11867@code{CALL RANDOM_SEED([SIZE, PUT, GET])} 11868 11869@item @emph{Arguments}: 11870@multitable @columnfractions .15 .70 11871@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default 11872@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size 11873of the arrays used with the @var{PUT} and @var{GET} arguments. 11874@item @var{PUT} @tab (Optional) Shall be an array of type default 11875@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of 11876the array must be larger than or equal to the number returned by the 11877@var{SIZE} argument. 11878@item @var{GET} @tab (Optional) Shall be an array of type default 11879@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size 11880of the array must be larger than or equal to the number returned by 11881the @var{SIZE} argument. 11882@end multitable 11883 11884@item @emph{Example}: 11885@smallexample 11886program test_random_seed 11887 implicit none 11888 integer, allocatable :: seed(:) 11889 integer :: n 11890 11891 call random_seed(size = n) 11892 allocate(seed(n)) 11893 call random_seed(get=seed) 11894 write (*, *) seed 11895end program test_random_seed 11896@end smallexample 11897 11898@item @emph{See also}: 11899@ref{RANDOM_NUMBER}, @ref{RANDOM_INIT} 11900@end table 11901 11902 11903 11904@node RANGE 11905@section @code{RANGE} --- Decimal exponent range 11906@fnindex RANGE 11907@cindex model representation, range 11908 11909@table @asis 11910@item @emph{Description}: 11911@code{RANGE(X)} returns the decimal exponent range in the model of the 11912type of @code{X}. 11913 11914@item @emph{Standard}: 11915Fortran 95 and later 11916 11917@item @emph{Class}: 11918Inquiry function 11919 11920@item @emph{Syntax}: 11921@code{RESULT = RANGE(X)} 11922 11923@item @emph{Arguments}: 11924@multitable @columnfractions .15 .70 11925@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL} 11926or @code{COMPLEX}. 11927@end multitable 11928 11929@item @emph{Return value}: 11930The return value is of type @code{INTEGER} and of the default integer 11931kind. 11932 11933@item @emph{See also}: 11934@ref{SELECTED_REAL_KIND}, @ref{PRECISION} 11935 11936@item @emph{Example}: 11937See @code{PRECISION} for an example. 11938@end table 11939 11940 11941 11942@node RANK 11943@section @code{RANK} --- Rank of a data object 11944@fnindex RANK 11945@cindex rank 11946 11947@table @asis 11948@item @emph{Description}: 11949@code{RANK(A)} returns the rank of a scalar or array data object. 11950 11951@item @emph{Standard}: 11952Technical Specification (TS) 29113 11953 11954@item @emph{Class}: 11955Inquiry function 11956 11957@item @emph{Syntax}: 11958@code{RESULT = RANK(A)} 11959 11960@item @emph{Arguments}: 11961@multitable @columnfractions .15 .70 11962@item @var{A} @tab can be of any type 11963@end multitable 11964 11965@item @emph{Return value}: 11966The return value is of type @code{INTEGER} and of the default integer 11967kind. For arrays, their rank is returned; for scalars zero is returned. 11968 11969@item @emph{Example}: 11970@smallexample 11971program test_rank 11972 integer :: a 11973 real, allocatable :: b(:,:) 11974 11975 print *, rank(a), rank(b) ! Prints: 0 2 11976end program test_rank 11977@end smallexample 11978 11979@end table 11980 11981 11982 11983@node REAL 11984@section @code{REAL} --- Convert to real type 11985@fnindex REAL 11986@fnindex REALPART 11987@fnindex FLOAT 11988@fnindex DFLOAT 11989@fnindex FLOATI 11990@fnindex FLOATJ 11991@fnindex FLOATK 11992@fnindex SNGL 11993@cindex conversion, to real 11994@cindex complex numbers, real part 11995 11996@table @asis 11997@item @emph{Description}: 11998@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The 11999@code{REALPART} function is provided for compatibility with @command{g77}, 12000and its use is strongly discouraged. 12001 12002@item @emph{Standard}: 12003Fortran 77 and later 12004 12005@item @emph{Class}: 12006Elemental function 12007 12008@item @emph{Syntax}: 12009@multitable @columnfractions .80 12010@item @code{RESULT = REAL(A [, KIND])} 12011@item @code{RESULT = REALPART(Z)} 12012@end multitable 12013 12014@item @emph{Arguments}: 12015@multitable @columnfractions .15 .70 12016@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or 12017@code{COMPLEX}. 12018@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12019expression indicating the kind parameter of the result. 12020@end multitable 12021 12022@item @emph{Return value}: 12023These functions return a @code{REAL} variable or array under 12024the following rules: 12025 12026@table @asis 12027@item (A) 12028@code{REAL(A)} is converted to a default real type if @var{A} is an 12029integer or real variable. 12030@item (B) 12031@code{REAL(A)} is converted to a real type with the kind type parameter 12032of @var{A} if @var{A} is a complex variable. 12033@item (C) 12034@code{REAL(A, KIND)} is converted to a real type with kind type 12035parameter @var{KIND} if @var{A} is a complex, integer, or real 12036variable. 12037@end table 12038 12039@item @emph{Example}: 12040@smallexample 12041program test_real 12042 complex :: x = (1.0, 2.0) 12043 print *, real(x), real(x,8), realpart(x) 12044end program test_real 12045@end smallexample 12046 12047@item @emph{Specific names}: 12048@multitable @columnfractions .20 .20 .20 .25 12049@item Name @tab Argument @tab Return type @tab Standard 12050@item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later 12051@item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension 12052@item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension 12053@item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension 12054@item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension 12055@item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later 12056@end multitable 12057 12058 12059@item @emph{See also}: 12060@ref{DBLE} 12061 12062@end table 12063 12064 12065 12066@node RENAME 12067@section @code{RENAME} --- Rename a file 12068@fnindex RENAME 12069@cindex file system, rename file 12070 12071@table @asis 12072@item @emph{Description}: 12073Renames a file from file @var{PATH1} to @var{PATH2}. A null 12074character (@code{CHAR(0)}) can be used to mark the end of the names in 12075@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 12076names are ignored. If the @var{STATUS} argument is supplied, it 12077contains 0 on success or a nonzero error code upon return; see 12078@code{rename(2)}. 12079 12080This intrinsic is provided in both subroutine and function forms; 12081however, only one form can be used in any given program unit. 12082 12083@item @emph{Standard}: 12084GNU extension 12085 12086@item @emph{Class}: 12087Subroutine, function 12088 12089@item @emph{Syntax}: 12090@multitable @columnfractions .80 12091@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])} 12092@item @code{STATUS = RENAME(PATH1, PATH2)} 12093@end multitable 12094 12095@item @emph{Arguments}: 12096@multitable @columnfractions .15 .70 12097@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 12098@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 12099@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 12100@end multitable 12101 12102@item @emph{See also}: 12103@ref{LINK} 12104 12105@end table 12106 12107 12108 12109@node REPEAT 12110@section @code{REPEAT} --- Repeated string concatenation 12111@fnindex REPEAT 12112@cindex string, repeat 12113@cindex string, concatenate 12114 12115@table @asis 12116@item @emph{Description}: 12117Concatenates @var{NCOPIES} copies of a string. 12118 12119@item @emph{Standard}: 12120Fortran 95 and later 12121 12122@item @emph{Class}: 12123Transformational function 12124 12125@item @emph{Syntax}: 12126@code{RESULT = REPEAT(STRING, NCOPIES)} 12127 12128@item @emph{Arguments}: 12129@multitable @columnfractions .15 .70 12130@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}. 12131@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}. 12132@end multitable 12133 12134@item @emph{Return value}: 12135A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies 12136of @var{STRING}. 12137 12138@item @emph{Example}: 12139@smallexample 12140program test_repeat 12141 write(*,*) repeat("x", 5) ! "xxxxx" 12142end program 12143@end smallexample 12144@end table 12145 12146 12147 12148@node RESHAPE 12149@section @code{RESHAPE} --- Function to reshape an array 12150@fnindex RESHAPE 12151@cindex array, change dimensions 12152@cindex array, transmogrify 12153 12154@table @asis 12155@item @emph{Description}: 12156Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary, 12157the new array may be padded with elements from @var{PAD} or permuted 12158as defined by @var{ORDER}. 12159 12160@item @emph{Standard}: 12161Fortran 95 and later 12162 12163@item @emph{Class}: 12164Transformational function 12165 12166@item @emph{Syntax}: 12167@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])} 12168 12169@item @emph{Arguments}: 12170@multitable @columnfractions .15 .70 12171@item @var{SOURCE} @tab Shall be an array of any type. 12172@item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an 12173array of rank one. Its values must be positive or zero. 12174@item @var{PAD} @tab (Optional) shall be an array of the same 12175type as @var{SOURCE}. 12176@item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER} 12177and an array of the same shape as @var{SHAPE}. Its values shall 12178be a permutation of the numbers from 1 to n, where n is the size of 12179@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall 12180be assumed. 12181@end multitable 12182 12183@item @emph{Return value}: 12184The result is an array of shape @var{SHAPE} with the same type as 12185@var{SOURCE}. 12186 12187@item @emph{Example}: 12188@smallexample 12189PROGRAM test_reshape 12190 INTEGER, DIMENSION(4) :: x 12191 WRITE(*,*) SHAPE(x) ! prints "4" 12192 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" 12193END PROGRAM 12194@end smallexample 12195 12196@item @emph{See also}: 12197@ref{SHAPE} 12198@end table 12199 12200 12201 12202@node RRSPACING 12203@section @code{RRSPACING} --- Reciprocal of the relative spacing 12204@fnindex RRSPACING 12205@cindex real number, relative spacing 12206@cindex floating point, relative spacing 12207 12208 12209@table @asis 12210@item @emph{Description}: 12211@code{RRSPACING(X)} returns the reciprocal of the relative spacing of 12212model numbers near @var{X}. 12213 12214@item @emph{Standard}: 12215Fortran 95 and later 12216 12217@item @emph{Class}: 12218Elemental function 12219 12220@item @emph{Syntax}: 12221@code{RESULT = RRSPACING(X)} 12222 12223@item @emph{Arguments}: 12224@multitable @columnfractions .15 .70 12225@item @var{X} @tab Shall be of type @code{REAL}. 12226@end multitable 12227 12228@item @emph{Return value}: 12229The return value is of the same type and kind as @var{X}. 12230The value returned is equal to 12231@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}. 12232 12233@item @emph{See also}: 12234@ref{SPACING} 12235@end table 12236 12237 12238 12239@node RSHIFT 12240@section @code{RSHIFT} --- Right shift bits 12241@fnindex RSHIFT 12242@cindex bits, shift right 12243 12244@table @asis 12245@item @emph{Description}: 12246@code{RSHIFT} returns a value corresponding to @var{I} with all of the 12247bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be 12248nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 12249the result value is undefined. Bits shifted out from the right end 12250are lost. The fill is arithmetic: the bits shifted in from the left 12251end are equal to the leftmost bit, which in two's complement 12252representation is the sign bit. 12253 12254This function has been superseded by the @code{SHIFTA} intrinsic, which 12255is standard in Fortran 2008 and later. 12256 12257@item @emph{Standard}: 12258GNU extension 12259 12260@item @emph{Class}: 12261Elemental function 12262 12263@item @emph{Syntax}: 12264@code{RESULT = RSHIFT(I, SHIFT)} 12265 12266@item @emph{Arguments}: 12267@multitable @columnfractions .15 .70 12268@item @var{I} @tab The type shall be @code{INTEGER}. 12269@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12270@end multitable 12271 12272@item @emph{Return value}: 12273The return value is of type @code{INTEGER} and of the same kind as 12274@var{I}. 12275 12276@item @emph{See also}: 12277@ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR}, 12278@ref{SHIFTL} 12279 12280@end table 12281 12282 12283 12284@node SAME_TYPE_AS 12285@section @code{SAME_TYPE_AS} --- Query dynamic types for equality 12286@fnindex SAME_TYPE_AS 12287 12288@table @asis 12289@item @emph{Description}: 12290Query dynamic types for equality. 12291 12292@item @emph{Standard}: 12293Fortran 2003 and later 12294 12295@item @emph{Class}: 12296Inquiry function 12297 12298@item @emph{Syntax}: 12299@code{RESULT = SAME_TYPE_AS(A, B)} 12300 12301@item @emph{Arguments}: 12302@multitable @columnfractions .15 .70 12303@item @var{A} @tab Shall be an object of extensible declared type or 12304unlimited polymorphic. 12305@item @var{B} @tab Shall be an object of extensible declared type or 12306unlimited polymorphic. 12307@end multitable 12308 12309@item @emph{Return value}: 12310The return value is a scalar of type default logical. It is true if and 12311only if the dynamic type of A is the same as the dynamic type of B. 12312 12313@item @emph{See also}: 12314@ref{EXTENDS_TYPE_OF} 12315 12316@end table 12317 12318 12319 12320@node SCALE 12321@section @code{SCALE} --- Scale a real value 12322@fnindex SCALE 12323@cindex real number, scale 12324@cindex floating point, scale 12325 12326@table @asis 12327@item @emph{Description}: 12328@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}. 12329 12330@item @emph{Standard}: 12331Fortran 95 and later 12332 12333@item @emph{Class}: 12334Elemental function 12335 12336@item @emph{Syntax}: 12337@code{RESULT = SCALE(X, I)} 12338 12339@item @emph{Arguments}: 12340@multitable @columnfractions .15 .70 12341@item @var{X} @tab The type of the argument shall be a @code{REAL}. 12342@item @var{I} @tab The type of the argument shall be a @code{INTEGER}. 12343@end multitable 12344 12345@item @emph{Return value}: 12346The return value is of the same type and kind as @var{X}. 12347Its value is @code{X * RADIX(X)**I}. 12348 12349@item @emph{Example}: 12350@smallexample 12351program test_scale 12352 real :: x = 178.1387e-4 12353 integer :: i = 5 12354 print *, scale(x,i), x*radix(x)**i 12355end program test_scale 12356@end smallexample 12357 12358@end table 12359 12360 12361 12362@node SCAN 12363@section @code{SCAN} --- Scan a string for the presence of a set of characters 12364@fnindex SCAN 12365@cindex string, find subset 12366 12367@table @asis 12368@item @emph{Description}: 12369Scans a @var{STRING} for any of the characters in a @var{SET} 12370of characters. 12371 12372If @var{BACK} is either absent or equals @code{FALSE}, this function 12373returns the position of the leftmost character of @var{STRING} that is 12374in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position 12375is returned. If no character of @var{SET} is found in @var{STRING}, the 12376result is zero. 12377 12378@item @emph{Standard}: 12379Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 12380 12381@item @emph{Class}: 12382Elemental function 12383 12384@item @emph{Syntax}: 12385@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])} 12386 12387@item @emph{Arguments}: 12388@multitable @columnfractions .15 .70 12389@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 12390@item @var{SET} @tab Shall be of type @code{CHARACTER}. 12391@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 12392@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12393expression indicating the kind parameter of the result. 12394@end multitable 12395 12396@item @emph{Return value}: 12397The return value is of type @code{INTEGER} and of kind @var{KIND}. If 12398@var{KIND} is absent, the return value is of default integer kind. 12399 12400@item @emph{Example}: 12401@smallexample 12402PROGRAM test_scan 12403 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O' 12404 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A' 12405 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none 12406END PROGRAM 12407@end smallexample 12408 12409@item @emph{See also}: 12410@ref{INDEX intrinsic}, @ref{VERIFY} 12411@end table 12412 12413 12414 12415@node SECNDS 12416@section @code{SECNDS} --- Time function 12417@fnindex SECNDS 12418@cindex time, elapsed 12419@cindex elapsed time 12420 12421@table @asis 12422@item @emph{Description}: 12423@code{SECNDS(X)} gets the time in seconds from the real-time system clock. 12424@var{X} is a reference time, also in seconds. If this is zero, the time in 12425seconds from midnight is returned. This function is non-standard and its 12426use is discouraged. 12427 12428@item @emph{Standard}: 12429GNU extension 12430 12431@item @emph{Class}: 12432Function 12433 12434@item @emph{Syntax}: 12435@code{RESULT = SECNDS (X)} 12436 12437@item @emph{Arguments}: 12438@multitable @columnfractions .15 .70 12439@item @var{T} @tab Shall be of type @code{REAL(4)}. 12440@item @var{X} @tab Shall be of type @code{REAL(4)}. 12441@end multitable 12442 12443@item @emph{Return value}: 12444None 12445 12446@item @emph{Example}: 12447@smallexample 12448program test_secnds 12449 integer :: i 12450 real(4) :: t1, t2 12451 print *, secnds (0.0) ! seconds since midnight 12452 t1 = secnds (0.0) ! reference time 12453 do i = 1, 10000000 ! do something 12454 end do 12455 t2 = secnds (t1) ! elapsed time 12456 print *, "Something took ", t2, " seconds." 12457end program test_secnds 12458@end smallexample 12459@end table 12460 12461 12462 12463@node SECOND 12464@section @code{SECOND} --- CPU time function 12465@fnindex SECOND 12466@cindex time, elapsed 12467@cindex elapsed time 12468 12469@table @asis 12470@item @emph{Description}: 12471Returns a @code{REAL(4)} value representing the elapsed CPU time in 12472seconds. This provides the same functionality as the standard 12473@code{CPU_TIME} intrinsic, and is only included for backwards 12474compatibility. 12475 12476This intrinsic is provided in both subroutine and function forms; 12477however, only one form can be used in any given program unit. 12478 12479@item @emph{Standard}: 12480GNU extension 12481 12482@item @emph{Class}: 12483Subroutine, function 12484 12485@item @emph{Syntax}: 12486@multitable @columnfractions .80 12487@item @code{CALL SECOND(TIME)} 12488@item @code{TIME = SECOND()} 12489@end multitable 12490 12491@item @emph{Arguments}: 12492@multitable @columnfractions .15 .70 12493@item @var{TIME} @tab Shall be of type @code{REAL(4)}. 12494@end multitable 12495 12496@item @emph{Return value}: 12497In either syntax, @var{TIME} is set to the process's current runtime in 12498seconds. 12499 12500@item @emph{See also}: 12501@ref{CPU_TIME} 12502 12503@end table 12504 12505 12506 12507@node SELECTED_CHAR_KIND 12508@section @code{SELECTED_CHAR_KIND} --- Choose character kind 12509@fnindex SELECTED_CHAR_KIND 12510@cindex character kind 12511@cindex kind, character 12512 12513@table @asis 12514@item @emph{Description}: 12515 12516@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character 12517set named @var{NAME}, if a character set with such a name is supported, 12518or @math{-1} otherwise. Currently, supported character sets include 12519``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646'' 12520(Universal Character Set, UCS-4) which is commonly known as Unicode. 12521 12522@item @emph{Standard}: 12523Fortran 2003 and later 12524 12525@item @emph{Class}: 12526Transformational function 12527 12528@item @emph{Syntax}: 12529@code{RESULT = SELECTED_CHAR_KIND(NAME)} 12530 12531@item @emph{Arguments}: 12532@multitable @columnfractions .15 .70 12533@item @var{NAME} @tab Shall be a scalar and of the default character type. 12534@end multitable 12535 12536@item @emph{Example}: 12537@smallexample 12538program character_kind 12539 use iso_fortran_env 12540 implicit none 12541 integer, parameter :: ascii = selected_char_kind ("ascii") 12542 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646') 12543 12544 character(kind=ascii, len=26) :: alphabet 12545 character(kind=ucs4, len=30) :: hello_world 12546 12547 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz" 12548 hello_world = ucs4_'Hello World and Ni Hao -- ' & 12549 // char (int (z'4F60'), ucs4) & 12550 // char (int (z'597D'), ucs4) 12551 12552 write (*,*) alphabet 12553 12554 open (output_unit, encoding='UTF-8') 12555 write (*,*) trim (hello_world) 12556end program character_kind 12557@end smallexample 12558@end table 12559 12560 12561 12562@node SELECTED_INT_KIND 12563@section @code{SELECTED_INT_KIND} --- Choose integer kind 12564@fnindex SELECTED_INT_KIND 12565@cindex integer kind 12566@cindex kind, integer 12567 12568@table @asis 12569@item @emph{Description}: 12570@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer 12571type that can represent all values ranging from @math{-10^R} (exclusive) 12572to @math{10^R} (exclusive). If there is no integer kind that accommodates 12573this range, @code{SELECTED_INT_KIND} returns @math{-1}. 12574 12575@item @emph{Standard}: 12576Fortran 95 and later 12577 12578@item @emph{Class}: 12579Transformational function 12580 12581@item @emph{Syntax}: 12582@code{RESULT = SELECTED_INT_KIND(R)} 12583 12584@item @emph{Arguments}: 12585@multitable @columnfractions .15 .70 12586@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}. 12587@end multitable 12588 12589@item @emph{Example}: 12590@smallexample 12591program large_integers 12592 integer,parameter :: k5 = selected_int_kind(5) 12593 integer,parameter :: k15 = selected_int_kind(15) 12594 integer(kind=k5) :: i5 12595 integer(kind=k15) :: i15 12596 12597 print *, huge(i5), huge(i15) 12598 12599 ! The following inequalities are always true 12600 print *, huge(i5) >= 10_k5**5-1 12601 print *, huge(i15) >= 10_k15**15-1 12602end program large_integers 12603@end smallexample 12604@end table 12605 12606 12607 12608@node SELECTED_REAL_KIND 12609@section @code{SELECTED_REAL_KIND} --- Choose real kind 12610@fnindex SELECTED_REAL_KIND 12611@cindex real kind 12612@cindex kind, real 12613@cindex radix, real 12614 12615@table @asis 12616@item @emph{Description}: 12617@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type 12618with decimal precision of at least @code{P} digits, exponent range of 12619at least @code{R}, and with a radix of @code{RADIX}. 12620 12621@item @emph{Standard}: 12622Fortran 95 and later, with @code{RADIX} Fortran 2008 or later 12623 12624@item @emph{Class}: 12625Transformational function 12626 12627@item @emph{Syntax}: 12628@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])} 12629 12630@item @emph{Arguments}: 12631@multitable @columnfractions .15 .70 12632@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12633@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12634@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 12635@end multitable 12636Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall 12637be present; since Fortran 2008, they are assumed to be zero if absent. 12638 12639@item @emph{Return value}: 12640 12641@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of 12642a real data type with decimal precision of at least @code{P} digits, a 12643decimal exponent range of at least @code{R}, and with the requested 12644@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with 12645any radix can be returned. If more than one real data type meet the 12646criteria, the kind of the data type with the smallest decimal precision 12647is returned. If no real data type matches the criteria, the result is 12648@table @asis 12649@item -1 if the processor does not support a real data type with a 12650precision greater than or equal to @code{P}, but the @code{R} and 12651@code{RADIX} requirements can be fulfilled 12652@item -2 if the processor does not support a real type with an exponent 12653range greater than or equal to @code{R}, but @code{P} and @code{RADIX} 12654are fulfillable 12655@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements 12656are fulfillable 12657@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements 12658are fulfillable 12659@item -5 if there is no real type with the given @code{RADIX} 12660@end table 12661 12662@item @emph{See also}: 12663@ref{PRECISION}, @ref{RANGE}, @ref{RADIX} 12664 12665@item @emph{Example}: 12666@smallexample 12667program real_kinds 12668 integer,parameter :: p6 = selected_real_kind(6) 12669 integer,parameter :: p10r100 = selected_real_kind(10,100) 12670 integer,parameter :: r400 = selected_real_kind(r=400) 12671 real(kind=p6) :: x 12672 real(kind=p10r100) :: y 12673 real(kind=r400) :: z 12674 12675 print *, precision(x), range(x) 12676 print *, precision(y), range(y) 12677 print *, precision(z), range(z) 12678end program real_kinds 12679@end smallexample 12680@end table 12681 12682 12683 12684@node SET_EXPONENT 12685@section @code{SET_EXPONENT} --- Set the exponent of the model 12686@fnindex SET_EXPONENT 12687@cindex real number, set exponent 12688@cindex floating point, set exponent 12689 12690@table @asis 12691@item @emph{Description}: 12692@code{SET_EXPONENT(X, I)} returns the real number whose fractional part 12693is that that of @var{X} and whose exponent part is @var{I}. 12694 12695@item @emph{Standard}: 12696Fortran 95 and later 12697 12698@item @emph{Class}: 12699Elemental function 12700 12701@item @emph{Syntax}: 12702@code{RESULT = SET_EXPONENT(X, I)} 12703 12704@item @emph{Arguments}: 12705@multitable @columnfractions .15 .70 12706@item @var{X} @tab Shall be of type @code{REAL}. 12707@item @var{I} @tab Shall be of type @code{INTEGER}. 12708@end multitable 12709 12710@item @emph{Return value}: 12711The return value is of the same type and kind as @var{X}. 12712The real number whose fractional part 12713is that that of @var{X} and whose exponent part if @var{I} is returned; 12714it is @code{FRACTION(X) * RADIX(X)**I}. 12715 12716@item @emph{Example}: 12717@smallexample 12718PROGRAM test_setexp 12719 REAL :: x = 178.1387e-4 12720 INTEGER :: i = 17 12721 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i 12722END PROGRAM 12723@end smallexample 12724 12725@end table 12726 12727 12728 12729@node SHAPE 12730@section @code{SHAPE} --- Determine the shape of an array 12731@fnindex SHAPE 12732@cindex array, shape 12733 12734@table @asis 12735@item @emph{Description}: 12736Determines the shape of an array. 12737 12738@item @emph{Standard}: 12739Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 12740 12741@item @emph{Class}: 12742Inquiry function 12743 12744@item @emph{Syntax}: 12745@code{RESULT = SHAPE(SOURCE [, KIND])} 12746 12747@item @emph{Arguments}: 12748@multitable @columnfractions .15 .70 12749@item @var{SOURCE} @tab Shall be an array or scalar of any type. 12750If @var{SOURCE} is a pointer it must be associated and allocatable 12751arrays must be allocated. 12752@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12753expression indicating the kind parameter of the result. 12754@end multitable 12755 12756@item @emph{Return value}: 12757An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 12758has dimensions. The elements of the resulting array correspond to the extend 12759of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar, 12760the result is the rank one array of size zero. If @var{KIND} is absent, the 12761return value has the default integer kind otherwise the specified kind. 12762 12763@item @emph{Example}: 12764@smallexample 12765PROGRAM test_shape 12766 INTEGER, DIMENSION(-1:1, -1:2) :: A 12767 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) 12768 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) 12769END PROGRAM 12770@end smallexample 12771 12772@item @emph{See also}: 12773@ref{RESHAPE}, @ref{SIZE} 12774@end table 12775 12776 12777 12778@node SHIFTA 12779@section @code{SHIFTA} --- Right shift with fill 12780@fnindex SHIFTA 12781@cindex bits, shift right 12782@cindex shift, right with fill 12783 12784@table @asis 12785@item @emph{Description}: 12786@code{SHIFTA} returns a value corresponding to @var{I} with all of the 12787bits shifted right by @var{SHIFT} places. @var{SHIFT} that be 12788nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 12789the result value is undefined. Bits shifted out from the right end 12790are lost. The fill is arithmetic: the bits shifted in from the left 12791end are equal to the leftmost bit, which in two's complement 12792representation is the sign bit. 12793 12794@item @emph{Standard}: 12795Fortran 2008 and later 12796 12797@item @emph{Class}: 12798Elemental function 12799 12800@item @emph{Syntax}: 12801@code{RESULT = SHIFTA(I, SHIFT)} 12802 12803@item @emph{Arguments}: 12804@multitable @columnfractions .15 .70 12805@item @var{I} @tab The type shall be @code{INTEGER}. 12806@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12807@end multitable 12808 12809@item @emph{Return value}: 12810The return value is of type @code{INTEGER} and of the same kind as 12811@var{I}. 12812 12813@item @emph{See also}: 12814@ref{SHIFTL}, @ref{SHIFTR} 12815@end table 12816 12817 12818 12819@node SHIFTL 12820@section @code{SHIFTL} --- Left shift 12821@fnindex SHIFTL 12822@cindex bits, shift left 12823@cindex shift, left 12824 12825@table @asis 12826@item @emph{Description}: 12827@code{SHIFTL} returns a value corresponding to @var{I} with all of the 12828bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be 12829nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 12830the result value is undefined. Bits shifted out from the left end are 12831lost, and bits shifted in from the right end are set to 0. 12832 12833@item @emph{Standard}: 12834Fortran 2008 and later 12835 12836@item @emph{Class}: 12837Elemental function 12838 12839@item @emph{Syntax}: 12840@code{RESULT = SHIFTL(I, SHIFT)} 12841 12842@item @emph{Arguments}: 12843@multitable @columnfractions .15 .70 12844@item @var{I} @tab The type shall be @code{INTEGER}. 12845@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12846@end multitable 12847 12848@item @emph{Return value}: 12849The return value is of type @code{INTEGER} and of the same kind as 12850@var{I}. 12851 12852@item @emph{See also}: 12853@ref{SHIFTA}, @ref{SHIFTR} 12854@end table 12855 12856 12857 12858@node SHIFTR 12859@section @code{SHIFTR} --- Right shift 12860@fnindex SHIFTR 12861@cindex bits, shift right 12862@cindex shift, right 12863 12864@table @asis 12865@item @emph{Description}: 12866@code{SHIFTR} returns a value corresponding to @var{I} with all of the 12867bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be 12868nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise 12869the result value is undefined. Bits shifted out from the right end 12870are lost, and bits shifted in from the left end are set to 0. 12871 12872@item @emph{Standard}: 12873Fortran 2008 and later 12874 12875@item @emph{Class}: 12876Elemental function 12877 12878@item @emph{Syntax}: 12879@code{RESULT = SHIFTR(I, SHIFT)} 12880 12881@item @emph{Arguments}: 12882@multitable @columnfractions .15 .70 12883@item @var{I} @tab The type shall be @code{INTEGER}. 12884@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12885@end multitable 12886 12887@item @emph{Return value}: 12888The return value is of type @code{INTEGER} and of the same kind as 12889@var{I}. 12890 12891@item @emph{See also}: 12892@ref{SHIFTA}, @ref{SHIFTL} 12893@end table 12894 12895 12896 12897@node SIGN 12898@section @code{SIGN} --- Sign copying function 12899@fnindex SIGN 12900@fnindex ISIGN 12901@fnindex DSIGN 12902@cindex sign copying 12903 12904@table @asis 12905@item @emph{Description}: 12906@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}. 12907 12908@item @emph{Standard}: 12909Fortran 77 and later 12910 12911@item @emph{Class}: 12912Elemental function 12913 12914@item @emph{Syntax}: 12915@code{RESULT = SIGN(A, B)} 12916 12917@item @emph{Arguments}: 12918@multitable @columnfractions .15 .70 12919@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL} 12920@item @var{B} @tab Shall be of the same type and kind as @var{A} 12921@end multitable 12922 12923@item @emph{Return value}: 12924The kind of the return value is that of @var{A} and @var{B}. 12925If @math{B\ge 0} then the result is @code{ABS(A)}, else 12926it is @code{-ABS(A)}. 12927 12928@item @emph{Example}: 12929@smallexample 12930program test_sign 12931 print *, sign(-12,1) 12932 print *, sign(-12,0) 12933 print *, sign(-12,-1) 12934 12935 print *, sign(-12.,1.) 12936 print *, sign(-12.,0.) 12937 print *, sign(-12.,-1.) 12938end program test_sign 12939@end smallexample 12940 12941@item @emph{Specific names}: 12942@multitable @columnfractions .20 .20 .20 .25 12943@item Name @tab Arguments @tab Return type @tab Standard 12944@item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu 12945@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu 12946@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu 12947@end multitable 12948@end table 12949 12950 12951 12952@node SIGNAL 12953@section @code{SIGNAL} --- Signal handling subroutine (or function) 12954@fnindex SIGNAL 12955@cindex system, signal handling 12956 12957@table @asis 12958@item @emph{Description}: 12959@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine 12960@var{HANDLER} to be executed with a single integer argument when signal 12961@var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to 12962turn off handling of signal @var{NUMBER} or revert to its default 12963action. See @code{signal(2)}. 12964 12965If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument 12966is supplied, it is set to the value returned by @code{signal(2)}. 12967 12968@item @emph{Standard}: 12969GNU extension 12970 12971@item @emph{Class}: 12972Subroutine, function 12973 12974@item @emph{Syntax}: 12975@multitable @columnfractions .80 12976@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])} 12977@item @code{STATUS = SIGNAL(NUMBER, HANDLER)} 12978@end multitable 12979 12980@item @emph{Arguments}: 12981@multitable @columnfractions .15 .70 12982@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)} 12983@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or 12984@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. 12985@code{INTEGER}. It is @code{INTENT(IN)}. 12986@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 12987integer. It has @code{INTENT(OUT)}. 12988@end multitable 12989@c TODO: What should the interface of the handler be? Does it take arguments? 12990 12991@item @emph{Return value}: 12992The @code{SIGNAL} function returns the value returned by @code{signal(2)}. 12993 12994@item @emph{Example}: 12995@smallexample 12996program test_signal 12997 intrinsic signal 12998 external handler_print 12999 13000 call signal (12, handler_print) 13001 call signal (10, 1) 13002 13003 call sleep (30) 13004end program test_signal 13005@end smallexample 13006@end table 13007 13008 13009 13010@node SIN 13011@section @code{SIN} --- Sine function 13012@fnindex SIN 13013@fnindex DSIN 13014@fnindex CSIN 13015@fnindex ZSIN 13016@fnindex CDSIN 13017@cindex trigonometric function, sine 13018@cindex sine 13019 13020@table @asis 13021@item @emph{Description}: 13022@code{SIN(X)} computes the sine of @var{X}. 13023 13024@item @emph{Standard}: 13025Fortran 77 and later 13026 13027@item @emph{Class}: 13028Elemental function 13029 13030@item @emph{Syntax}: 13031@code{RESULT = SIN(X)} 13032 13033@item @emph{Arguments}: 13034@multitable @columnfractions .15 .70 13035@item @var{X} @tab The type shall be @code{REAL} or 13036@code{COMPLEX}. 13037@end multitable 13038 13039@item @emph{Return value}: 13040The return value has same type and kind as @var{X}. 13041 13042@item @emph{Example}: 13043@smallexample 13044program test_sin 13045 real :: x = 0.0 13046 x = sin(x) 13047end program test_sin 13048@end smallexample 13049 13050@item @emph{Specific names}: 13051@multitable @columnfractions .20 .20 .20 .25 13052@item Name @tab Argument @tab Return type @tab Standard 13053@item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu 13054@item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu 13055@item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu 13056@item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 13057@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 13058@end multitable 13059 13060@item @emph{See also}: 13061Inverse function: @ref{ASIN} 13062Degrees function: @ref{SIND} 13063@end table 13064 13065 13066 13067@node SIND 13068@section @code{SIND} --- Sine function, degrees 13069@fnindex SIND 13070@fnindex DSIND 13071@fnindex CSIND 13072@fnindex ZSIND 13073@fnindex CDSIND 13074@cindex trigonometric function, sine, degrees 13075@cindex sine, degrees 13076 13077@table @asis 13078@item @emph{Description}: 13079@code{SIND(X)} computes the sine of @var{X} in degrees. 13080 13081This function is for compatibility only and should be avoided in favor of 13082standard constructs wherever possible. 13083 13084@item @emph{Standard}: 13085GNU Extension, enabled with @option{-fdec-math}. 13086 13087@item @emph{Class}: 13088Elemental function 13089 13090@item @emph{Syntax}: 13091@code{RESULT = SIND(X)} 13092 13093@item @emph{Arguments}: 13094@multitable @columnfractions .15 .70 13095@item @var{X} @tab The type shall be @code{REAL} or 13096@code{COMPLEX}. 13097@end multitable 13098 13099@item @emph{Return value}: 13100The return value has same type and kind as @var{X}, and its value is in degrees. 13101 13102@item @emph{Example}: 13103@smallexample 13104program test_sind 13105 real :: x = 0.0 13106 x = sind(x) 13107end program test_sind 13108@end smallexample 13109 13110@item @emph{Specific names}: 13111@multitable @columnfractions .20 .20 .20 .25 13112@item Name @tab Argument @tab Return type @tab Standard 13113@item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 13114@item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 13115@item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension 13116@item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension 13117@item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension 13118@end multitable 13119 13120@item @emph{See also}: 13121Inverse function: @ref{ASIND} 13122Radians function: @ref{SIN} 13123 13124@end table 13125 13126 13127 13128@node SINH 13129@section @code{SINH} --- Hyperbolic sine function 13130@fnindex SINH 13131@fnindex DSINH 13132@cindex hyperbolic sine 13133@cindex hyperbolic function, sine 13134@cindex sine, hyperbolic 13135 13136@table @asis 13137@item @emph{Description}: 13138@code{SINH(X)} computes the hyperbolic sine of @var{X}. 13139 13140@item @emph{Standard}: 13141Fortran 95 and later, for a complex argument Fortran 2008 or later 13142 13143@item @emph{Class}: 13144Elemental function 13145 13146@item @emph{Syntax}: 13147@code{RESULT = SINH(X)} 13148 13149@item @emph{Arguments}: 13150@multitable @columnfractions .15 .70 13151@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13152@end multitable 13153 13154@item @emph{Return value}: 13155The return value has same type and kind as @var{X}. 13156 13157@item @emph{Example}: 13158@smallexample 13159program test_sinh 13160 real(8) :: x = - 1.0_8 13161 x = sinh(x) 13162end program test_sinh 13163@end smallexample 13164 13165@item @emph{Specific names}: 13166@multitable @columnfractions .20 .20 .20 .25 13167@item Name @tab Argument @tab Return type @tab Standard 13168@item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 13169@item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 13170@end multitable 13171 13172@item @emph{See also}: 13173@ref{ASINH} 13174@end table 13175 13176 13177 13178@node SIZE 13179@section @code{SIZE} --- Determine the size of an array 13180@fnindex SIZE 13181@cindex array, size 13182@cindex array, number of elements 13183@cindex array, count elements 13184 13185@table @asis 13186@item @emph{Description}: 13187Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}, 13188or the total number of elements in @var{ARRAY} if @var{DIM} is absent. 13189 13190@item @emph{Standard}: 13191Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 13192 13193@item @emph{Class}: 13194Inquiry function 13195 13196@item @emph{Syntax}: 13197@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])} 13198 13199@item @emph{Arguments}: 13200@multitable @columnfractions .15 .70 13201@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is 13202a pointer it must be associated and allocatable arrays must be allocated. 13203@item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} 13204and its value shall be in the range from 1 to n, where n equals the rank 13205of @var{ARRAY}. 13206@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13207expression indicating the kind parameter of the result. 13208@end multitable 13209 13210@item @emph{Return value}: 13211The return value is of type @code{INTEGER} and of kind @var{KIND}. If 13212@var{KIND} is absent, the return value is of default integer kind. 13213 13214@item @emph{Example}: 13215@smallexample 13216PROGRAM test_size 13217 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 13218END PROGRAM 13219@end smallexample 13220 13221@item @emph{See also}: 13222@ref{SHAPE}, @ref{RESHAPE} 13223@end table 13224 13225 13226@node SIZEOF 13227@section @code{SIZEOF} --- Size in bytes of an expression 13228@fnindex SIZEOF 13229@cindex expression size 13230@cindex size of an expression 13231 13232@table @asis 13233@item @emph{Description}: 13234@code{SIZEOF(X)} calculates the number of bytes of storage the 13235expression @code{X} occupies. 13236 13237@item @emph{Standard}: 13238GNU extension 13239 13240@item @emph{Class}: 13241Inquiry function 13242 13243@item @emph{Syntax}: 13244@code{N = SIZEOF(X)} 13245 13246@item @emph{Arguments}: 13247@multitable @columnfractions .15 .70 13248@item @var{X} @tab The argument shall be of any type, rank or shape. 13249@end multitable 13250 13251@item @emph{Return value}: 13252The return value is of type integer and of the system-dependent kind 13253@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the 13254number of bytes occupied by the argument. If the argument has the 13255@code{POINTER} attribute, the number of bytes of the storage area pointed 13256to is returned. If the argument is of a derived type with @code{POINTER} 13257or @code{ALLOCATABLE} components, the return value does not account for 13258the sizes of the data pointed to by these components. If the argument is 13259polymorphic, the size according to the dynamic type is returned. The argument 13260may not be a procedure or procedure pointer. Note that the code assumes for 13261arrays that those are contiguous; for contiguous arrays, it returns the 13262storage or an array element multiplied by the size of the array. 13263 13264@item @emph{Example}: 13265@smallexample 13266 integer :: i 13267 real :: r, s(5) 13268 print *, (sizeof(s)/sizeof(r) == 5) 13269 end 13270@end smallexample 13271The example will print @code{.TRUE.} unless you are using a platform 13272where default @code{REAL} variables are unusually padded. 13273 13274@item @emph{See also}: 13275@ref{C_SIZEOF}, @ref{STORAGE_SIZE} 13276@end table 13277 13278 13279@node SLEEP 13280@section @code{SLEEP} --- Sleep for the specified number of seconds 13281@fnindex SLEEP 13282@cindex delayed execution 13283 13284@table @asis 13285@item @emph{Description}: 13286Calling this subroutine causes the process to pause for @var{SECONDS} seconds. 13287 13288@item @emph{Standard}: 13289GNU extension 13290 13291@item @emph{Class}: 13292Subroutine 13293 13294@item @emph{Syntax}: 13295@code{CALL SLEEP(SECONDS)} 13296 13297@item @emph{Arguments}: 13298@multitable @columnfractions .15 .70 13299@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}. 13300@end multitable 13301 13302@item @emph{Example}: 13303@smallexample 13304program test_sleep 13305 call sleep(5) 13306end 13307@end smallexample 13308@end table 13309 13310 13311 13312@node SPACING 13313@section @code{SPACING} --- Smallest distance between two numbers of a given type 13314@fnindex SPACING 13315@cindex real number, relative spacing 13316@cindex floating point, relative spacing 13317 13318@table @asis 13319@item @emph{Description}: 13320Determines the distance between the argument @var{X} and the nearest 13321adjacent number of the same type. 13322 13323@item @emph{Standard}: 13324Fortran 95 and later 13325 13326@item @emph{Class}: 13327Elemental function 13328 13329@item @emph{Syntax}: 13330@code{RESULT = SPACING(X)} 13331 13332@item @emph{Arguments}: 13333@multitable @columnfractions .15 .70 13334@item @var{X} @tab Shall be of type @code{REAL}. 13335@end multitable 13336 13337@item @emph{Return value}: 13338The result is of the same type as the input argument @var{X}. 13339 13340@item @emph{Example}: 13341@smallexample 13342PROGRAM test_spacing 13343 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37) 13344 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200) 13345 13346 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686 13347 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686 13348END PROGRAM 13349@end smallexample 13350 13351@item @emph{See also}: 13352@ref{RRSPACING} 13353@end table 13354 13355 13356 13357@node SPREAD 13358@section @code{SPREAD} --- Add a dimension to an array 13359@fnindex SPREAD 13360@cindex array, increase dimension 13361@cindex array, duplicate elements 13362@cindex array, duplicate dimensions 13363 13364@table @asis 13365@item @emph{Description}: 13366Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified 13367dimension @var{DIM}. 13368 13369@item @emph{Standard}: 13370Fortran 95 and later 13371 13372@item @emph{Class}: 13373Transformational function 13374 13375@item @emph{Syntax}: 13376@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)} 13377 13378@item @emph{Arguments}: 13379@multitable @columnfractions .15 .70 13380@item @var{SOURCE} @tab Shall be a scalar or an array of any type and 13381a rank less than seven. 13382@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a 13383value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}. 13384@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}. 13385@end multitable 13386 13387@item @emph{Return value}: 13388The result is an array of the same type as @var{SOURCE} and has rank n+1 13389where n equals the rank of @var{SOURCE}. 13390 13391@item @emph{Example}: 13392@smallexample 13393PROGRAM test_spread 13394 INTEGER :: a = 1, b(2) = (/ 1, 2 /) 13395 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1" 13396 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2" 13397END PROGRAM 13398@end smallexample 13399 13400@item @emph{See also}: 13401@ref{UNPACK} 13402@end table 13403 13404 13405 13406@node SQRT 13407@section @code{SQRT} --- Square-root function 13408@fnindex SQRT 13409@fnindex DSQRT 13410@fnindex CSQRT 13411@fnindex ZSQRT 13412@fnindex CDSQRT 13413@cindex root 13414@cindex square-root 13415 13416@table @asis 13417@item @emph{Description}: 13418@code{SQRT(X)} computes the square root of @var{X}. 13419 13420@item @emph{Standard}: 13421Fortran 77 and later 13422 13423@item @emph{Class}: 13424Elemental function 13425 13426@item @emph{Syntax}: 13427@code{RESULT = SQRT(X)} 13428 13429@item @emph{Arguments}: 13430@multitable @columnfractions .15 .70 13431@item @var{X} @tab The type shall be @code{REAL} or 13432@code{COMPLEX}. 13433@end multitable 13434 13435@item @emph{Return value}: 13436The return value is of type @code{REAL} or @code{COMPLEX}. 13437The kind type parameter is the same as @var{X}. 13438 13439@item @emph{Example}: 13440@smallexample 13441program test_sqrt 13442 real(8) :: x = 2.0_8 13443 complex :: z = (1.0, 2.0) 13444 x = sqrt(x) 13445 z = sqrt(z) 13446end program test_sqrt 13447@end smallexample 13448 13449@item @emph{Specific names}: 13450@multitable @columnfractions .20 .20 .20 .25 13451@item Name @tab Argument @tab Return type @tab Standard 13452@item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 13453@item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 13454@item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later 13455@item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13456@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 13457@end multitable 13458@end table 13459 13460 13461 13462@node SRAND 13463@section @code{SRAND} --- Reinitialize the random number generator 13464@fnindex SRAND 13465@cindex random number generation, seeding 13466@cindex seeding a random number generator 13467 13468@table @asis 13469@item @emph{Description}: 13470@code{SRAND} reinitializes the pseudo-random number generator 13471called by @code{RAND} and @code{IRAND}. The new seed used by the 13472generator is specified by the required argument @var{SEED}. 13473 13474@item @emph{Standard}: 13475GNU extension 13476 13477@item @emph{Class}: 13478Subroutine 13479 13480@item @emph{Syntax}: 13481@code{CALL SRAND(SEED)} 13482 13483@item @emph{Arguments}: 13484@multitable @columnfractions .15 .70 13485@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}. 13486@end multitable 13487 13488@item @emph{Return value}: 13489Does not return anything. 13490 13491@item @emph{Example}: 13492See @code{RAND} and @code{IRAND} for examples. 13493 13494@item @emph{Notes}: 13495The Fortran standard specifies the intrinsic subroutines 13496@code{RANDOM_SEED} to initialize the pseudo-random number 13497generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers. 13498These subroutines should be used in new codes. 13499 13500Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND}, 13501@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and 13502@code{RANDOM_SEED} on the other hand) access two independent 13503pseudo-random number generators. 13504 13505@item @emph{See also}: 13506@ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER} 13507 13508@end table 13509 13510 13511 13512@node STAT 13513@section @code{STAT} --- Get file status 13514@fnindex STAT 13515@cindex file system, file status 13516 13517@table @asis 13518@item @emph{Description}: 13519This function returns information about a file. No permissions are required on 13520the file itself, but execute (search) permission is required on all of the 13521directories in path that lead to the file. 13522 13523The elements that are obtained and stored in the array @code{VALUES}: 13524@multitable @columnfractions .15 .70 13525@item @code{VALUES(1)} @tab Device ID 13526@item @code{VALUES(2)} @tab Inode number 13527@item @code{VALUES(3)} @tab File mode 13528@item @code{VALUES(4)} @tab Number of links 13529@item @code{VALUES(5)} @tab Owner's uid 13530@item @code{VALUES(6)} @tab Owner's gid 13531@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available) 13532@item @code{VALUES(8)} @tab File size (bytes) 13533@item @code{VALUES(9)} @tab Last access time 13534@item @code{VALUES(10)} @tab Last modification time 13535@item @code{VALUES(11)} @tab Last file status change time 13536@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available) 13537@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available) 13538@end multitable 13539 13540Not all these elements are relevant on all systems. 13541If an element is not relevant, it is returned as 0. 13542 13543This intrinsic is provided in both subroutine and function forms; however, 13544only one form can be used in any given program unit. 13545 13546@item @emph{Standard}: 13547GNU extension 13548 13549@item @emph{Class}: 13550Subroutine, function 13551 13552@item @emph{Syntax}: 13553@multitable @columnfractions .80 13554@item @code{CALL STAT(NAME, VALUES [, STATUS])} 13555@item @code{STATUS = STAT(NAME, VALUES)} 13556@end multitable 13557 13558@item @emph{Arguments}: 13559@multitable @columnfractions .15 .70 13560@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the 13561default kind and a valid path within the file system. 13562@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 13563@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 13564on success and a system specific error code otherwise. 13565@end multitable 13566 13567@item @emph{Example}: 13568@smallexample 13569PROGRAM test_stat 13570 INTEGER, DIMENSION(13) :: buff 13571 INTEGER :: status 13572 13573 CALL STAT("/etc/passwd", buff, status) 13574 13575 IF (status == 0) THEN 13576 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1) 13577 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2) 13578 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3) 13579 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4) 13580 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5) 13581 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6) 13582 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7) 13583 WRITE (*, FMT="('File size:', T30, I19)") buff(8) 13584 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9)) 13585 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10)) 13586 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11)) 13587 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12) 13588 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13) 13589 END IF 13590END PROGRAM 13591@end smallexample 13592 13593@item @emph{See also}: 13594To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT} 13595@end table 13596 13597 13598 13599@node STORAGE_SIZE 13600@section @code{STORAGE_SIZE} --- Storage size in bits 13601@fnindex STORAGE_SIZE 13602@cindex storage size 13603 13604@table @asis 13605@item @emph{Description}: 13606Returns the storage size of argument @var{A} in bits. 13607@item @emph{Standard}: 13608Fortran 2008 and later 13609@item @emph{Class}: 13610Inquiry function 13611@item @emph{Syntax}: 13612@code{RESULT = STORAGE_SIZE(A [, KIND])} 13613 13614@item @emph{Arguments}: 13615@multitable @columnfractions .15 .70 13616@item @var{A} @tab Shall be a scalar or array of any type. 13617@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression. 13618@end multitable 13619 13620@item @emph{Return Value}: 13621The result is a scalar integer with the kind type parameter specified by KIND 13622(or default integer type if KIND is missing). The result value is the size 13623expressed in bits for an element of an array that has the dynamic type and type 13624parameters of A. 13625 13626@item @emph{See also}: 13627@ref{C_SIZEOF}, @ref{SIZEOF} 13628@end table 13629 13630 13631 13632@node SUM 13633@section @code{SUM} --- Sum of array elements 13634@fnindex SUM 13635@cindex array, sum 13636@cindex array, add elements 13637@cindex array, conditionally add elements 13638@cindex sum array elements 13639 13640@table @asis 13641@item @emph{Description}: 13642Adds the elements of @var{ARRAY} along dimension @var{DIM} if 13643the corresponding element in @var{MASK} is @code{TRUE}. 13644 13645@item @emph{Standard}: 13646Fortran 95 and later 13647 13648@item @emph{Class}: 13649Transformational function 13650 13651@item @emph{Syntax}: 13652@multitable @columnfractions .80 13653@item @code{RESULT = SUM(ARRAY[, MASK])} 13654@item @code{RESULT = SUM(ARRAY, DIM[, MASK])} 13655@end multitable 13656 13657@item @emph{Arguments}: 13658@multitable @columnfractions .15 .70 13659@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 13660@code{REAL} or @code{COMPLEX}. 13661@item @var{DIM} @tab (Optional) shall be a scalar of type 13662@code{INTEGER} with a value in the range from 1 to n, where n 13663equals the rank of @var{ARRAY}. 13664@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 13665and either be a scalar or an array of the same shape as @var{ARRAY}. 13666@end multitable 13667 13668@item @emph{Return value}: 13669The result is of the same type as @var{ARRAY}. 13670 13671If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY} 13672is returned. Otherwise, an array of rank n-1, where n equals the rank of 13673@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} 13674dropped is returned. 13675 13676@item @emph{Example}: 13677@smallexample 13678PROGRAM test_sum 13679 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 13680 print *, SUM(x) ! all elements, sum = 15 13681 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9 13682END PROGRAM 13683@end smallexample 13684 13685@item @emph{See also}: 13686@ref{PRODUCT} 13687@end table 13688 13689 13690 13691@node SYMLNK 13692@section @code{SYMLNK} --- Create a symbolic link 13693@fnindex SYMLNK 13694@cindex file system, create link 13695@cindex file system, soft link 13696 13697@table @asis 13698@item @emph{Description}: 13699Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null 13700character (@code{CHAR(0)}) can be used to mark the end of the names in 13701@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 13702names are ignored. If the @var{STATUS} argument is supplied, it 13703contains 0 on success or a nonzero error code upon return; see 13704@code{symlink(2)}. If the system does not supply @code{symlink(2)}, 13705@code{ENOSYS} is returned. 13706 13707This intrinsic is provided in both subroutine and function forms; 13708however, only one form can be used in any given program unit. 13709 13710@item @emph{Standard}: 13711GNU extension 13712 13713@item @emph{Class}: 13714Subroutine, function 13715 13716@item @emph{Syntax}: 13717@multitable @columnfractions .80 13718@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])} 13719@item @code{STATUS = SYMLNK(PATH1, PATH2)} 13720@end multitable 13721 13722@item @emph{Arguments}: 13723@multitable @columnfractions .15 .70 13724@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 13725@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 13726@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13727@end multitable 13728 13729@item @emph{See also}: 13730@ref{LINK}, @ref{UNLINK} 13731 13732@end table 13733 13734 13735 13736@node SYSTEM 13737@section @code{SYSTEM} --- Execute a shell command 13738@fnindex SYSTEM 13739@cindex system, system call 13740 13741@table @asis 13742@item @emph{Description}: 13743Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If 13744argument @var{STATUS} is present, it contains the value returned by 13745@code{system(3)}, which is presumably 0 if the shell command succeeded. 13746Note that which shell is used to invoke the command is system-dependent 13747and environment-dependent. 13748 13749This intrinsic is provided in both subroutine and function forms; 13750however, only one form can be used in any given program unit. 13751 13752Note that the @code{system} function need not be thread-safe. It is 13753the responsibility of the user to ensure that @code{system} is not 13754called concurrently. 13755 13756@item @emph{Standard}: 13757GNU extension 13758 13759@item @emph{Class}: 13760Subroutine, function 13761 13762@item @emph{Syntax}: 13763@multitable @columnfractions .80 13764@item @code{CALL SYSTEM(COMMAND [, STATUS])} 13765@item @code{STATUS = SYSTEM(COMMAND)} 13766@end multitable 13767 13768@item @emph{Arguments}: 13769@multitable @columnfractions .15 .70 13770@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type. 13771@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13772@end multitable 13773 13774@item @emph{See also}: 13775@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard 13776and should considered in new code for future portability. 13777@end table 13778 13779 13780 13781@node SYSTEM_CLOCK 13782@section @code{SYSTEM_CLOCK} --- Time function 13783@fnindex SYSTEM_CLOCK 13784@cindex time, clock ticks 13785@cindex clock ticks 13786 13787@table @asis 13788@item @emph{Description}: 13789Determines the @var{COUNT} of a processor clock since an unspecified 13790time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines 13791the number of clock ticks per second. If the platform supports a 13792monotonic clock, that clock is used and can, depending on the platform 13793clock implementation, provide up to nanosecond resolution. If a 13794monotonic clock is not available, the implementation falls back to a 13795realtime clock. 13796 13797@var{COUNT_RATE} is system dependent and can vary depending on the kind of 13798the arguments. For @var{kind=4} arguments (and smaller integer kinds), 13799@var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and 13800larger integer kinds), @var{COUNT} typically represents micro- or 13801nanoseconds depending on resolution of the underlying platform clock. 13802@var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the 13803millisecond resolution of the @var{kind=4} version implies that the 13804@var{COUNT} will wrap around in roughly 25 days. In order to avoid issues 13805with the wrap around and for more precise timing, please use the 13806@var{kind=8} version. 13807 13808If there is no clock, or querying the clock fails, @var{COUNT} is set 13809to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are 13810set to zero. 13811 13812When running on a platform using the GNU C library (glibc) version 138132.16 or older, or a derivative thereof, the high resolution monotonic 13814clock is available only when linking with the @var{rt} library. This 13815can be done explicitly by adding the @code{-lrt} flag when linking the 13816application, but is also done implicitly when using OpenMP. 13817 13818On the Windows platform, the version with @var{kind=4} arguments uses 13819the @code{GetTickCount} function, whereas the @var{kind=8} version 13820uses @code{QueryPerformanceCounter} and 13821@code{QueryPerformanceCounterFrequency}. For more information, and 13822potential caveats, please see the platform documentation. 13823 13824@item @emph{Standard}: 13825Fortran 95 and later 13826 13827@item @emph{Class}: 13828Subroutine 13829 13830@item @emph{Syntax}: 13831@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} 13832 13833@item @emph{Arguments}: 13834@multitable @columnfractions .15 .70 13835@item @var{COUNT} @tab (Optional) shall be a scalar of type 13836@code{INTEGER} with @code{INTENT(OUT)}. 13837@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type 13838@code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}. 13839@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type 13840@code{INTEGER} with @code{INTENT(OUT)}. 13841@end multitable 13842 13843@item @emph{Example}: 13844@smallexample 13845PROGRAM test_system_clock 13846 INTEGER :: count, count_rate, count_max 13847 CALL SYSTEM_CLOCK(count, count_rate, count_max) 13848 WRITE(*,*) count, count_rate, count_max 13849END PROGRAM 13850@end smallexample 13851 13852@item @emph{See also}: 13853@ref{DATE_AND_TIME}, @ref{CPU_TIME} 13854@end table 13855 13856 13857 13858@node TAN 13859@section @code{TAN} --- Tangent function 13860@fnindex TAN 13861@fnindex DTAN 13862@cindex trigonometric function, tangent 13863@cindex tangent 13864 13865@table @asis 13866@item @emph{Description}: 13867@code{TAN(X)} computes the tangent of @var{X}. 13868 13869@item @emph{Standard}: 13870Fortran 77 and later, for a complex argument Fortran 2008 or later 13871 13872@item @emph{Class}: 13873Elemental function 13874 13875@item @emph{Syntax}: 13876@code{RESULT = TAN(X)} 13877 13878@item @emph{Arguments}: 13879@multitable @columnfractions .15 .70 13880@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13881@end multitable 13882 13883@item @emph{Return value}: 13884The return value has same type and kind as @var{X}, and its value is in radians. 13885 13886@item @emph{Example}: 13887@smallexample 13888program test_tan 13889 real(8) :: x = 0.165_8 13890 x = tan(x) 13891end program test_tan 13892@end smallexample 13893 13894@item @emph{Specific names}: 13895@multitable @columnfractions .20 .20 .20 .25 13896@item Name @tab Argument @tab Return type @tab Standard 13897@item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 13898@item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 13899@end multitable 13900 13901@item @emph{See also}: 13902Inverse function: @ref{ATAN} 13903Degrees function: @ref{TAND} 13904@end table 13905 13906 13907 13908@node TAND 13909@section @code{TAND} --- Tangent function, degrees 13910@fnindex TAND 13911@fnindex DTAND 13912@cindex trigonometric function, tangent, degrees 13913@cindex tangent, degrees 13914 13915@table @asis 13916@item @emph{Description}: 13917@code{TAND(X)} computes the tangent of @var{X} in degrees. 13918 13919This function is for compatibility only and should be avoided in favor of 13920standard constructs wherever possible. 13921 13922@item @emph{Standard}: 13923GNU Extension, enabled with @option{-fdec-math}. 13924 13925@item @emph{Class}: 13926Elemental function 13927 13928@item @emph{Syntax}: 13929@code{RESULT = TAND(X)} 13930 13931@item @emph{Arguments}: 13932@multitable @columnfractions .15 .70 13933@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13934@end multitable 13935 13936@item @emph{Return value}: 13937The return value has same type and kind as @var{X}, and its value is in degrees. 13938 13939@item @emph{Example}: 13940@smallexample 13941program test_tand 13942 real(8) :: x = 0.165_8 13943 x = tand(x) 13944end program test_tand 13945@end smallexample 13946 13947@item @emph{Specific names}: 13948@multitable @columnfractions .20 .20 .20 .25 13949@item Name @tab Argument @tab Return type @tab Standard 13950@item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 13951@item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 13952@end multitable 13953 13954@item @emph{See also}: 13955Inverse function: @ref{ATAND} 13956Radians function: @ref{TAN} 13957@end table 13958 13959 13960 13961@node TANH 13962@section @code{TANH} --- Hyperbolic tangent function 13963@fnindex TANH 13964@fnindex DTANH 13965@cindex hyperbolic tangent 13966@cindex hyperbolic function, tangent 13967@cindex tangent, hyperbolic 13968 13969@table @asis 13970@item @emph{Description}: 13971@code{TANH(X)} computes the hyperbolic tangent of @var{X}. 13972 13973@item @emph{Standard}: 13974Fortran 77 and later, for a complex argument Fortran 2008 or later 13975 13976@item @emph{Class}: 13977Elemental function 13978 13979@item @emph{Syntax}: 13980@code{X = TANH(X)} 13981 13982@item @emph{Arguments}: 13983@multitable @columnfractions .15 .70 13984@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13985@end multitable 13986 13987@item @emph{Return value}: 13988The return value has same type and kind as @var{X}. If @var{X} is 13989complex, the imaginary part of the result is in radians. If @var{X} 13990is @code{REAL}, the return value lies in the range 13991@math{ - 1 \leq tanh(x) \leq 1 }. 13992 13993@item @emph{Example}: 13994@smallexample 13995program test_tanh 13996 real(8) :: x = 2.1_8 13997 x = tanh(x) 13998end program test_tanh 13999@end smallexample 14000 14001@item @emph{Specific names}: 14002@multitable @columnfractions .20 .20 .20 .25 14003@item Name @tab Argument @tab Return type @tab Standard 14004@item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 14005@item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 14006@end multitable 14007 14008@item @emph{See also}: 14009@ref{ATANH} 14010@end table 14011 14012 14013 14014@node THIS_IMAGE 14015@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image 14016@fnindex THIS_IMAGE 14017@cindex coarray, @code{THIS_IMAGE} 14018@cindex images, index of this image 14019 14020@table @asis 14021@item @emph{Description}: 14022Returns the cosubscript for this image. 14023 14024@item @emph{Standard}: 14025Fortran 2008 and later. With @var{DISTANCE} argument, 14026Technical Specification (TS) 18508 or later 14027 14028@item @emph{Class}: 14029Transformational function 14030 14031@item @emph{Syntax}: 14032@multitable @columnfractions .80 14033@item @code{RESULT = THIS_IMAGE()} 14034@item @code{RESULT = THIS_IMAGE(DISTANCE)} 14035@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} 14036@end multitable 14037 14038@item @emph{Arguments}: 14039@multitable @columnfractions .15 .70 14040@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 14041(not permitted together with @var{COARRAY}). 14042@item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} 14043present, required). 14044@item @var{DIM} @tab default integer scalar (optional). If present, 14045@var{DIM} shall be between one and the corank of @var{COARRAY}. 14046@end multitable 14047 14048 14049@item @emph{Return value}: 14050Default integer. If @var{COARRAY} is not present, it is scalar; if 14051@var{DISTANCE} is not present or has value 0, its value is the image index on 14052the invoking image for the current team, for values smaller or equal 14053distance to the initial team, it returns the image index on the ancestor team 14054which has a distance of @var{DISTANCE} from the invoking team. If 14055@var{DISTANCE} is larger than the distance to the initial team, the image 14056index of the initial team is returned. Otherwise when the @var{COARRAY} is 14057present, if @var{DIM} is not present, a rank-1 array with corank elements is 14058returned, containing the cosubscripts for @var{COARRAY} specifying the invoking 14059image. If @var{DIM} is present, a scalar is returned, with the value of 14060the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}. 14061 14062@item @emph{Example}: 14063@smallexample 14064INTEGER :: value[*] 14065INTEGER :: i 14066value = THIS_IMAGE() 14067SYNC ALL 14068IF (THIS_IMAGE() == 1) THEN 14069 DO i = 1, NUM_IMAGES() 14070 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 14071 END DO 14072END IF 14073 14074! Check whether the current image is the initial image 14075IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) 14076 error stop "something is rotten here" 14077@end smallexample 14078 14079@item @emph{See also}: 14080@ref{NUM_IMAGES}, @ref{IMAGE_INDEX} 14081@end table 14082 14083 14084 14085@node TIME 14086@section @code{TIME} --- Time function 14087@fnindex TIME 14088@cindex time, current 14089@cindex current time 14090 14091@table @asis 14092@item @emph{Description}: 14093Returns the current time encoded as an integer (in the manner of the 14094function @code{time(3)} in the C standard library). This value is 14095suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 14096 14097This intrinsic is not fully portable, such as to systems with 32-bit 14098@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 14099the values returned by this intrinsic might be, or become, negative, or 14100numerically less than previous values, during a single run of the 14101compiled program. 14102 14103See @ref{TIME8}, for information on a similar intrinsic that might be 14104portable to more GNU Fortran implementations, though to fewer Fortran 14105compilers. 14106 14107@item @emph{Standard}: 14108GNU extension 14109 14110@item @emph{Class}: 14111Function 14112 14113@item @emph{Syntax}: 14114@code{RESULT = TIME()} 14115 14116@item @emph{Return value}: 14117The return value is a scalar of type @code{INTEGER(4)}. 14118 14119@item @emph{See also}: 14120@ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} 14121 14122@end table 14123 14124 14125 14126@node TIME8 14127@section @code{TIME8} --- Time function (64-bit) 14128@fnindex TIME8 14129@cindex time, current 14130@cindex current time 14131 14132@table @asis 14133@item @emph{Description}: 14134Returns the current time encoded as an integer (in the manner of the 14135function @code{time(3)} in the C standard library). This value is 14136suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}. 14137 14138@emph{Warning:} this intrinsic does not increase the range of the timing 14139values over that returned by @code{time(3)}. On a system with a 32-bit 14140@code{time(3)}, @code{TIME8} will return a 32-bit value, even though 14141it is converted to a 64-bit @code{INTEGER(8)} value. That means 14142overflows of the 32-bit value can still occur. Therefore, the values 14143returned by this intrinsic might be or become negative or numerically 14144less than previous values during a single run of the compiled program. 14145 14146@item @emph{Standard}: 14147GNU extension 14148 14149@item @emph{Class}: 14150Function 14151 14152@item @emph{Syntax}: 14153@code{RESULT = TIME8()} 14154 14155@item @emph{Return value}: 14156The return value is a scalar of type @code{INTEGER(8)}. 14157 14158@item @emph{See also}: 14159@ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME} 14160 14161@end table 14162 14163 14164 14165@node TINY 14166@section @code{TINY} --- Smallest positive number of a real kind 14167@fnindex TINY 14168@cindex limits, smallest number 14169@cindex model representation, smallest number 14170 14171@table @asis 14172@item @emph{Description}: 14173@code{TINY(X)} returns the smallest positive (non zero) number 14174in the model of the type of @code{X}. 14175 14176@item @emph{Standard}: 14177Fortran 95 and later 14178 14179@item @emph{Class}: 14180Inquiry function 14181 14182@item @emph{Syntax}: 14183@code{RESULT = TINY(X)} 14184 14185@item @emph{Arguments}: 14186@multitable @columnfractions .15 .70 14187@item @var{X} @tab Shall be of type @code{REAL}. 14188@end multitable 14189 14190@item @emph{Return value}: 14191The return value is of the same type and kind as @var{X} 14192 14193@item @emph{Example}: 14194See @code{HUGE} for an example. 14195@end table 14196 14197 14198 14199@node TRAILZ 14200@section @code{TRAILZ} --- Number of trailing zero bits of an integer 14201@fnindex TRAILZ 14202@cindex zero bits 14203 14204@table @asis 14205@item @emph{Description}: 14206@code{TRAILZ} returns the number of trailing zero bits of an integer. 14207 14208@item @emph{Standard}: 14209Fortran 2008 and later 14210 14211@item @emph{Class}: 14212Elemental function 14213 14214@item @emph{Syntax}: 14215@code{RESULT = TRAILZ(I)} 14216 14217@item @emph{Arguments}: 14218@multitable @columnfractions .15 .70 14219@item @var{I} @tab Shall be of type @code{INTEGER}. 14220@end multitable 14221 14222@item @emph{Return value}: 14223The type of the return value is the default @code{INTEGER}. 14224If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 14225 14226@item @emph{Example}: 14227@smallexample 14228PROGRAM test_trailz 14229 WRITE (*,*) TRAILZ(8) ! prints 3 14230END PROGRAM 14231@end smallexample 14232 14233@item @emph{See also}: 14234@ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT} 14235@end table 14236 14237 14238 14239@node TRANSFER 14240@section @code{TRANSFER} --- Transfer bit patterns 14241@fnindex TRANSFER 14242@cindex bits, move 14243@cindex type cast 14244 14245@table @asis 14246@item @emph{Description}: 14247Interprets the bitwise representation of @var{SOURCE} in memory as if it 14248is the representation of a variable or array of the same type and type 14249parameters as @var{MOLD}. 14250 14251This is approximately equivalent to the C concept of @emph{casting} one 14252type to another. 14253 14254@item @emph{Standard}: 14255Fortran 95 and later 14256 14257@item @emph{Class}: 14258Transformational function 14259 14260@item @emph{Syntax}: 14261@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])} 14262 14263@item @emph{Arguments}: 14264@multitable @columnfractions .15 .70 14265@item @var{SOURCE} @tab Shall be a scalar or an array of any type. 14266@item @var{MOLD} @tab Shall be a scalar or an array of any type. 14267@item @var{SIZE} @tab (Optional) shall be a scalar of type 14268@code{INTEGER}. 14269@end multitable 14270 14271@item @emph{Return value}: 14272The result has the same type as @var{MOLD}, with the bit level 14273representation of @var{SOURCE}. If @var{SIZE} is present, the result is 14274a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent 14275but @var{MOLD} is an array (of any size or shape), the result is a one- 14276dimensional array of the minimum length needed to contain the entirety 14277of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent 14278and @var{MOLD} is a scalar, the result is a scalar. 14279 14280If the bitwise representation of the result is longer than that of 14281@var{SOURCE}, then the leading bits of the result correspond to those of 14282@var{SOURCE} and any trailing bits are filled arbitrarily. 14283 14284When the resulting bit representation does not correspond to a valid 14285representation of a variable of the same type as @var{MOLD}, the results 14286are undefined, and subsequent operations on the result cannot be 14287guaranteed to produce sensible behavior. For example, it is possible to 14288create @code{LOGICAL} variables for which @code{@var{VAR}} and 14289@code{.NOT.@var{VAR}} both appear to be true. 14290 14291@item @emph{Example}: 14292@smallexample 14293PROGRAM test_transfer 14294 integer :: x = 2143289344 14295 print *, transfer(x, 1.0) ! prints "NaN" on i686 14296END PROGRAM 14297@end smallexample 14298@end table 14299 14300 14301 14302@node TRANSPOSE 14303@section @code{TRANSPOSE} --- Transpose an array of rank two 14304@fnindex TRANSPOSE 14305@cindex array, transpose 14306@cindex matrix, transpose 14307@cindex transpose 14308 14309@table @asis 14310@item @emph{Description}: 14311Transpose an array of rank two. Element (i, j) of the result has the value 14312@code{MATRIX(j, i)}, for all i, j. 14313 14314@item @emph{Standard}: 14315Fortran 95 and later 14316 14317@item @emph{Class}: 14318Transformational function 14319 14320@item @emph{Syntax}: 14321@code{RESULT = TRANSPOSE(MATRIX)} 14322 14323@item @emph{Arguments}: 14324@multitable @columnfractions .15 .70 14325@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two. 14326@end multitable 14327 14328@item @emph{Return value}: 14329The result has the same type as @var{MATRIX}, and has shape 14330@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}. 14331@end table 14332 14333 14334 14335@node TRIM 14336@section @code{TRIM} --- Remove trailing blank characters of a string 14337@fnindex TRIM 14338@cindex string, remove trailing whitespace 14339 14340@table @asis 14341@item @emph{Description}: 14342Removes trailing blank characters of a string. 14343 14344@item @emph{Standard}: 14345Fortran 95 and later 14346 14347@item @emph{Class}: 14348Transformational function 14349 14350@item @emph{Syntax}: 14351@code{RESULT = TRIM(STRING)} 14352 14353@item @emph{Arguments}: 14354@multitable @columnfractions .15 .70 14355@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}. 14356@end multitable 14357 14358@item @emph{Return value}: 14359A scalar of type @code{CHARACTER} which length is that of @var{STRING} 14360less the number of trailing blanks. 14361 14362@item @emph{Example}: 14363@smallexample 14364PROGRAM test_trim 14365 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " 14366 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks 14367END PROGRAM 14368@end smallexample 14369 14370@item @emph{See also}: 14371@ref{ADJUSTL}, @ref{ADJUSTR} 14372@end table 14373 14374 14375 14376@node TTYNAM 14377@section @code{TTYNAM} --- Get the name of a terminal device. 14378@fnindex TTYNAM 14379@cindex system, terminal 14380 14381@table @asis 14382@item @emph{Description}: 14383Get the name of a terminal device. For more information, 14384see @code{ttyname(3)}. 14385 14386This intrinsic is provided in both subroutine and function forms; 14387however, only one form can be used in any given program unit. 14388 14389@item @emph{Standard}: 14390GNU extension 14391 14392@item @emph{Class}: 14393Subroutine, function 14394 14395@item @emph{Syntax}: 14396@multitable @columnfractions .80 14397@item @code{CALL TTYNAM(UNIT, NAME)} 14398@item @code{NAME = TTYNAM(UNIT)} 14399@end multitable 14400 14401@item @emph{Arguments}: 14402@multitable @columnfractions .15 .70 14403@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 14404@item @var{NAME} @tab Shall be of type @code{CHARACTER}. 14405@end multitable 14406 14407@item @emph{Example}: 14408@smallexample 14409PROGRAM test_ttynam 14410 INTEGER :: unit 14411 DO unit = 1, 10 14412 IF (isatty(unit=unit)) write(*,*) ttynam(unit) 14413 END DO 14414END PROGRAM 14415@end smallexample 14416 14417@item @emph{See also}: 14418@ref{ISATTY} 14419@end table 14420 14421 14422 14423@node UBOUND 14424@section @code{UBOUND} --- Upper dimension bounds of an array 14425@fnindex UBOUND 14426@cindex array, upper bound 14427 14428@table @asis 14429@item @emph{Description}: 14430Returns the upper bounds of an array, or a single upper bound 14431along the @var{DIM} dimension. 14432@item @emph{Standard}: 14433Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 14434 14435@item @emph{Class}: 14436Inquiry function 14437 14438@item @emph{Syntax}: 14439@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])} 14440 14441@item @emph{Arguments}: 14442@multitable @columnfractions .15 .70 14443@item @var{ARRAY} @tab Shall be an array, of any type. 14444@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14445@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization 14446expression indicating the kind parameter of the result. 14447@end multitable 14448 14449@item @emph{Return value}: 14450The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14451@var{KIND} is absent, the return value is of default integer kind. 14452If @var{DIM} is absent, the result is an array of the upper bounds of 14453@var{ARRAY}. If @var{DIM} is present, the result is a scalar 14454corresponding to the upper bound of the array along that dimension. If 14455@var{ARRAY} is an expression rather than a whole array or array 14456structure component, or if it has a zero extent along the relevant 14457dimension, the upper bound is taken to be the number of elements along 14458the relevant dimension. 14459 14460@item @emph{See also}: 14461@ref{LBOUND}, @ref{LCOBOUND} 14462@end table 14463 14464 14465 14466@node UCOBOUND 14467@section @code{UCOBOUND} --- Upper codimension bounds of an array 14468@fnindex UCOBOUND 14469@cindex coarray, upper bound 14470 14471@table @asis 14472@item @emph{Description}: 14473Returns the upper cobounds of a coarray, or a single upper cobound 14474along the @var{DIM} codimension. 14475@item @emph{Standard}: 14476Fortran 2008 and later 14477 14478@item @emph{Class}: 14479Inquiry function 14480 14481@item @emph{Syntax}: 14482@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])} 14483 14484@item @emph{Arguments}: 14485@multitable @columnfractions .15 .70 14486@item @var{ARRAY} @tab Shall be an coarray, of any type. 14487@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 14488@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14489expression indicating the kind parameter of the result. 14490@end multitable 14491 14492@item @emph{Return value}: 14493The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14494@var{KIND} is absent, the return value is of default integer kind. 14495If @var{DIM} is absent, the result is an array of the lower cobounds of 14496@var{COARRAY}. If @var{DIM} is present, the result is a scalar 14497corresponding to the lower cobound of the array along that codimension. 14498 14499@item @emph{See also}: 14500@ref{LCOBOUND}, @ref{LBOUND} 14501@end table 14502 14503 14504 14505@node UMASK 14506@section @code{UMASK} --- Set the file creation mask 14507@fnindex UMASK 14508@cindex file system, file creation mask 14509 14510@table @asis 14511@item @emph{Description}: 14512Sets the file creation mask to @var{MASK}. If called as a function, it 14513returns the old value. If called as a subroutine and argument @var{OLD} 14514if it is supplied, it is set to the old value. See @code{umask(2)}. 14515 14516@item @emph{Standard}: 14517GNU extension 14518 14519@item @emph{Class}: 14520Subroutine, function 14521 14522@item @emph{Syntax}: 14523@multitable @columnfractions .80 14524@item @code{CALL UMASK(MASK [, OLD])} 14525@item @code{OLD = UMASK(MASK)} 14526@end multitable 14527 14528@item @emph{Arguments}: 14529@multitable @columnfractions .15 .70 14530@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}. 14531@item @var{OLD} @tab (Optional) Shall be a scalar of type 14532@code{INTEGER}. 14533@end multitable 14534 14535@end table 14536 14537 14538 14539@node UNLINK 14540@section @code{UNLINK} --- Remove a file from the file system 14541@fnindex UNLINK 14542@cindex file system, remove file 14543 14544@table @asis 14545@item @emph{Description}: 14546Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be 14547used to mark the end of the name in @var{PATH}; otherwise, trailing 14548blanks in the file name are ignored. If the @var{STATUS} argument is 14549supplied, it contains 0 on success or a nonzero error code upon return; 14550see @code{unlink(2)}. 14551 14552This intrinsic is provided in both subroutine and function forms; 14553however, only one form can be used in any given program unit. 14554 14555@item @emph{Standard}: 14556GNU extension 14557 14558@item @emph{Class}: 14559Subroutine, function 14560 14561@item @emph{Syntax}: 14562@multitable @columnfractions .80 14563@item @code{CALL UNLINK(PATH [, STATUS])} 14564@item @code{STATUS = UNLINK(PATH)} 14565@end multitable 14566 14567@item @emph{Arguments}: 14568@multitable @columnfractions .15 .70 14569@item @var{PATH} @tab Shall be of default @code{CHARACTER} type. 14570@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 14571@end multitable 14572 14573@item @emph{See also}: 14574@ref{LINK}, @ref{SYMLNK} 14575@end table 14576 14577 14578 14579@node UNPACK 14580@section @code{UNPACK} --- Unpack an array of rank one into an array 14581@fnindex UNPACK 14582@cindex array, unpacking 14583@cindex array, increase dimension 14584@cindex array, scatter elements 14585 14586@table @asis 14587@item @emph{Description}: 14588Store the elements of @var{VECTOR} in an array of higher rank. 14589 14590@item @emph{Standard}: 14591Fortran 95 and later 14592 14593@item @emph{Class}: 14594Transformational function 14595 14596@item @emph{Syntax}: 14597@code{RESULT = UNPACK(VECTOR, MASK, FIELD)} 14598 14599@item @emph{Arguments}: 14600@multitable @columnfractions .15 .70 14601@item @var{VECTOR} @tab Shall be an array of any type and rank one. It 14602shall have at least as many elements as @var{MASK} has @code{TRUE} values. 14603@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}. 14604@item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have 14605the same shape as @var{MASK}. 14606@end multitable 14607 14608@item @emph{Return value}: 14609The resulting array corresponds to @var{FIELD} with @code{TRUE} elements 14610of @var{MASK} replaced by values from @var{VECTOR} in array element order. 14611 14612@item @emph{Example}: 14613@smallexample 14614PROGRAM test_unpack 14615 integer :: vector(2) = (/1,1/) 14616 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /) 14617 integer :: field(2,2) = 0, unity(2,2) 14618 14619 ! result: unity matrix 14620 unity = unpack(vector, reshape(mask, (/2,2/)), field) 14621END PROGRAM 14622@end smallexample 14623 14624@item @emph{See also}: 14625@ref{PACK}, @ref{SPREAD} 14626@end table 14627 14628 14629 14630@node VERIFY 14631@section @code{VERIFY} --- Scan a string for characters not a given set 14632@fnindex VERIFY 14633@cindex string, find missing set 14634 14635@table @asis 14636@item @emph{Description}: 14637Verifies that all the characters in @var{STRING} belong to the set of 14638characters in @var{SET}. 14639 14640If @var{BACK} is either absent or equals @code{FALSE}, this function 14641returns the position of the leftmost character of @var{STRING} that is 14642not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost 14643position is returned. If all characters of @var{STRING} are found in 14644@var{SET}, the result is zero. 14645 14646@item @emph{Standard}: 14647Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 14648 14649@item @emph{Class}: 14650Elemental function 14651 14652@item @emph{Syntax}: 14653@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])} 14654 14655@item @emph{Arguments}: 14656@multitable @columnfractions .15 .70 14657@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 14658@item @var{SET} @tab Shall be of type @code{CHARACTER}. 14659@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 14660@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 14661expression indicating the kind parameter of the result. 14662@end multitable 14663 14664@item @emph{Return value}: 14665The return value is of type @code{INTEGER} and of kind @var{KIND}. If 14666@var{KIND} is absent, the return value is of default integer kind. 14667 14668@item @emph{Example}: 14669@smallexample 14670PROGRAM test_verify 14671 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F' 14672 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R' 14673 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F' 14674 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N' 14675 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none 14676END PROGRAM 14677@end smallexample 14678 14679@item @emph{See also}: 14680@ref{SCAN}, @ref{INDEX intrinsic} 14681@end table 14682 14683 14684 14685@node XOR 14686@section @code{XOR} --- Bitwise logical exclusive OR 14687@fnindex XOR 14688@cindex bitwise logical exclusive or 14689@cindex logical exclusive or, bitwise 14690 14691@table @asis 14692@item @emph{Description}: 14693Bitwise logical exclusive or. 14694 14695This intrinsic routine is provided for backwards compatibility with 14696GNU Fortran 77. For integer arguments, programmers should consider 14697the use of the @ref{IEOR} intrinsic and for logical arguments the 14698@code{.NEQV.} operator, which are both defined by the Fortran standard. 14699 14700@item @emph{Standard}: 14701GNU extension 14702 14703@item @emph{Class}: 14704Function 14705 14706@item @emph{Syntax}: 14707@code{RESULT = XOR(I, J)} 14708 14709@item @emph{Arguments}: 14710@multitable @columnfractions .15 .70 14711@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 14712type or a scalar @code{LOGICAL} type or a boz-literal-constant. 14713@item @var{J} @tab The type shall be the same as the type of @var{I} or 14714a boz-literal-constant. @var{I} and @var{J} shall not both be 14715boz-literal-constants. If either @var{I} and @var{J} is a 14716boz-literal-constant, then the other argument must be a scalar @code{INTEGER}. 14717@end multitable 14718 14719@item @emph{Return value}: 14720The return type is either a scalar @code{INTEGER} or a scalar 14721@code{LOGICAL}. If the kind type parameters differ, then the 14722smaller kind type is implicitly converted to larger kind, and the 14723return has the larger kind. A boz-literal-constant is 14724converted to an @code{INTEGER} with the kind type parameter of 14725the other argument as-if a call to @ref{INT} occurred. 14726 14727@item @emph{Example}: 14728@smallexample 14729PROGRAM test_xor 14730 LOGICAL :: T = .TRUE., F = .FALSE. 14731 INTEGER :: a, b 14732 DATA a / Z'F' /, b / Z'3' / 14733 14734 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F) 14735 WRITE (*,*) XOR(a, b) 14736END PROGRAM 14737@end smallexample 14738 14739@item @emph{See also}: 14740Fortran 95 elemental function: @ref{IEOR} 14741@end table 14742 14743 14744 14745@node Intrinsic Modules 14746@chapter Intrinsic Modules 14747@cindex intrinsic Modules 14748 14749@menu 14750* ISO_FORTRAN_ENV:: 14751* ISO_C_BINDING:: 14752* IEEE modules:: 14753* OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: 14754* OpenACC Module OPENACC:: 14755@end menu 14756 14757@node ISO_FORTRAN_ENV 14758@section @code{ISO_FORTRAN_ENV} 14759@table @asis 14760@item @emph{Standard}: 14761Fortran 2003 and later, except when otherwise noted 14762@end table 14763 14764The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer 14765named constants: 14766 14767@table @asis 14768@item @code{ATOMIC_INT_KIND}: 14769Default-kind integer constant to be used as kind parameter when defining 14770integer variables used in atomic operations. (Fortran 2008 or later.) 14771 14772@item @code{ATOMIC_LOGICAL_KIND}: 14773Default-kind integer constant to be used as kind parameter when defining 14774logical variables used in atomic operations. (Fortran 2008 or later.) 14775 14776@item @code{CHARACTER_KINDS}: 14777Default-kind integer constant array of rank one containing the supported kind 14778parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) 14779 14780@item @code{CHARACTER_STORAGE_SIZE}: 14781Size in bits of the character storage unit. 14782 14783@item @code{ERROR_UNIT}: 14784Identifies the preconnected unit used for error reporting. 14785 14786@item @code{FILE_STORAGE_SIZE}: 14787Size in bits of the file-storage unit. 14788 14789@item @code{INPUT_UNIT}: 14790Identifies the preconnected unit identified by the asterisk 14791(@code{*}) in @code{READ} statement. 14792 14793@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}: 14794Kind type parameters to specify an INTEGER type with a storage 14795size of 16, 32, and 64 bits. It is negative if a target platform 14796does not support the particular kind. (Fortran 2008 or later.) 14797 14798@item @code{INTEGER_KINDS}: 14799Default-kind integer constant array of rank one containing the supported kind 14800parameters of the @code{INTEGER} type. (Fortran 2008 or later.) 14801 14802@item @code{IOSTAT_END}: 14803The value assigned to the variable passed to the @code{IOSTAT=} specifier of 14804an input/output statement if an end-of-file condition occurred. 14805 14806@item @code{IOSTAT_EOR}: 14807The value assigned to the variable passed to the @code{IOSTAT=} specifier of 14808an input/output statement if an end-of-record condition occurred. 14809 14810@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}: 14811Scalar default-integer constant, used by @code{INQUIRE} for the 14812@code{IOSTAT=} specifier to denote an that a unit number identifies an 14813internal unit. (Fortran 2008 or later.) 14814 14815@item @code{NUMERIC_STORAGE_SIZE}: 14816The size in bits of the numeric storage unit. 14817 14818@item @code{LOGICAL_KINDS}: 14819Default-kind integer constant array of rank one containing the supported kind 14820parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) 14821 14822@item @code{OUTPUT_UNIT}: 14823Identifies the preconnected unit identified by the asterisk 14824(@code{*}) in @code{WRITE} statement. 14825 14826@item @code{REAL32}, @code{REAL64}, @code{REAL128}: 14827Kind type parameters to specify a REAL type with a storage 14828size of 32, 64, and 128 bits. It is negative if a target platform 14829does not support the particular kind. (Fortran 2008 or later.) 14830 14831@item @code{REAL_KINDS}: 14832Default-kind integer constant array of rank one containing the supported kind 14833parameters of the @code{REAL} type. (Fortran 2008 or later.) 14834 14835@item @code{STAT_LOCKED}: 14836Scalar default-integer constant used as STAT= return value by @code{LOCK} to 14837denote that the lock variable is locked by the executing image. (Fortran 2008 14838or later.) 14839 14840@item @code{STAT_LOCKED_OTHER_IMAGE}: 14841Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 14842denote that the lock variable is locked by another image. (Fortran 2008 or 14843later.) 14844 14845@item @code{STAT_STOPPED_IMAGE}: 14846Positive, scalar default-integer constant used as STAT= return value if the 14847argument in the statement requires synchronisation with an image, which has 14848initiated the termination of the execution. (Fortran 2008 or later.) 14849 14850@item @code{STAT_FAILED_IMAGE}: 14851Positive, scalar default-integer constant used as STAT= return value if the 14852argument in the statement requires communication with an image, which has 14853is in the failed state. (TS 18508 or later.) 14854 14855@item @code{STAT_UNLOCKED}: 14856Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 14857denote that the lock variable is unlocked. (Fortran 2008 or later.) 14858@end table 14859 14860The module provides the following derived type: 14861 14862@table @asis 14863@item @code{LOCK_TYPE}: 14864Derived type with private components to be use with the @code{LOCK} and 14865@code{UNLOCK} statement. A variable of its type has to be always declared 14866as coarray and may not appear in a variable-definition context. 14867(Fortran 2008 or later.) 14868@end table 14869 14870The module also provides the following intrinsic procedures: 14871@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}. 14872 14873 14874 14875@node ISO_C_BINDING 14876@section @code{ISO_C_BINDING} 14877@table @asis 14878@item @emph{Standard}: 14879Fortran 2003 and later, GNU extensions 14880@end table 14881 14882The following intrinsic procedures are provided by the module; their 14883definition can be found in the section Intrinsic Procedures of this 14884manual. 14885 14886@table @asis 14887@item @code{C_ASSOCIATED} 14888@item @code{C_F_POINTER} 14889@item @code{C_F_PROCPOINTER} 14890@item @code{C_FUNLOC} 14891@item @code{C_LOC} 14892@item @code{C_SIZEOF} 14893@end table 14894@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF, 14895@c don't really know why. 14896 14897The @code{ISO_C_BINDING} module provides the following named constants of 14898type default integer, which can be used as KIND type parameters. 14899 14900In addition to the integer named constants required by the Fortran 2003 14901standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an 14902extension named constants for the 128-bit integer types supported by the 14903C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}. 14904Furthermore, if @code{__float128} is supported in C, the named constants 14905@code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined. 14906 14907@multitable @columnfractions .15 .35 .35 .35 14908@item Fortran Type @tab Named constant @tab C type @tab Extension 14909@item @code{INTEGER}@tab @code{C_INT} @tab @code{int} 14910@item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int} 14911@item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int} 14912@item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int} 14913@item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char} 14914@item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t} 14915@item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t} 14916@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t} 14917@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t} 14918@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t} 14919@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext. 14920@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t} 14921@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t} 14922@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t} 14923@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t} 14924@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext. 14925@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t} 14926@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t} 14927@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t} 14928@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t} 14929@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext. 14930@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t} 14931@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t} 14932@item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113 14933@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float} 14934@item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double} 14935@item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double} 14936@item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext. 14937@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex} 14938@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex} 14939@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex} 14940@item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext. 14941@item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool} 14942@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char} 14943@end multitable 14944 14945Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)} 14946are defined. 14947 14948@multitable @columnfractions .20 .45 .15 14949@item Name @tab C definition @tab Value 14950@item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'} 14951@item @code{C_ALERT} @tab alert @tab @code{'\a'} 14952@item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'} 14953@item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'} 14954@item @code{C_NEW_LINE} @tab new line @tab @code{'\n'} 14955@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'} 14956@item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'} 14957@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'} 14958@end multitable 14959 14960Moreover, the following two named constants are defined: 14961 14962@multitable @columnfractions .20 .80 14963@item Name @tab Type 14964@item @code{C_NULL_PTR} @tab @code{C_PTR} 14965@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR} 14966@end multitable 14967 14968Both are equivalent to the value @code{NULL} in C. 14969 14970 14971 14972@node IEEE modules 14973@section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 14974@table @asis 14975@item @emph{Standard}: 14976Fortran 2003 and later 14977@end table 14978 14979The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 14980intrinsic modules provide support for exceptions and IEEE arithmetic, as 14981defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard 14982(@emph{Binary floating-point arithmetic for microprocessor systems}). These 14983modules are only provided on the following supported platforms: 14984 14985@itemize @bullet 14986@item i386 and x86_64 processors 14987@item platforms which use the GNU C Library (glibc) 14988@item platforms with support for SysV/386 routines for floating point 14989interface (including Solaris and BSDs) 14990@item platforms with the AIX OS 14991@end itemize 14992 14993For full compliance with the Fortran standards, code using the 14994@code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled 14995with the following options: @code{-fno-unsafe-math-optimizations 14996-frounding-math -fsignaling-nans}. 14997 14998 14999 15000@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS 15001@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS} 15002@table @asis 15003@item @emph{Standard}: 15004OpenMP Application Program Interface v4.5 15005@end table 15006 15007 15008The OpenMP Fortran runtime library routines are provided both in 15009a form of two Fortran 90 modules, named @code{OMP_LIB} and 15010@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named 15011@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found 15012in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi 15013Processing Runtime Library} manual, 15014the named constants defined in the modules are listed 15015below. 15016 15017For details refer to the actual 15018@uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf, 15019OpenMP Application Program Interface v4.5}. 15020And for the @code{pause}-related constants to the OpenMP 5.0 specification. 15021 15022@code{OMP_LIB_KINDS} provides the following scalar default-integer 15023named constants: 15024 15025@table @asis 15026@item @code{omp_lock_kind} 15027@item @code{omp_lock_hint_kind} 15028@item @code{omp_nest_lock_kind} 15029@item @code{omp_pause_resource_kind} 15030@item @code{omp_proc_bind_kind} 15031@item @code{omp_sched_kind} 15032@end table 15033 15034@code{OMP_LIB} provides the scalar default-integer 15035named constant @code{openmp_version} with a value of the form 15036@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 15037of the OpenMP version; for OpenMP v4.5 the value is @code{201511}. 15038 15039The following scalar integer named constants of the 15040kind @code{omp_sched_kind}: 15041 15042@table @asis 15043@item @code{omp_sched_static} 15044@item @code{omp_sched_dynamic} 15045@item @code{omp_sched_guided} 15046@item @code{omp_sched_auto} 15047@end table 15048 15049And the following scalar integer named constants of the 15050kind @code{omp_proc_bind_kind}: 15051 15052@table @asis 15053@item @code{omp_proc_bind_false} 15054@item @code{omp_proc_bind_true} 15055@item @code{omp_proc_bind_master} 15056@item @code{omp_proc_bind_close} 15057@item @code{omp_proc_bind_spread} 15058@end table 15059 15060The following scalar integer named constants are of the 15061kind @code{omp_lock_hint_kind}: 15062 15063@table @asis 15064@item @code{omp_lock_hint_none} 15065@item @code{omp_lock_hint_uncontended} 15066@item @code{omp_lock_hint_contended} 15067@item @code{omp_lock_hint_nonspeculative} 15068@item @code{omp_lock_hint_speculative} 15069@end table 15070 15071And the following two scalar integer named constants are of the 15072kind @code{omp_pause_resource_kind}: 15073 15074@table @asis 15075@item @code{omp_pause_soft} 15076@item @code{omp_pause_hard} 15077@end table 15078 15079 15080@node OpenACC Module OPENACC 15081@section OpenACC Module @code{OPENACC} 15082@table @asis 15083@item @emph{Standard}: 15084OpenACC Application Programming Interface v2.0 15085@end table 15086 15087 15088The OpenACC Fortran runtime library routines are provided both in a 15089form of a Fortran 90 module, named @code{OPENACC}, and in form of a 15090Fortran @code{include} file named @file{openacc_lib.h}. The 15091procedures provided by @code{OPENACC} can be found in the 15092@ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing 15093Runtime Library} manual, the named constants defined in the modules 15094are listed below. 15095 15096For details refer to the actual 15097@uref{http://www.openacc.org/, 15098OpenACC Application Programming Interface v2.0}. 15099 15100@code{OPENACC} provides the scalar default-integer 15101named constant @code{openacc_version} with a value of the form 15102@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 15103of the OpenACC version; for OpenACC v2.0 the value is @code{201306}. 15104