1@ignore 2Copyright (C) 2005-2015 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\acos{\mathop{\rm acos}\nolimits} 27\gdef\asin{\mathop{\rm asin}\nolimits} 28\gdef\atan{\mathop{\rm atan}\nolimits} 29\gdef\acosh{\mathop{\rm acosh}\nolimits} 30\gdef\asinh{\mathop{\rm asinh}\nolimits} 31\gdef\atanh{\mathop{\rm atanh}\nolimits} 32@end tex 33 34 35@node Intrinsic Procedures 36@chapter Intrinsic Procedures 37@cindex intrinsic procedures 38 39@menu 40* Introduction: Introduction to Intrinsics 41* @code{ABORT}: ABORT, Abort the program 42* @code{ABS}: ABS, Absolute value 43* @code{ACCESS}: ACCESS, Checks file access modes 44* @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence 45* @code{ACOS}: ACOS, Arccosine function 46* @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function 47* @code{ADJUSTL}: ADJUSTL, Left adjust a string 48* @code{ADJUSTR}: ADJUSTR, Right adjust a string 49* @code{AIMAG}: AIMAG, Imaginary part of complex number 50* @code{AINT}: AINT, Truncate to a whole number 51* @code{ALARM}: ALARM, Set an alarm clock 52* @code{ALL}: ALL, Determine if all values are true 53* @code{ALLOCATED}: ALLOCATED, Status of allocatable entity 54* @code{AND}: AND, Bitwise logical AND 55* @code{ANINT}: ANINT, Nearest whole number 56* @code{ANY}: ANY, Determine if any values are true 57* @code{ASIN}: ASIN, Arcsine function 58* @code{ASINH}: ASINH, Inverse hyperbolic sine function 59* @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair 60* @code{ATAN}: ATAN, Arctangent function 61* @code{ATAN2}: ATAN2, Arctangent function 62* @code{ATANH}: ATANH, Inverse hyperbolic tangent function 63* @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation 64* @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation 65* @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap 66* @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically 67* @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch 68* @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch 69* @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch 70* @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch 71* @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation 72* @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically 73* @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation 74* @code{BACKTRACE}: BACKTRACE, Show a backtrace 75* @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0 76* @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1 77* @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind 78* @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0 79* @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1 80* @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind 81* @code{BGE}: BGE, Bitwise greater than or equal to 82* @code{BGT}: BGT, Bitwise greater than 83* @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function 84* @code{BLE}: BLE, Bitwise less than or equal to 85* @code{BLT}: BLT, Bitwise less than 86* @code{BTEST}: BTEST, Bit test function 87* @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer 88* @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer 89* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer 90* @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure 91* @code{C_LOC}: C_LOC, Obtain the C address of an object 92* @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression 93* @code{CEILING}: CEILING, Integer ceiling function 94* @code{CHAR}: CHAR, Integer-to-character conversion function 95* @code{CHDIR}: CHDIR, Change working directory 96* @code{CHMOD}: CHMOD, Change access permissions of files 97* @code{CMPLX}: CMPLX, Complex conversion function 98* @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images 99* @code{CO_MAX}: CO_MAX, Maximal value on the current set of images 100* @code{CO_MIN}: CO_MIN, Minimal value on the current set of images 101* @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images 102* @code{CO_SUM}: CO_SUM, Sum of values on the current set of images 103* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments 104* @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler 105* @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string 106* @code{COMPLEX}: COMPLEX, Complex conversion function 107* @code{CONJG}: CONJG, Complex conjugate function 108* @code{COS}: COS, Cosine function 109* @code{COSH}: COSH, Hyperbolic cosine function 110* @code{COUNT}: COUNT, Count occurrences of TRUE in an array 111* @code{CPU_TIME}: CPU_TIME, CPU time subroutine 112* @code{CSHIFT}: CSHIFT, Circular shift elements of an array 113* @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string 114* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine 115* @code{DBLE}: DBLE, Double precision conversion function 116* @code{DCMPLX}: DCMPLX, Double complex conversion function 117* @code{DIGITS}: DIGITS, Significant digits function 118* @code{DIM}: DIM, Positive difference 119* @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function 120* @code{DPROD}: DPROD, Double product function 121* @code{DREAL}: DREAL, Double real part function 122* @code{DSHIFTL}: DSHIFTL, Combined left shift 123* @code{DSHIFTR}: DSHIFTR, Combined right shift 124* @code{DTIME}: DTIME, Execution time subroutine (or function) 125* @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array 126* @code{EPSILON}: EPSILON, Epsilon function 127* @code{ERF}: ERF, Error function 128* @code{ERFC}: ERFC, Complementary error function 129* @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function 130* @code{ETIME}: ETIME, Execution time subroutine (or function) 131* @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command 132* @code{EXIT}: EXIT, Exit the program with status. 133* @code{EXP}: EXP, Exponential function 134* @code{EXPONENT}: EXPONENT, Exponent function 135* @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension 136* @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string 137* @code{FGET}: FGET, Read a single character in stream mode from stdin 138* @code{FGETC}: FGETC, Read a single character in stream mode 139* @code{FLOOR}: FLOOR, Integer floor function 140* @code{FLUSH}: FLUSH, Flush I/O unit(s) 141* @code{FNUM}: FNUM, File number function 142* @code{FPUT}: FPUT, Write a single character in stream mode to stdout 143* @code{FPUTC}: FPUTC, Write a single character in stream mode 144* @code{FRACTION}: FRACTION, Fractional part of the model representation 145* @code{FREE}: FREE, Memory de-allocation subroutine 146* @code{FSEEK}: FSEEK, Low level file positioning subroutine 147* @code{FSTAT}: FSTAT, Get file status 148* @code{FTELL}: FTELL, Current stream position 149* @code{GAMMA}: GAMMA, Gamma function 150* @code{GERROR}: GERROR, Get last system error message 151* @code{GETARG}: GETARG, Get command line arguments 152* @code{GET_COMMAND}: GET_COMMAND, Get the entire command line 153* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments 154* @code{GETCWD}: GETCWD, Get current working directory 155* @code{GETENV}: GETENV, Get an environmental variable 156* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable 157* @code{GETGID}: GETGID, Group ID function 158* @code{GETLOG}: GETLOG, Get login name 159* @code{GETPID}: GETPID, Process ID function 160* @code{GETUID}: GETUID, User ID function 161* @code{GMTIME}: GMTIME, Convert time to GMT info 162* @code{HOSTNM}: HOSTNM, Get system host name 163* @code{HUGE}: HUGE, Largest number of a kind 164* @code{HYPOT}: HYPOT, Euclidean distance function 165* @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence 166* @code{IALL}: IALL, Bitwise AND of array elements 167* @code{IAND}: IAND, Bitwise logical and 168* @code{IANY}: IANY, Bitwise OR of array elements 169* @code{IARGC}: IARGC, Get the number of command line arguments 170* @code{IBCLR}: IBCLR, Clear bit 171* @code{IBITS}: IBITS, Bit extraction 172* @code{IBSET}: IBSET, Set bit 173* @code{ICHAR}: ICHAR, Character-to-integer conversion function 174* @code{IDATE}: IDATE, Current local time (day/month/year) 175* @code{IEOR}: IEOR, Bitwise logical exclusive or 176* @code{IERRNO}: IERRNO, Function to get the last system error number 177* @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion 178* @code{INDEX}: INDEX intrinsic, Position of a substring within a string 179* @code{INT}: INT, Convert to integer type 180* @code{INT2}: INT2, Convert to 16-bit integer type 181* @code{INT8}: INT8, Convert to 64-bit integer type 182* @code{IOR}: IOR, Bitwise logical or 183* @code{IPARITY}: IPARITY, Bitwise XOR of array elements 184* @code{IRAND}: IRAND, Integer pseudo-random number 185* @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value 186* @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value 187* @code{ISATTY}: ISATTY, Whether a unit is a terminal device 188* @code{ISHFT}: ISHFT, Shift bits 189* @code{ISHFTC}: ISHFTC, Shift bits circularly 190* @code{ISNAN}: ISNAN, Tests for a NaN 191* @code{ITIME}: ITIME, Current local time (hour/minutes/seconds) 192* @code{KILL}: KILL, Send a signal to a process 193* @code{KIND}: KIND, Kind of an entity 194* @code{LBOUND}: LBOUND, Lower dimension bounds of an array 195* @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array 196* @code{LEADZ}: LEADZ, Number of leading zero bits of an integer 197* @code{LEN}: LEN, Length of a character entity 198* @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters 199* @code{LGE}: LGE, Lexical greater than or equal 200* @code{LGT}: LGT, Lexical greater than 201* @code{LINK}: LINK, Create a hard link 202* @code{LLE}: LLE, Lexical less than or equal 203* @code{LLT}: LLT, Lexical less than 204* @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string 205* @code{LOC}: LOC, Returns the address of a variable 206* @code{LOG}: LOG, Logarithm function 207* @code{LOG10}: LOG10, Base 10 logarithm function 208* @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function 209* @code{LOGICAL}: LOGICAL, Convert to logical type 210* @code{LONG}: LONG, Convert to integer type 211* @code{LSHIFT}: LSHIFT, Left shift bits 212* @code{LSTAT}: LSTAT, Get file status 213* @code{LTIME}: LTIME, Convert time to local time info 214* @code{MALLOC}: MALLOC, Dynamic memory allocation function 215* @code{MASKL}: MASKL, Left justified mask 216* @code{MASKR}: MASKR, Right justified mask 217* @code{MATMUL}: MATMUL, matrix multiplication 218* @code{MAX}: MAX, Maximum value of an argument list 219* @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind 220* @code{MAXLOC}: MAXLOC, Location of the maximum value within an array 221* @code{MAXVAL}: MAXVAL, Maximum value of an array 222* @code{MCLOCK}: MCLOCK, Time function 223* @code{MCLOCK8}: MCLOCK8, Time function (64-bit) 224* @code{MERGE}: MERGE, Merge arrays 225* @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask 226* @code{MIN}: MIN, Minimum value of an argument list 227* @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind 228* @code{MINLOC}: MINLOC, Location of the minimum value within an array 229* @code{MINVAL}: MINVAL, Minimum value of an array 230* @code{MOD}: MOD, Remainder function 231* @code{MODULO}: MODULO, Modulo function 232* @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another 233* @code{MVBITS}: MVBITS, Move bits from one integer to another 234* @code{NEAREST}: NEAREST, Nearest representable number 235* @code{NEW_LINE}: NEW_LINE, New line character 236* @code{NINT}: NINT, Nearest whole number 237* @code{NORM2}: NORM2, Euclidean vector norm 238* @code{NOT}: NOT, Logical negation 239* @code{NULL}: NULL, Function that returns an disassociated pointer 240* @code{NUM_IMAGES}: NUM_IMAGES, Number of images 241* @code{OR}: OR, Bitwise logical OR 242* @code{PACK}: PACK, Pack an array into an array of rank one 243* @code{PARITY}: PARITY, Reduction with exclusive OR 244* @code{PERROR}: PERROR, Print system error message 245* @code{POPCNT}: POPCNT, Number of bits set 246* @code{POPPAR}: POPPAR, Parity of the number of bits set 247* @code{PRECISION}: PRECISION, Decimal precision of a real kind 248* @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified 249* @code{PRODUCT}: PRODUCT, Product of array elements 250* @code{RADIX}: RADIX, Base of a data model 251* @code{RAN}: RAN, Real pseudo-random number 252* @code{RAND}: RAND, Real pseudo-random number 253* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number 254* @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence 255* @code{RANGE}: RANGE, Decimal exponent range 256* @code{RANK} : RANK, Rank of a data object 257* @code{REAL}: REAL, Convert to real type 258* @code{RENAME}: RENAME, Rename a file 259* @code{REPEAT}: REPEAT, Repeated string concatenation 260* @code{RESHAPE}: RESHAPE, Function to reshape an array 261* @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing 262* @code{RSHIFT}: RSHIFT, Right shift bits 263* @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality 264* @code{SCALE}: SCALE, Scale a real value 265* @code{SCAN}: SCAN, Scan a string for the presence of a set of characters 266* @code{SECNDS}: SECNDS, Time function 267* @code{SECOND}: SECOND, CPU time function 268* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind 269* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind 270* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind 271* @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model 272* @code{SHAPE}: SHAPE, Determine the shape of an array 273* @code{SHIFTA}: SHIFTA, Right shift with fill 274* @code{SHIFTL}: SHIFTL, Left shift 275* @code{SHIFTR}: SHIFTR, Right shift 276* @code{SIGN}: SIGN, Sign copying function 277* @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function) 278* @code{SIN}: SIN, Sine function 279* @code{SINH}: SINH, Hyperbolic sine function 280* @code{SIZE}: SIZE, Function to determine the size of an array 281* @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression 282* @code{SLEEP}: SLEEP, Sleep for the specified number of seconds 283* @code{SPACING}: SPACING, Smallest distance between two numbers of a given type 284* @code{SPREAD}: SPREAD, Add a dimension to an array 285* @code{SQRT}: SQRT, Square-root function 286* @code{SRAND}: SRAND, Reinitialize the random number generator 287* @code{STAT}: STAT, Get file status 288* @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits 289* @code{SUM}: SUM, Sum of array elements 290* @code{SYMLNK}: SYMLNK, Create a symbolic link 291* @code{SYSTEM}: SYSTEM, Execute a shell command 292* @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function 293* @code{TAN}: TAN, Tangent function 294* @code{TANH}: TANH, Hyperbolic tangent function 295* @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image 296* @code{TIME}: TIME, Time function 297* @code{TIME8}: TIME8, Time function (64-bit) 298* @code{TINY}: TINY, Smallest positive number of a real kind 299* @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer 300* @code{TRANSFER}: TRANSFER, Transfer bit patterns 301* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two 302* @code{TRIM}: TRIM, Remove trailing blank characters of a string 303* @code{TTYNAM}: TTYNAM, Get the name of a terminal device. 304* @code{UBOUND}: UBOUND, Upper dimension bounds of an array 305* @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array 306* @code{UMASK}: UMASK, Set the file creation mask 307* @code{UNLINK}: UNLINK, Remove a file from the file system 308* @code{UNPACK}: UNPACK, Unpack an array of rank one into an array 309* @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters 310* @code{XOR}: XOR, Bitwise logical exclusive or 311@end menu 312 313@node Introduction to Intrinsics 314@section Introduction to intrinsic procedures 315 316The intrinsic procedures provided by GNU Fortran include all of the 317intrinsic procedures required by the Fortran 95 standard, a set of 318intrinsic procedures for backwards compatibility with G77, and a 319selection of intrinsic procedures from the Fortran 2003 and Fortran 2008 320standards. Any conflict between a description here and a description in 321either the Fortran 95 standard, the Fortran 2003 standard or the Fortran 3222008 standard is unintentional, and the standard(s) should be considered 323authoritative. 324 325The enumeration of the @code{KIND} type parameter is processor defined in 326the Fortran 95 standard. GNU Fortran defines the default integer type and 327default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)}, 328respectively. The standard mandates that both data types shall have 329another kind, which have more precision. On typical target architectures 330supported by @command{gfortran}, this kind type parameter is @code{KIND=8}. 331Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent. 332In the description of generic intrinsic procedures, the kind type parameter 333will be specified by @code{KIND=*}, and in the description of specific 334names for an intrinsic procedure the kind type parameter will be explicitly 335given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for 336brevity the optional @code{KIND=} syntax will be omitted. 337 338Many of the intrinsic procedures take one or more optional arguments. 339This document follows the convention used in the Fortran 95 standard, 340and denotes such arguments by square brackets. 341 342GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options, 343which can be used to restrict the set of intrinsic procedures to a 344given standard. By default, @command{gfortran} sets the @option{-std=gnu} 345option, and so all intrinsic procedures described here are accepted. There 346is one caveat. For a select group of intrinsic procedures, @command{g77} 347implemented both a function and a subroutine. Both classes 348have been implemented in @command{gfortran} for backwards compatibility 349with @command{g77}. It is noted here that these functions and subroutines 350cannot be intermixed in a given subprogram. In the descriptions that follow, 351the applicable standard for each intrinsic procedure is noted. 352 353 354 355@node ABORT 356@section @code{ABORT} --- Abort the program 357@fnindex ABORT 358@cindex program termination, with core dump 359@cindex terminate program, with core dump 360@cindex core, dump 361 362@table @asis 363@item @emph{Description}: 364@code{ABORT} causes immediate termination of the program. On operating 365systems that support a core dump, @code{ABORT} will produce a core dump. 366It will also print a backtrace, unless @code{-fno-backtrace} is given. 367 368@item @emph{Standard}: 369GNU extension 370 371@item @emph{Class}: 372Subroutine 373 374@item @emph{Syntax}: 375@code{CALL ABORT} 376 377@item @emph{Return value}: 378Does not return. 379 380@item @emph{Example}: 381@smallexample 382program test_abort 383 integer :: i = 1, j = 2 384 if (i /= j) call abort 385end program test_abort 386@end smallexample 387 388@item @emph{See also}: 389@ref{EXIT}, @ref{KILL}, @ref{BACKTRACE} 390 391@end table 392 393 394 395@node ABS 396@section @code{ABS} --- Absolute value 397@fnindex ABS 398@fnindex CABS 399@fnindex DABS 400@fnindex IABS 401@fnindex ZABS 402@fnindex CDABS 403@cindex absolute value 404 405@table @asis 406@item @emph{Description}: 407@code{ABS(A)} computes the absolute value of @code{A}. 408 409@item @emph{Standard}: 410Fortran 77 and later, has overloads that are GNU extensions 411 412@item @emph{Class}: 413Elemental function 414 415@item @emph{Syntax}: 416@code{RESULT = ABS(A)} 417 418@item @emph{Arguments}: 419@multitable @columnfractions .15 .70 420@item @var{A} @tab The type of the argument shall be an @code{INTEGER}, 421@code{REAL}, or @code{COMPLEX}. 422@end multitable 423 424@item @emph{Return value}: 425The return value is of the same type and 426kind as the argument except the return value is @code{REAL} for a 427@code{COMPLEX} argument. 428 429@item @emph{Example}: 430@smallexample 431program test_abs 432 integer :: i = -1 433 real :: x = -1.e0 434 complex :: z = (-1.e0,0.e0) 435 i = abs(i) 436 x = abs(x) 437 x = abs(z) 438end program test_abs 439@end smallexample 440 441@item @emph{Specific names}: 442@multitable @columnfractions .20 .20 .20 .25 443@item Name @tab Argument @tab Return type @tab Standard 444@item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 445@item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 446@item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 447@item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later 448@item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension 449@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension 450@end multitable 451@end table 452 453 454 455@node ACCESS 456@section @code{ACCESS} --- Checks file access modes 457@fnindex ACCESS 458@cindex file system, access mode 459 460@table @asis 461@item @emph{Description}: 462@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 463exists, is readable, writable or executable. Except for the 464executable check, @code{ACCESS} can be replaced by 465Fortran 95's @code{INQUIRE}. 466 467@item @emph{Standard}: 468GNU extension 469 470@item @emph{Class}: 471Inquiry function 472 473@item @emph{Syntax}: 474@code{RESULT = ACCESS(NAME, MODE)} 475 476@item @emph{Arguments}: 477@multitable @columnfractions .15 .70 478@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 479file name. Tailing blank are ignored unless the character @code{achar(0)} 480is present, then all characters up to and excluding @code{achar(0)} are 481used as file name. 482@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the 483file access mode, may be any concatenation of @code{"r"} (readable), 484@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check 485for existence. 486@end multitable 487 488@item @emph{Return value}: 489Returns a scalar @code{INTEGER}, which is @code{0} if the file is 490accessible in the given mode; otherwise or if an invalid argument 491has been given for @code{MODE} the value @code{1} is returned. 492 493@item @emph{Example}: 494@smallexample 495program access_test 496 implicit none 497 character(len=*), parameter :: file = 'test.dat' 498 character(len=*), parameter :: file2 = 'test.dat '//achar(0) 499 if(access(file,' ') == 0) print *, trim(file),' is exists' 500 if(access(file,'r') == 0) print *, trim(file),' is readable' 501 if(access(file,'w') == 0) print *, trim(file),' is writable' 502 if(access(file,'x') == 0) print *, trim(file),' is executable' 503 if(access(file2,'rwx') == 0) & 504 print *, trim(file2),' is readable, writable and executable' 505end program access_test 506@end smallexample 507@item @emph{Specific names}: 508@item @emph{See also}: 509 510@end table 511 512 513 514@node ACHAR 515@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 516@fnindex ACHAR 517@cindex @acronym{ASCII} collating sequence 518@cindex collating sequence, @acronym{ASCII} 519 520@table @asis 521@item @emph{Description}: 522@code{ACHAR(I)} returns the character located at position @code{I} 523in the @acronym{ASCII} collating sequence. 524 525@item @emph{Standard}: 526Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 527 528@item @emph{Class}: 529Elemental function 530 531@item @emph{Syntax}: 532@code{RESULT = ACHAR(I [, KIND])} 533 534@item @emph{Arguments}: 535@multitable @columnfractions .15 .70 536@item @var{I} @tab The type shall be @code{INTEGER}. 537@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 538expression indicating the kind parameter of the result. 539@end multitable 540 541@item @emph{Return value}: 542The return value is of type @code{CHARACTER} with a length of one. 543If the @var{KIND} argument is present, the return value is of the 544specified kind and of the default kind otherwise. 545 546@item @emph{Example}: 547@smallexample 548program test_achar 549 character c 550 c = achar(32) 551end program test_achar 552@end smallexample 553 554@item @emph{Note}: 555See @ref{ICHAR} for a discussion of converting between numerical values 556and formatted string representations. 557 558@item @emph{See also}: 559@ref{CHAR}, @ref{IACHAR}, @ref{ICHAR} 560 561@end table 562 563 564 565@node ACOS 566@section @code{ACOS} --- Arccosine function 567@fnindex ACOS 568@fnindex DACOS 569@cindex trigonometric function, cosine, inverse 570@cindex cosine, inverse 571 572@table @asis 573@item @emph{Description}: 574@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}). 575 576@item @emph{Standard}: 577Fortran 77 and later, for a complex argument Fortran 2008 or later 578 579@item @emph{Class}: 580Elemental function 581 582@item @emph{Syntax}: 583@code{RESULT = ACOS(X)} 584 585@item @emph{Arguments}: 586@multitable @columnfractions .15 .70 587@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is 588less than or equal to one - or the type shall be @code{COMPLEX}. 589@end multitable 590 591@item @emph{Return value}: 592The return value is of the same type and kind as @var{X}. 593The real part of the result is in radians and lies in the range 594@math{0 \leq \Re \acos(x) \leq \pi}. 595 596@item @emph{Example}: 597@smallexample 598program test_acos 599 real(8) :: x = 0.866_8 600 x = acos(x) 601end program test_acos 602@end smallexample 603 604@item @emph{Specific names}: 605@multitable @columnfractions .20 .20 .20 .25 606@item Name @tab Argument @tab Return type @tab Standard 607@item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 608@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 609@end multitable 610 611@item @emph{See also}: 612Inverse function: @ref{COS} 613 614@end table 615 616 617 618@node ACOSH 619@section @code{ACOSH} --- Inverse hyperbolic cosine function 620@fnindex ACOSH 621@fnindex DACOSH 622@cindex area hyperbolic cosine 623@cindex inverse hyperbolic cosine 624@cindex hyperbolic function, cosine, inverse 625@cindex cosine, hyperbolic, inverse 626 627@table @asis 628@item @emph{Description}: 629@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}. 630 631@item @emph{Standard}: 632Fortran 2008 and later 633 634@item @emph{Class}: 635Elemental function 636 637@item @emph{Syntax}: 638@code{RESULT = ACOSH(X)} 639 640@item @emph{Arguments}: 641@multitable @columnfractions .15 .70 642@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 643@end multitable 644 645@item @emph{Return value}: 646The return value has the same type and kind as @var{X}. If @var{X} is 647complex, the imaginary part of the result is in radians and lies between 648@math{ 0 \leq \Im \acosh(x) \leq \pi}. 649 650@item @emph{Example}: 651@smallexample 652PROGRAM test_acosh 653 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) 654 WRITE (*,*) ACOSH(x) 655END PROGRAM 656@end smallexample 657 658@item @emph{Specific names}: 659@multitable @columnfractions .20 .20 .20 .25 660@item Name @tab Argument @tab Return type @tab Standard 661@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 662@end multitable 663 664@item @emph{See also}: 665Inverse function: @ref{COSH} 666@end table 667 668 669 670@node ADJUSTL 671@section @code{ADJUSTL} --- Left adjust a string 672@fnindex ADJUSTL 673@cindex string, adjust left 674@cindex adjust string 675 676@table @asis 677@item @emph{Description}: 678@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces. 679Spaces are inserted at the end of the string as needed. 680 681@item @emph{Standard}: 682Fortran 90 and later 683 684@item @emph{Class}: 685Elemental function 686 687@item @emph{Syntax}: 688@code{RESULT = ADJUSTL(STRING)} 689 690@item @emph{Arguments}: 691@multitable @columnfractions .15 .70 692@item @var{STRING} @tab The type shall be @code{CHARACTER}. 693@end multitable 694 695@item @emph{Return value}: 696The return value is of type @code{CHARACTER} and of the same kind as 697@var{STRING} where leading spaces are removed and the same number of 698spaces are inserted on the end of @var{STRING}. 699 700@item @emph{Example}: 701@smallexample 702program test_adjustl 703 character(len=20) :: str = ' gfortran' 704 str = adjustl(str) 705 print *, str 706end program test_adjustl 707@end smallexample 708 709@item @emph{See also}: 710@ref{ADJUSTR}, @ref{TRIM} 711@end table 712 713 714 715@node ADJUSTR 716@section @code{ADJUSTR} --- Right adjust a string 717@fnindex ADJUSTR 718@cindex string, adjust right 719@cindex adjust string 720 721@table @asis 722@item @emph{Description}: 723@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces. 724Spaces are inserted at the start of the string as needed. 725 726@item @emph{Standard}: 727Fortran 95 and later 728 729@item @emph{Class}: 730Elemental function 731 732@item @emph{Syntax}: 733@code{RESULT = ADJUSTR(STRING)} 734 735@item @emph{Arguments}: 736@multitable @columnfractions .15 .70 737@item @var{STR} @tab The type shall be @code{CHARACTER}. 738@end multitable 739 740@item @emph{Return value}: 741The return value is of type @code{CHARACTER} and of the same kind as 742@var{STRING} where trailing spaces are removed and the same number of 743spaces are inserted at the start of @var{STRING}. 744 745@item @emph{Example}: 746@smallexample 747program test_adjustr 748 character(len=20) :: str = 'gfortran' 749 str = adjustr(str) 750 print *, str 751end program test_adjustr 752@end smallexample 753 754@item @emph{See also}: 755@ref{ADJUSTL}, @ref{TRIM} 756@end table 757 758 759 760@node AIMAG 761@section @code{AIMAG} --- Imaginary part of complex number 762@fnindex AIMAG 763@fnindex DIMAG 764@fnindex IMAG 765@fnindex IMAGPART 766@cindex complex numbers, imaginary part 767 768@table @asis 769@item @emph{Description}: 770@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}. 771The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided 772for compatibility with @command{g77}, and their use in new code is 773strongly discouraged. 774 775@item @emph{Standard}: 776Fortran 77 and later, has overloads that are GNU extensions 777 778@item @emph{Class}: 779Elemental function 780 781@item @emph{Syntax}: 782@code{RESULT = AIMAG(Z)} 783 784@item @emph{Arguments}: 785@multitable @columnfractions .15 .70 786@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}. 787@end multitable 788 789@item @emph{Return value}: 790The return value is of type @code{REAL} with the 791kind type parameter of the argument. 792 793@item @emph{Example}: 794@smallexample 795program test_aimag 796 complex(4) z4 797 complex(8) z8 798 z4 = cmplx(1.e0_4, 0.e0_4) 799 z8 = cmplx(0.e0_8, 1.e0_8) 800 print *, aimag(z4), dimag(z8) 801end program test_aimag 802@end smallexample 803 804@item @emph{Specific names}: 805@multitable @columnfractions .20 .20 .20 .25 806@item Name @tab Argument @tab Return type @tab Standard 807@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 808@item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension 809@item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 810@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension 811@end multitable 812@end table 813 814 815 816@node AINT 817@section @code{AINT} --- Truncate to a whole number 818@fnindex AINT 819@fnindex DINT 820@cindex floor 821@cindex rounding, floor 822 823@table @asis 824@item @emph{Description}: 825@code{AINT(A [, KIND])} truncates its argument to a whole number. 826 827@item @emph{Standard}: 828Fortran 77 and later 829 830@item @emph{Class}: 831Elemental function 832 833@item @emph{Syntax}: 834@code{RESULT = AINT(A [, KIND])} 835 836@item @emph{Arguments}: 837@multitable @columnfractions .15 .70 838@item @var{A} @tab The type of the argument shall be @code{REAL}. 839@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 840expression indicating the kind parameter of the result. 841@end multitable 842 843@item @emph{Return value}: 844The return value is of type @code{REAL} with the kind type parameter of the 845argument if the optional @var{KIND} is absent; otherwise, the kind 846type parameter will be given by @var{KIND}. If the magnitude of 847@var{X} is less than one, @code{AINT(X)} returns zero. If the 848magnitude is equal to or greater than one then it returns the largest 849whole number that does not exceed its magnitude. The sign is the same 850as the sign of @var{X}. 851 852@item @emph{Example}: 853@smallexample 854program test_aint 855 real(4) x4 856 real(8) x8 857 x4 = 1.234E0_4 858 x8 = 4.321_8 859 print *, aint(x4), dint(x8) 860 x8 = aint(x4,8) 861end program test_aint 862@end smallexample 863 864@item @emph{Specific names}: 865@multitable @columnfractions .20 .20 .20 .25 866@item Name @tab Argument @tab Return type @tab Standard 867@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 868@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 869@end multitable 870@end table 871 872 873 874@node ALARM 875@section @code{ALARM} --- Execute a routine after a given delay 876@fnindex ALARM 877@cindex delayed execution 878 879@table @asis 880@item @emph{Description}: 881@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} 882to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to 883set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is 884supplied, it will be returned with the number of seconds remaining until 885any previously scheduled alarm was due to be delivered, or zero if there 886was no previously scheduled alarm. 887 888@item @emph{Standard}: 889GNU extension 890 891@item @emph{Class}: 892Subroutine 893 894@item @emph{Syntax}: 895@code{CALL ALARM(SECONDS, HANDLER [, STATUS])} 896 897@item @emph{Arguments}: 898@multitable @columnfractions .15 .70 899@item @var{SECONDS} @tab The type of the argument shall be a scalar 900@code{INTEGER}. It is @code{INTENT(IN)}. 901@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or 902@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 903values may be either @code{SIG_IGN=1} to ignore the alarm generated 904or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}. 905@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 906variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}. 907@end multitable 908 909@item @emph{Example}: 910@smallexample 911program test_alarm 912 external handler_print 913 integer i 914 call alarm (3, handler_print, i) 915 print *, i 916 call sleep(10) 917end program test_alarm 918@end smallexample 919This will cause the external routine @var{handler_print} to be called 920after 3 seconds. 921@end table 922 923 924 925@node ALL 926@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 927@fnindex ALL 928@cindex array, apply condition 929@cindex array, condition testing 930 931@table @asis 932@item @emph{Description}: 933@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK} 934in the array along dimension @var{DIM}. 935 936@item @emph{Standard}: 937Fortran 95 and later 938 939@item @emph{Class}: 940Transformational function 941 942@item @emph{Syntax}: 943@code{RESULT = ALL(MASK [, DIM])} 944 945@item @emph{Arguments}: 946@multitable @columnfractions .15 .70 947@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 948it shall not be scalar. 949@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 950with a value that lies between one and the rank of @var{MASK}. 951@end multitable 952 953@item @emph{Return value}: 954@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where 955the kind type parameter is the same as the kind type parameter of 956@var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns 957an array with the rank of @var{MASK} minus 1. The shape is determined from 958the shape of @var{MASK} where the @var{DIM} dimension is elided. 959 960@table @asis 961@item (A) 962@code{ALL(MASK)} is true if all elements of @var{MASK} are true. 963It also is true if @var{MASK} has zero size; otherwise, it is false. 964@item (B) 965If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent 966to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)} 967is determined by applying @code{ALL} to the array sections. 968@end table 969 970@item @emph{Example}: 971@smallexample 972program test_all 973 logical l 974 l = all((/.true., .true., .true./)) 975 print *, l 976 call section 977 contains 978 subroutine section 979 integer a(2,3), b(2,3) 980 a = 1 981 b = 1 982 b(2,2) = 2 983 print *, all(a .eq. b, 1) 984 print *, all(a .eq. b, 2) 985 end subroutine section 986end program test_all 987@end smallexample 988@end table 989 990 991 992@node ALLOCATED 993@section @code{ALLOCATED} --- Status of an allocatable entity 994@fnindex ALLOCATED 995@cindex allocation, status 996 997@table @asis 998@item @emph{Description}: 999@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation 1000status of @var{ARRAY} and @var{SCALAR}, respectively. 1001 1002@item @emph{Standard}: 1003Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable 1004scalar entities are available in Fortran 2003 and later. 1005 1006@item @emph{Class}: 1007Inquiry function 1008 1009@item @emph{Syntax}: 1010@multitable @columnfractions .80 1011@item @code{RESULT = ALLOCATED(ARRAY)} 1012@item @code{RESULT = ALLOCATED(SCALAR)} 1013@end multitable 1014 1015@item @emph{Arguments}: 1016@multitable @columnfractions .15 .70 1017@item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array. 1018@item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar. 1019@end multitable 1020 1021@item @emph{Return value}: 1022The return value is a scalar @code{LOGICAL} with the default logical 1023kind type parameter. If the argument is allocated, then the result is 1024@code{.TRUE.}; otherwise, it returns @code{.FALSE.} 1025 1026@item @emph{Example}: 1027@smallexample 1028program test_allocated 1029 integer :: i = 4 1030 real(4), allocatable :: x(:) 1031 if (.not. allocated(x)) allocate(x(i)) 1032end program test_allocated 1033@end smallexample 1034@end table 1035 1036 1037 1038@node AND 1039@section @code{AND} --- Bitwise logical AND 1040@fnindex AND 1041@cindex bitwise logical and 1042@cindex logical and, bitwise 1043 1044@table @asis 1045@item @emph{Description}: 1046Bitwise logical @code{AND}. 1047 1048This intrinsic routine is provided for backwards compatibility with 1049GNU Fortran 77. For integer arguments, programmers should consider 1050the use of the @ref{IAND} intrinsic defined by the Fortran standard. 1051 1052@item @emph{Standard}: 1053GNU extension 1054 1055@item @emph{Class}: 1056Function 1057 1058@item @emph{Syntax}: 1059@code{RESULT = AND(I, J)} 1060 1061@item @emph{Arguments}: 1062@multitable @columnfractions .15 .70 1063@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 1064type or a scalar @code{LOGICAL} type. 1065@item @var{J} @tab The type shall be the same as the type of @var{I}. 1066@end multitable 1067 1068@item @emph{Return value}: 1069The return type is either a scalar @code{INTEGER} or a scalar 1070@code{LOGICAL}. If the kind type parameters differ, then the 1071smaller kind type is implicitly converted to larger kind, and the 1072return has the larger kind. 1073 1074@item @emph{Example}: 1075@smallexample 1076PROGRAM test_and 1077 LOGICAL :: T = .TRUE., F = .FALSE. 1078 INTEGER :: a, b 1079 DATA a / Z'F' /, b / Z'3' / 1080 1081 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F) 1082 WRITE (*,*) AND(a, b) 1083END PROGRAM 1084@end smallexample 1085 1086@item @emph{See also}: 1087Fortran 95 elemental function: @ref{IAND} 1088@end table 1089 1090 1091 1092@node ANINT 1093@section @code{ANINT} --- Nearest whole number 1094@fnindex ANINT 1095@fnindex DNINT 1096@cindex ceiling 1097@cindex rounding, ceiling 1098 1099@table @asis 1100@item @emph{Description}: 1101@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number. 1102 1103@item @emph{Standard}: 1104Fortran 77 and later 1105 1106@item @emph{Class}: 1107Elemental function 1108 1109@item @emph{Syntax}: 1110@code{RESULT = ANINT(A [, KIND])} 1111 1112@item @emph{Arguments}: 1113@multitable @columnfractions .15 .70 1114@item @var{A} @tab The type of the argument shall be @code{REAL}. 1115@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 1116expression indicating the kind parameter of the result. 1117@end multitable 1118 1119@item @emph{Return value}: 1120The return value is of type real with the kind type parameter of the 1121argument if the optional @var{KIND} is absent; otherwise, the kind 1122type parameter will be given by @var{KIND}. If @var{A} is greater than 1123zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is 1124less than or equal to zero then it returns @code{AINT(X-0.5)}. 1125 1126@item @emph{Example}: 1127@smallexample 1128program test_anint 1129 real(4) x4 1130 real(8) x8 1131 x4 = 1.234E0_4 1132 x8 = 4.321_8 1133 print *, anint(x4), dnint(x8) 1134 x8 = anint(x4,8) 1135end program test_anint 1136@end smallexample 1137 1138@item @emph{Specific names}: 1139@multitable @columnfractions .20 .20 .20 .25 1140@item Name @tab Argument @tab Return type @tab Standard 1141@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later 1142@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later 1143@end multitable 1144@end table 1145 1146 1147 1148@node ANY 1149@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 1150@fnindex ANY 1151@cindex array, apply condition 1152@cindex array, condition testing 1153 1154@table @asis 1155@item @emph{Description}: 1156@code{ANY(MASK [, DIM])} determines if any of the values in the logical array 1157@var{MASK} along dimension @var{DIM} are @code{.TRUE.}. 1158 1159@item @emph{Standard}: 1160Fortran 95 and later 1161 1162@item @emph{Class}: 1163Transformational function 1164 1165@item @emph{Syntax}: 1166@code{RESULT = ANY(MASK [, DIM])} 1167 1168@item @emph{Arguments}: 1169@multitable @columnfractions .15 .70 1170@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and 1171it shall not be scalar. 1172@item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer 1173with a value that lies between one and the rank of @var{MASK}. 1174@end multitable 1175 1176@item @emph{Return value}: 1177@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where 1178the kind type parameter is the same as the kind type parameter of 1179@var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns 1180an array with the rank of @var{MASK} minus 1. The shape is determined from 1181the shape of @var{MASK} where the @var{DIM} dimension is elided. 1182 1183@table @asis 1184@item (A) 1185@code{ANY(MASK)} is true if any element of @var{MASK} is true; 1186otherwise, it is false. It also is false if @var{MASK} has zero size. 1187@item (B) 1188If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent 1189to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)} 1190is determined by applying @code{ANY} to the array sections. 1191@end table 1192 1193@item @emph{Example}: 1194@smallexample 1195program test_any 1196 logical l 1197 l = any((/.true., .true., .true./)) 1198 print *, l 1199 call section 1200 contains 1201 subroutine section 1202 integer a(2,3), b(2,3) 1203 a = 1 1204 b = 1 1205 b(2,2) = 2 1206 print *, any(a .eq. b, 1) 1207 print *, any(a .eq. b, 2) 1208 end subroutine section 1209end program test_any 1210@end smallexample 1211@end table 1212 1213 1214 1215@node ASIN 1216@section @code{ASIN} --- Arcsine function 1217@fnindex ASIN 1218@fnindex DASIN 1219@cindex trigonometric function, sine, inverse 1220@cindex sine, inverse 1221 1222@table @asis 1223@item @emph{Description}: 1224@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}). 1225 1226@item @emph{Standard}: 1227Fortran 77 and later, for a complex argument Fortran 2008 or later 1228 1229@item @emph{Class}: 1230Elemental function 1231 1232@item @emph{Syntax}: 1233@code{RESULT = ASIN(X)} 1234 1235@item @emph{Arguments}: 1236@multitable @columnfractions .15 .70 1237@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is 1238less than or equal to one - or be @code{COMPLEX}. 1239@end multitable 1240 1241@item @emph{Return value}: 1242The return value is of the same type and kind as @var{X}. 1243The real part of the result is in radians and lies in the range 1244@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}. 1245 1246@item @emph{Example}: 1247@smallexample 1248program test_asin 1249 real(8) :: x = 0.866_8 1250 x = asin(x) 1251end program test_asin 1252@end smallexample 1253 1254@item @emph{Specific names}: 1255@multitable @columnfractions .20 .20 .20 .25 1256@item Name @tab Argument @tab Return type @tab Standard 1257@item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1258@item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1259@end multitable 1260 1261@item @emph{See also}: 1262Inverse function: @ref{SIN} 1263 1264@end table 1265 1266 1267 1268@node ASINH 1269@section @code{ASINH} --- Inverse hyperbolic sine function 1270@fnindex ASINH 1271@fnindex DASINH 1272@cindex area hyperbolic sine 1273@cindex inverse hyperbolic sine 1274@cindex hyperbolic function, sine, inverse 1275@cindex sine, hyperbolic, inverse 1276 1277@table @asis 1278@item @emph{Description}: 1279@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}. 1280 1281@item @emph{Standard}: 1282Fortran 2008 and later 1283 1284@item @emph{Class}: 1285Elemental function 1286 1287@item @emph{Syntax}: 1288@code{RESULT = ASINH(X)} 1289 1290@item @emph{Arguments}: 1291@multitable @columnfractions .15 .70 1292@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1293@end multitable 1294 1295@item @emph{Return value}: 1296The return value is of the same type and kind as @var{X}. If @var{X} is 1297complex, the imaginary part of the result is in radians and lies between 1298@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}. 1299 1300@item @emph{Example}: 1301@smallexample 1302PROGRAM test_asinh 1303 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1304 WRITE (*,*) ASINH(x) 1305END PROGRAM 1306@end smallexample 1307 1308@item @emph{Specific names}: 1309@multitable @columnfractions .20 .20 .20 .25 1310@item Name @tab Argument @tab Return type @tab Standard 1311@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension. 1312@end multitable 1313 1314@item @emph{See also}: 1315Inverse function: @ref{SINH} 1316@end table 1317 1318 1319 1320@node ASSOCIATED 1321@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 1322@fnindex ASSOCIATED 1323@cindex pointer, status 1324@cindex association status 1325 1326@table @asis 1327@item @emph{Description}: 1328@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer 1329@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}. 1330 1331@item @emph{Standard}: 1332Fortran 95 and later 1333 1334@item @emph{Class}: 1335Inquiry function 1336 1337@item @emph{Syntax}: 1338@code{RESULT = ASSOCIATED(POINTER [, TARGET])} 1339 1340@item @emph{Arguments}: 1341@multitable @columnfractions .15 .70 1342@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute 1343and it can be of any type. 1344@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or 1345a target. It must have the same type, kind type parameter, and 1346array rank as @var{POINTER}. 1347@end multitable 1348The association status of neither @var{POINTER} nor @var{TARGET} shall be 1349undefined. 1350 1351@item @emph{Return value}: 1352@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}. 1353There are several cases: 1354@table @asis 1355@item (A) When the optional @var{TARGET} is not present then 1356@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false. 1357@item (B) If @var{TARGET} is present and a scalar target, the result is true if 1358@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 1359disassociated, the result is false. 1360@item (C) If @var{TARGET} is present and an array target, the result is true if 1361@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays, 1362are arrays whose elements are not zero-sized storage sequences, and 1363@var{TARGET} and @var{POINTER} occupy the same storage units in array element 1364order. 1365As in case(B), the result is false, if @var{POINTER} is disassociated. 1366@item (D) If @var{TARGET} is present and an scalar pointer, the result is true 1367if @var{TARGET} is associated with @var{POINTER}, the target associated with 1368@var{TARGET} are not zero-sized storage sequences and occupy the same storage 1369units. 1370The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1371@item (E) If @var{TARGET} is present and an array pointer, the result is true if 1372target associated with @var{POINTER} and the target associated with @var{TARGET} 1373have the same shape, are not zero-sized arrays, are arrays whose elements are 1374not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy 1375the same storage units in array element order. 1376The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. 1377@end table 1378 1379@item @emph{Example}: 1380@smallexample 1381program test_associated 1382 implicit none 1383 real, target :: tgt(2) = (/1., 2./) 1384 real, pointer :: ptr(:) 1385 ptr => tgt 1386 if (associated(ptr) .eqv. .false.) call abort 1387 if (associated(ptr,tgt) .eqv. .false.) call abort 1388end program test_associated 1389@end smallexample 1390 1391@item @emph{See also}: 1392@ref{NULL} 1393@end table 1394 1395 1396 1397@node ATAN 1398@section @code{ATAN} --- Arctangent function 1399@fnindex ATAN 1400@fnindex DATAN 1401@cindex trigonometric function, tangent, inverse 1402@cindex tangent, inverse 1403 1404@table @asis 1405@item @emph{Description}: 1406@code{ATAN(X)} computes the arctangent of @var{X}. 1407 1408@item @emph{Standard}: 1409Fortran 77 and later, for a complex argument and for two arguments 1410Fortran 2008 or later 1411 1412@item @emph{Class}: 1413Elemental function 1414 1415@item @emph{Syntax}: 1416@multitable @columnfractions .80 1417@item @code{RESULT = ATAN(X)} 1418@item @code{RESULT = ATAN(Y, X)} 1419@end multitable 1420 1421@item @emph{Arguments}: 1422@multitable @columnfractions .15 .70 1423@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; 1424if @var{Y} is present, @var{X} shall be REAL. 1425@item @var{Y} shall be of the same type and kind as @var{X}. 1426@end multitable 1427 1428@item @emph{Return value}: 1429The return value is of the same type and kind as @var{X}. 1430If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}. 1431Otherwise, it the arcus tangent of @var{X}, where the real part of 1432the result is in radians and lies in the range 1433@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}. 1434 1435@item @emph{Example}: 1436@smallexample 1437program test_atan 1438 real(8) :: x = 2.866_8 1439 x = atan(x) 1440end program test_atan 1441@end smallexample 1442 1443@item @emph{Specific names}: 1444@multitable @columnfractions .20 .20 .20 .25 1445@item Name @tab Argument @tab Return type @tab Standard 1446@item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 1447@item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 1448@end multitable 1449 1450@item @emph{See also}: 1451Inverse function: @ref{TAN} 1452 1453@end table 1454 1455 1456 1457@node ATAN2 1458@section @code{ATAN2} --- Arctangent function 1459@fnindex ATAN2 1460@fnindex DATAN2 1461@cindex trigonometric function, tangent, inverse 1462@cindex tangent, inverse 1463 1464@table @asis 1465@item @emph{Description}: 1466@code{ATAN2(Y, X)} computes the principal value of the argument 1467function of the complex number @math{X + i Y}. This function can 1468be used to transform from Cartesian into polar coordinates and 1469allows to determine the angle in the correct quadrant. 1470 1471@item @emph{Standard}: 1472Fortran 77 and later 1473 1474@item @emph{Class}: 1475Elemental function 1476 1477@item @emph{Syntax}: 1478@code{RESULT = ATAN2(Y, X)} 1479 1480@item @emph{Arguments}: 1481@multitable @columnfractions .15 .70 1482@item @var{Y} @tab The type shall be @code{REAL}. 1483@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. 1484If @var{Y} is zero, then @var{X} must be nonzero. 1485@end multitable 1486 1487@item @emph{Return value}: 1488The return value has the same type and kind type parameter as @var{Y}. It 1489is the principal value of the complex number @math{X + i Y}. If @var{X} 1490is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}. 1491The sign is positive if @var{Y} is positive. If @var{Y} is zero, then 1492the return value is zero if @var{X} is strictly positive, @math{\pi} if 1493@var{X} is negative and @var{Y} is positive zero (or the processor does 1494not handle signed zeros), and @math{-\pi} if @var{X} is negative and 1495@var{Y} is negative zero. Finally, if @var{X} is zero, then the 1496magnitude of the result is @math{\pi/2}. 1497 1498@item @emph{Example}: 1499@smallexample 1500program test_atan2 1501 real(4) :: x = 1.e0_4, y = 0.5e0_4 1502 x = atan2(y,x) 1503end program test_atan2 1504@end smallexample 1505 1506@item @emph{Specific names}: 1507@multitable @columnfractions .20 .20 .20 .25 1508@item Name @tab Argument @tab Return type @tab Standard 1509@item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 1510@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 1511@end multitable 1512@end table 1513 1514 1515 1516@node ATANH 1517@section @code{ATANH} --- Inverse hyperbolic tangent function 1518@fnindex ATANH 1519@fnindex DATANH 1520@cindex area hyperbolic tangent 1521@cindex inverse hyperbolic tangent 1522@cindex hyperbolic function, tangent, inverse 1523@cindex tangent, hyperbolic, inverse 1524 1525@table @asis 1526@item @emph{Description}: 1527@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}. 1528 1529@item @emph{Standard}: 1530Fortran 2008 and later 1531 1532@item @emph{Class}: 1533Elemental function 1534 1535@item @emph{Syntax}: 1536@code{RESULT = ATANH(X)} 1537 1538@item @emph{Arguments}: 1539@multitable @columnfractions .15 .70 1540@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 1541@end multitable 1542 1543@item @emph{Return value}: 1544The return value has same type and kind as @var{X}. If @var{X} is 1545complex, the imaginary part of the result is in radians and lies between 1546@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}. 1547 1548@item @emph{Example}: 1549@smallexample 1550PROGRAM test_atanh 1551 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) 1552 WRITE (*,*) ATANH(x) 1553END PROGRAM 1554@end smallexample 1555 1556@item @emph{Specific names}: 1557@multitable @columnfractions .20 .20 .20 .25 1558@item Name @tab Argument @tab Return type @tab Standard 1559@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 1560@end multitable 1561 1562@item @emph{See also}: 1563Inverse function: @ref{TANH} 1564@end table 1565 1566 1567 1568@node ATOMIC_ADD 1569@section @code{ATOMIC_ADD} --- Atomic ADD operation 1570@fnindex ATOMIC_ADD 1571@cindex Atomic subroutine, add 1572 1573@table @asis 1574@item @emph{Description}: 1575@code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the 1576variable @var{ATOM}. When @var{STAT} is present and the invokation was 1577successful, it is assigned the value 0. If it is present and the invokation 1578has failed, it is assigned a positive value; in particular, for a coindexed 1579@var{ATOM}, if the remote image has stopped, it is assigned the value of 1580@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1581failed, the value @code{STAT_FAILED_IMAGE}. 1582 1583@item @emph{Standard}: 1584TS 18508 or later 1585 1586@item @emph{Class}: 1587Atomic subroutine 1588 1589@item @emph{Syntax}: 1590@code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])} 1591 1592@item @emph{Arguments}: 1593@multitable @columnfractions .15 .70 1594@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1595type with @code{ATOMIC_INT_KIND} kind. 1596@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1597is different, the value is converted to the kind of @var{ATOM}. 1598@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1599@end multitable 1600 1601@item @emph{Example}: 1602@smallexample 1603program atomic 1604 use iso_fortran_env 1605 integer(atomic_int_kind) :: atom[*] 1606 call atomic_add (atom[1], this_image()) 1607end program atomic 1608@end smallexample 1609 1610@item @emph{See also}: 1611@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV}, 1612@ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 1613@end table 1614 1615 1616 1617 1618@node ATOMIC_AND 1619@section @code{ATOMIC_AND} --- Atomic bitwise AND operation 1620@fnindex ATOMIC_AND 1621@cindex Atomic subroutine, AND 1622 1623@table @asis 1624@item @emph{Description}: 1625@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 1626AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 1627and the invokation was successful, it is assigned the value 0. If it is present 1628and the invokation has failed, it is assigned a positive value; in particular, 1629for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 1630value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 1631image has failed, the value @code{STAT_FAILED_IMAGE}. 1632 1633@item @emph{Standard}: 1634TS 18508 or later 1635 1636@item @emph{Class}: 1637Atomic subroutine 1638 1639@item @emph{Syntax}: 1640@code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])} 1641 1642@item @emph{Arguments}: 1643@multitable @columnfractions .15 .70 1644@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1645type with @code{ATOMIC_INT_KIND} kind. 1646@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1647is different, the value is converted to the kind of @var{ATOM}. 1648@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1649@end multitable 1650 1651@item @emph{Example}: 1652@smallexample 1653program atomic 1654 use iso_fortran_env 1655 integer(atomic_int_kind) :: atom[*] 1656 call atomic_and (atom[1], int(b'10100011101')) 1657end program atomic 1658@end smallexample 1659 1660@item @emph{See also}: 1661@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV}, 1662@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 1663@end table 1664 1665 1666 1667@node ATOMIC_CAS 1668@section @code{ATOMIC_CAS} --- Atomic compare and swap 1669@fnindex ATOMIC_DEFINE 1670@cindex Atomic subroutine, compare and swap 1671 1672@table @asis 1673@item @emph{Description}: 1674@code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of 1675@var{COMPARE}; if the value is the same, @var{ATOM} is set to the value 1676of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM} 1677that was used for the comparison. When @var{STAT} is present and the invokation 1678was successful, it is assigned the value 0. If it is present and the invokation 1679has failed, it is assigned a positive value; in particular, for a coindexed 1680@var{ATOM}, if the remote image has stopped, it is assigned the value of 1681@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1682failed, the value @code{STAT_FAILED_IMAGE}. 1683 1684@item @emph{Standard}: 1685TS 18508 or later 1686 1687@item @emph{Class}: 1688Atomic subroutine 1689 1690@item @emph{Syntax}: 1691@code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])} 1692 1693@item @emph{Arguments}: 1694@multitable @columnfractions .15 .70 1695@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 1696type with @code{ATOMIC_INT_KIND} kind or logical type with 1697@code{ATOMIC_LOGICAL_KIND} kind. 1698@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 1699@item @var{COMPARE} @tab Scalar variable of the same type and kind as 1700@var{ATOM}. 1701@item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind 1702is different, the value is converted to the kind of @var{ATOM}. 1703@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1704@end multitable 1705 1706@item @emph{Example}: 1707@smallexample 1708program atomic 1709 use iso_fortran_env 1710 logical(atomic_logical_kind) :: atom[*], prev 1711 call atomic_cas (atom[1], prev, .false., .true.)) 1712end program atomic 1713@end smallexample 1714 1715@item @emph{See also}: 1716@ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV} 1717@end table 1718 1719 1720 1721@node ATOMIC_DEFINE 1722@section @code{ATOMIC_DEFINE} --- Setting a variable atomically 1723@fnindex ATOMIC_DEFINE 1724@cindex Atomic subroutine, define 1725 1726@table @asis 1727@item @emph{Description}: 1728@code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value 1729@var{VALUE} atomically. When @var{STAT} is present and the invokation was 1730successful, it is assigned the value 0. If it is present and the invokation 1731has failed, it is assigned a positive value; in particular, for a coindexed 1732@var{ATOM}, if the remote image has stopped, it is assigned the value of 1733@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1734failed, the value @code{STAT_FAILED_IMAGE}. 1735 1736@item @emph{Standard}: 1737Fortran 2008 and later; with @var{STAT}, TS 18508 or later 1738 1739@item @emph{Class}: 1740Atomic subroutine 1741 1742@item @emph{Syntax}: 1743@code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])} 1744 1745@item @emph{Arguments}: 1746@multitable @columnfractions .15 .70 1747@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 1748type with @code{ATOMIC_INT_KIND} kind or logical type with 1749@code{ATOMIC_LOGICAL_KIND} kind. 1750 1751@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1752is different, the value is converted to the kind of @var{ATOM}. 1753@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1754@end multitable 1755 1756@item @emph{Example}: 1757@smallexample 1758program atomic 1759 use iso_fortran_env 1760 integer(atomic_int_kind) :: atom[*] 1761 call atomic_define (atom[1], this_image()) 1762end program atomic 1763@end smallexample 1764 1765@item @emph{See also}: 1766@ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV}, 1767@ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 1768@end table 1769 1770 1771 1772@node ATOMIC_FETCH_ADD 1773@section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch 1774@fnindex ATOMIC_FETCH_ADD 1775@cindex Atomic subroutine, ADD with fetch 1776 1777@table @asis 1778@item @emph{Description}: 1779@code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of 1780@var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the 1781variable @var{ATOM}. When @var{STAT} is present and the invokation was 1782successful, it is assigned the value 0. If it is present and the invokation 1783has failed, it is assigned a positive value; in particular, for a coindexed 1784@var{ATOM}, if the remote image has stopped, it is assigned the value of 1785@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1786failed, the value @code{STAT_FAILED_IMAGE}. 1787 1788@item @emph{Standard}: 1789TS 18508 or later 1790 1791@item @emph{Class}: 1792Atomic subroutine 1793 1794@item @emph{Syntax}: 1795@code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])} 1796 1797@item @emph{Arguments}: 1798@multitable @columnfractions .15 .70 1799@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1800type with @code{ATOMIC_INT_KIND} kind. 1801@code{ATOMIC_LOGICAL_KIND} kind. 1802 1803@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1804is different, the value is converted to the kind of @var{ATOM}. 1805@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 1806@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1807@end multitable 1808 1809@item @emph{Example}: 1810@smallexample 1811program atomic 1812 use iso_fortran_env 1813 integer(atomic_int_kind) :: atom[*], old 1814 call atomic_add (atom[1], this_image(), old) 1815end program atomic 1816@end smallexample 1817 1818@item @emph{See also}: 1819@ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV}, 1820@ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} 1821@end table 1822 1823 1824 1825@node ATOMIC_FETCH_AND 1826@section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch 1827@fnindex ATOMIC_FETCH_AND 1828@cindex Atomic subroutine, AND with fetch 1829 1830@table @asis 1831@item @emph{Description}: 1832@code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 1833@var{OLD} and defines @var{ATOM} with the bitwise AND between the values of 1834@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was 1835successful, it is assigned the value 0. If it is present and the invokation has 1836failed, it is assigned a positive value; in particular, for a coindexed 1837@var{ATOM}, if the remote image has stopped, it is assigned the value of 1838@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1839failed, the value @code{STAT_FAILED_IMAGE}. 1840 1841@item @emph{Standard}: 1842TS 18508 or later 1843 1844@item @emph{Class}: 1845Atomic subroutine 1846 1847@item @emph{Syntax}: 1848@code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])} 1849 1850@item @emph{Arguments}: 1851@multitable @columnfractions .15 .70 1852@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1853type with @code{ATOMIC_INT_KIND} kind. 1854@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1855is different, the value is converted to the kind of @var{ATOM}. 1856@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 1857@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1858@end multitable 1859 1860@item @emph{Example}: 1861@smallexample 1862program atomic 1863 use iso_fortran_env 1864 integer(atomic_int_kind) :: atom[*], old 1865 call atomic_fetch_and (atom[1], int(b'10100011101'), old) 1866end program atomic 1867@end smallexample 1868 1869@item @emph{See also}: 1870@ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV}, 1871@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} 1872@end table 1873 1874 1875 1876@node ATOMIC_FETCH_OR 1877@section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch 1878@fnindex ATOMIC_FETCH_OR 1879@cindex Atomic subroutine, OR with fetch 1880 1881@table @asis 1882@item @emph{Description}: 1883@code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 1884@var{OLD} and defines @var{ATOM} with the bitwise OR between the values of 1885@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was 1886successful, it is assigned the value 0. If it is present and the invokation has 1887failed, it is assigned a positive value; in particular, for a coindexed 1888@var{ATOM}, if the remote image has stopped, it is assigned the value of 1889@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1890failed, the value @code{STAT_FAILED_IMAGE}. 1891 1892@item @emph{Standard}: 1893TS 18508 or later 1894 1895@item @emph{Class}: 1896Atomic subroutine 1897 1898@item @emph{Syntax}: 1899@code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])} 1900 1901@item @emph{Arguments}: 1902@multitable @columnfractions .15 .70 1903@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1904type with @code{ATOMIC_INT_KIND} kind. 1905@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1906is different, the value is converted to the kind of @var{ATOM}. 1907@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 1908@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1909@end multitable 1910 1911@item @emph{Example}: 1912@smallexample 1913program atomic 1914 use iso_fortran_env 1915 integer(atomic_int_kind) :: atom[*], old 1916 call atomic_fetch_or (atom[1], int(b'10100011101'), old) 1917end program atomic 1918@end smallexample 1919 1920@item @emph{See also}: 1921@ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV}, 1922@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR} 1923@end table 1924 1925 1926 1927@node ATOMIC_FETCH_XOR 1928@section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch 1929@fnindex ATOMIC_FETCH_XOR 1930@cindex Atomic subroutine, XOR with fetch 1931 1932@table @asis 1933@item @emph{Description}: 1934@code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in 1935@var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of 1936@var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was 1937successful, it is assigned the value 0. If it is present and the invokation has 1938failed, it is assigned a positive value; in particular, for a coindexed 1939@var{ATOM}, if the remote image has stopped, it is assigned the value of 1940@code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has 1941failed, the value @code{STAT_FAILED_IMAGE}. 1942 1943@item @emph{Standard}: 1944TS 18508 or later 1945 1946@item @emph{Class}: 1947Atomic subroutine 1948 1949@item @emph{Syntax}: 1950@code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])} 1951 1952@item @emph{Arguments}: 1953@multitable @columnfractions .15 .70 1954@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 1955type with @code{ATOMIC_INT_KIND} kind. 1956@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 1957is different, the value is converted to the kind of @var{ATOM}. 1958@item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. 1959@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 1960@end multitable 1961 1962@item @emph{Example}: 1963@smallexample 1964program atomic 1965 use iso_fortran_env 1966 integer(atomic_int_kind) :: atom[*], old 1967 call atomic_fetch_xor (atom[1], int(b'10100011101'), old) 1968end program atomic 1969@end smallexample 1970 1971@item @emph{See also}: 1972@ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV}, 1973@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR} 1974@end table 1975 1976 1977 1978@node ATOMIC_OR 1979@section @code{ATOMIC_OR} --- Atomic bitwise OR operation 1980@fnindex ATOMIC_OR 1981@cindex Atomic subroutine, OR 1982 1983@table @asis 1984@item @emph{Description}: 1985@code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 1986AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 1987and the invokation was successful, it is assigned the value 0. If it is present 1988and the invokation has failed, it is assigned a positive value; in particular, 1989for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 1990value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 1991image has failed, the value @code{STAT_FAILED_IMAGE}. 1992 1993@item @emph{Standard}: 1994TS 18508 or later 1995 1996@item @emph{Class}: 1997Atomic subroutine 1998 1999@item @emph{Syntax}: 2000@code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])} 2001 2002@item @emph{Arguments}: 2003@multitable @columnfractions .15 .70 2004@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2005type with @code{ATOMIC_INT_KIND} kind. 2006@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2007is different, the value is converted to the kind of @var{ATOM}. 2008@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2009@end multitable 2010 2011@item @emph{Example}: 2012@smallexample 2013program atomic 2014 use iso_fortran_env 2015 integer(atomic_int_kind) :: atom[*] 2016 call atomic_or (atom[1], int(b'10100011101')) 2017end program atomic 2018@end smallexample 2019 2020@item @emph{See also}: 2021@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV}, 2022@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 2023@end table 2024 2025 2026 2027@node ATOMIC_REF 2028@section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically 2029@fnindex ATOMIC_REF 2030@cindex Atomic subroutine, reference 2031 2032@table @asis 2033@item @emph{Description}: 2034@code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the 2035variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the 2036invokation was successful, it is assigned the value 0. If it is present and the 2037invokation has failed, it is assigned a positive value; in particular, for a 2038coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value 2039of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image 2040has failed, the value @code{STAT_FAILED_IMAGE}. 2041 2042 2043@item @emph{Standard}: 2044Fortran 2008 and later; with @var{STAT}, TS 18508 or later 2045 2046@item @emph{Class}: 2047Atomic subroutine 2048 2049@item @emph{Syntax}: 2050@code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])} 2051 2052@item @emph{Arguments}: 2053@multitable @columnfractions .15 .70 2054@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2055is different, the value is converted to the kind of @var{ATOM}. 2056@item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer 2057type with @code{ATOMIC_INT_KIND} kind or logical type with 2058@code{ATOMIC_LOGICAL_KIND} kind. 2059@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2060@end multitable 2061 2062@item @emph{Example}: 2063@smallexample 2064program atomic 2065 use iso_fortran_env 2066 logical(atomic_logical_kind) :: atom[*] 2067 logical :: val 2068 call atomic_ref (atom, .false.) 2069 ! ... 2070 call atomic_ref (atom, val) 2071 if (val) then 2072 print *, "Obtained" 2073 end if 2074end program atomic 2075@end smallexample 2076 2077@item @emph{See also}: 2078@ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV}, 2079@ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, 2080@ref{ATOMIC_FETCH_XOR} 2081@end table 2082 2083 2084@node ATOMIC_XOR 2085@section @code{ATOMIC_XOR} --- Atomic bitwise OR operation 2086@fnindex ATOMIC_XOR 2087@cindex Atomic subroutine, XOR 2088 2089@table @asis 2090@item @emph{Description}: 2091@code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise 2092XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present 2093and the invokation was successful, it is assigned the value 0. If it is present 2094and the invokation has failed, it is assigned a positive value; in particular, 2095for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the 2096value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote 2097image has failed, the value @code{STAT_FAILED_IMAGE}. 2098 2099@item @emph{Standard}: 2100TS 18508 or later 2101 2102@item @emph{Class}: 2103Atomic subroutine 2104 2105@item @emph{Syntax}: 2106@code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])} 2107 2108@item @emph{Arguments}: 2109@multitable @columnfractions .15 .70 2110@item @var{ATOM} @tab Scalar coarray or coindexed variable of integer 2111type with @code{ATOMIC_INT_KIND} kind. 2112@item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind 2113is different, the value is converted to the kind of @var{ATOM}. 2114@item @var{STAT} @tab (optional) Scalar default-kind integer variable. 2115@end multitable 2116 2117@item @emph{Example}: 2118@smallexample 2119program atomic 2120 use iso_fortran_env 2121 integer(atomic_int_kind) :: atom[*] 2122 call atomic_xor (atom[1], int(b'10100011101')) 2123end program atomic 2124@end smallexample 2125 2126@item @emph{See also}: 2127@ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV}, 2128@ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} 2129@end table 2130 2131 2132@node BACKTRACE 2133@section @code{BACKTRACE} --- Show a backtrace 2134@fnindex BACKTRACE 2135@cindex backtrace 2136 2137@table @asis 2138@item @emph{Description}: 2139@code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program 2140execution continues normally afterwards. The backtrace information is printed 2141to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}. 2142 2143@item @emph{Standard}: 2144GNU Extension 2145 2146@item @emph{Class}: 2147Subroutine 2148 2149@item @emph{Syntax}: 2150@code{CALL BACKTRACE} 2151 2152@item @emph{Arguments}: 2153None 2154 2155@item @emph{See also}: 2156@ref{ABORT} 2157@end table 2158 2159 2160 2161@node BESSEL_J0 2162@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0 2163@fnindex BESSEL_J0 2164@fnindex BESJ0 2165@fnindex DBESJ0 2166@cindex Bessel function, first kind 2167 2168@table @asis 2169@item @emph{Description}: 2170@code{BESSEL_J0(X)} computes the Bessel function of the first kind of 2171order 0 of @var{X}. This function is available under the name 2172@code{BESJ0} as a GNU extension. 2173 2174@item @emph{Standard}: 2175Fortran 2008 and later 2176 2177@item @emph{Class}: 2178Elemental function 2179 2180@item @emph{Syntax}: 2181@code{RESULT = BESSEL_J0(X)} 2182 2183@item @emph{Arguments}: 2184@multitable @columnfractions .15 .70 2185@item @var{X} @tab The type shall be @code{REAL}. 2186@end multitable 2187 2188@item @emph{Return value}: 2189The return value is of type @code{REAL} and lies in the 2190range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same 2191kind as @var{X}. 2192 2193@item @emph{Example}: 2194@smallexample 2195program test_besj0 2196 real(8) :: x = 0.0_8 2197 x = bessel_j0(x) 2198end program test_besj0 2199@end smallexample 2200 2201@item @emph{Specific names}: 2202@multitable @columnfractions .20 .20 .20 .25 2203@item Name @tab Argument @tab Return type @tab Standard 2204@item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2205@end multitable 2206@end table 2207 2208 2209 2210@node BESSEL_J1 2211@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1 2212@fnindex BESSEL_J1 2213@fnindex BESJ1 2214@fnindex DBESJ1 2215@cindex Bessel function, first kind 2216 2217@table @asis 2218@item @emph{Description}: 2219@code{BESSEL_J1(X)} computes the Bessel function of the first kind of 2220order 1 of @var{X}. This function is available under the name 2221@code{BESJ1} as a GNU extension. 2222 2223@item @emph{Standard}: 2224Fortran 2008 2225 2226@item @emph{Class}: 2227Elemental function 2228 2229@item @emph{Syntax}: 2230@code{RESULT = BESSEL_J1(X)} 2231 2232@item @emph{Arguments}: 2233@multitable @columnfractions .15 .70 2234@item @var{X} @tab The type shall be @code{REAL}. 2235@end multitable 2236 2237@item @emph{Return value}: 2238The return value is of type @code{REAL} and lies in the 2239range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same 2240kind as @var{X}. 2241 2242@item @emph{Example}: 2243@smallexample 2244program test_besj1 2245 real(8) :: x = 1.0_8 2246 x = bessel_j1(x) 2247end program test_besj1 2248@end smallexample 2249 2250@item @emph{Specific names}: 2251@multitable @columnfractions .20 .20 .20 .25 2252@item Name @tab Argument @tab Return type @tab Standard 2253@item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2254@end multitable 2255@end table 2256 2257 2258 2259@node BESSEL_JN 2260@section @code{BESSEL_JN} --- Bessel function of the first kind 2261@fnindex BESSEL_JN 2262@fnindex BESJN 2263@fnindex DBESJN 2264@cindex Bessel function, first kind 2265 2266@table @asis 2267@item @emph{Description}: 2268@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of 2269order @var{N} of @var{X}. This function is available under the name 2270@code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays, 2271their ranks and shapes shall conform. 2272 2273@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions 2274of the first kind of the orders @var{N1} to @var{N2}. 2275 2276@item @emph{Standard}: 2277Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2278 2279@item @emph{Class}: 2280Elemental function, except for the transformational function 2281@code{BESSEL_JN(N1, N2, X)} 2282 2283@item @emph{Syntax}: 2284@multitable @columnfractions .80 2285@item @code{RESULT = BESSEL_JN(N, X)} 2286@item @code{RESULT = BESSEL_JN(N1, N2, X)} 2287@end multitable 2288 2289@item @emph{Arguments}: 2290@multitable @columnfractions .15 .70 2291@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}. 2292@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2293@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2294@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2295for @code{BESSEL_JN(N1, N2, X)} it shall be scalar. 2296@end multitable 2297 2298@item @emph{Return value}: 2299The return value is a scalar of type @code{REAL}. It has the same 2300kind as @var{X}. 2301 2302@item @emph{Note}: 2303The transformational function uses a recurrence algorithm which might, 2304for some values of @var{X}, lead to different results than calls to 2305the elemental function. 2306 2307@item @emph{Example}: 2308@smallexample 2309program test_besjn 2310 real(8) :: x = 1.0_8 2311 x = bessel_jn(5,x) 2312end program test_besjn 2313@end smallexample 2314 2315@item @emph{Specific names}: 2316@multitable @columnfractions .20 .20 .20 .25 2317@item Name @tab Argument @tab Return type @tab Standard 2318@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2319@item @tab @code{REAL(8) X} @tab @tab 2320@end multitable 2321@end table 2322 2323 2324 2325@node BESSEL_Y0 2326@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0 2327@fnindex BESSEL_Y0 2328@fnindex BESY0 2329@fnindex DBESY0 2330@cindex Bessel function, second kind 2331 2332@table @asis 2333@item @emph{Description}: 2334@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of 2335order 0 of @var{X}. This function is available under the name 2336@code{BESY0} as a GNU extension. 2337 2338@item @emph{Standard}: 2339Fortran 2008 and later 2340 2341@item @emph{Class}: 2342Elemental function 2343 2344@item @emph{Syntax}: 2345@code{RESULT = BESSEL_Y0(X)} 2346 2347@item @emph{Arguments}: 2348@multitable @columnfractions .15 .70 2349@item @var{X} @tab The type shall be @code{REAL}. 2350@end multitable 2351 2352@item @emph{Return value}: 2353The return value is of type @code{REAL}. It has the same kind as @var{X}. 2354 2355@item @emph{Example}: 2356@smallexample 2357program test_besy0 2358 real(8) :: x = 0.0_8 2359 x = bessel_y0(x) 2360end program test_besy0 2361@end smallexample 2362 2363@item @emph{Specific names}: 2364@multitable @columnfractions .20 .20 .20 .25 2365@item Name @tab Argument @tab Return type @tab Standard 2366@item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2367@end multitable 2368@end table 2369 2370 2371 2372@node BESSEL_Y1 2373@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1 2374@fnindex BESSEL_Y1 2375@fnindex BESY1 2376@fnindex DBESY1 2377@cindex Bessel function, second kind 2378 2379@table @asis 2380@item @emph{Description}: 2381@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of 2382order 1 of @var{X}. This function is available under the name 2383@code{BESY1} as a GNU extension. 2384 2385@item @emph{Standard}: 2386Fortran 2008 and later 2387 2388@item @emph{Class}: 2389Elemental function 2390 2391@item @emph{Syntax}: 2392@code{RESULT = BESSEL_Y1(X)} 2393 2394@item @emph{Arguments}: 2395@multitable @columnfractions .15 .70 2396@item @var{X} @tab The type shall be @code{REAL}. 2397@end multitable 2398 2399@item @emph{Return value}: 2400The return value is of type @code{REAL}. It has the same kind as @var{X}. 2401 2402@item @emph{Example}: 2403@smallexample 2404program test_besy1 2405 real(8) :: x = 1.0_8 2406 x = bessel_y1(x) 2407end program test_besy1 2408@end smallexample 2409 2410@item @emph{Specific names}: 2411@multitable @columnfractions .20 .20 .20 .25 2412@item Name @tab Argument @tab Return type @tab Standard 2413@item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 2414@end multitable 2415@end table 2416 2417 2418 2419@node BESSEL_YN 2420@section @code{BESSEL_YN} --- Bessel function of the second kind 2421@fnindex BESSEL_YN 2422@fnindex BESYN 2423@fnindex DBESYN 2424@cindex Bessel function, second kind 2425 2426@table @asis 2427@item @emph{Description}: 2428@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of 2429order @var{N} of @var{X}. This function is available under the name 2430@code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays, 2431their ranks and shapes shall conform. 2432 2433@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions 2434of the first kind of the orders @var{N1} to @var{N2}. 2435 2436@item @emph{Standard}: 2437Fortran 2008 and later, negative @var{N} is allowed as GNU extension 2438 2439@item @emph{Class}: 2440Elemental function, except for the transformational function 2441@code{BESSEL_YN(N1, N2, X)} 2442 2443@item @emph{Syntax}: 2444@multitable @columnfractions .80 2445@item @code{RESULT = BESSEL_YN(N, X)} 2446@item @code{RESULT = BESSEL_YN(N1, N2, X)} 2447@end multitable 2448 2449@item @emph{Arguments}: 2450@multitable @columnfractions .15 .70 2451@item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} . 2452@item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2453@item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. 2454@item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; 2455for @code{BESSEL_YN(N1, N2, X)} it shall be scalar. 2456@end multitable 2457 2458@item @emph{Return value}: 2459The return value is a scalar of type @code{REAL}. It has the same 2460kind as @var{X}. 2461 2462@item @emph{Note}: 2463The transformational function uses a recurrence algorithm which might, 2464for some values of @var{X}, lead to different results than calls to 2465the elemental function. 2466 2467@item @emph{Example}: 2468@smallexample 2469program test_besyn 2470 real(8) :: x = 1.0_8 2471 x = bessel_yn(5,x) 2472end program test_besyn 2473@end smallexample 2474 2475@item @emph{Specific names}: 2476@multitable @columnfractions .20 .20 .20 .25 2477@item Name @tab Argument @tab Return type @tab Standard 2478@item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension 2479@item @tab @code{REAL(8) X} @tab @tab 2480@end multitable 2481@end table 2482 2483 2484 2485@node BGE 2486@section @code{BGE} --- Bitwise greater than or equal to 2487@fnindex BGE 2488@cindex bitwise comparison 2489 2490@table @asis 2491@item @emph{Description}: 2492Determines whether an integral is a bitwise greater than or equal to 2493another. 2494 2495@item @emph{Standard}: 2496Fortran 2008 and later 2497 2498@item @emph{Class}: 2499Elemental function 2500 2501@item @emph{Syntax}: 2502@code{RESULT = BGE(I, J)} 2503 2504@item @emph{Arguments}: 2505@multitable @columnfractions .15 .70 2506@item @var{I} @tab Shall be of @code{INTEGER} type. 2507@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2508as @var{I}. 2509@end multitable 2510 2511@item @emph{Return value}: 2512The return value is of type @code{LOGICAL} and of the default kind. 2513 2514@item @emph{See also}: 2515@ref{BGT}, @ref{BLE}, @ref{BLT} 2516@end table 2517 2518 2519 2520@node BGT 2521@section @code{BGT} --- Bitwise greater than 2522@fnindex BGT 2523@cindex bitwise comparison 2524 2525@table @asis 2526@item @emph{Description}: 2527Determines whether an integral is a bitwise greater than another. 2528 2529@item @emph{Standard}: 2530Fortran 2008 and later 2531 2532@item @emph{Class}: 2533Elemental function 2534 2535@item @emph{Syntax}: 2536@code{RESULT = BGT(I, J)} 2537 2538@item @emph{Arguments}: 2539@multitable @columnfractions .15 .70 2540@item @var{I} @tab Shall be of @code{INTEGER} type. 2541@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2542as @var{I}. 2543@end multitable 2544 2545@item @emph{Return value}: 2546The return value is of type @code{LOGICAL} and of the default kind. 2547 2548@item @emph{See also}: 2549@ref{BGE}, @ref{BLE}, @ref{BLT} 2550@end table 2551 2552 2553 2554@node BIT_SIZE 2555@section @code{BIT_SIZE} --- Bit size inquiry function 2556@fnindex BIT_SIZE 2557@cindex bits, number of 2558@cindex size of a variable, in bits 2559 2560@table @asis 2561@item @emph{Description}: 2562@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) 2563represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is 2564independent of the actual value of @var{I}. 2565 2566@item @emph{Standard}: 2567Fortran 95 and later 2568 2569@item @emph{Class}: 2570Inquiry function 2571 2572@item @emph{Syntax}: 2573@code{RESULT = BIT_SIZE(I)} 2574 2575@item @emph{Arguments}: 2576@multitable @columnfractions .15 .70 2577@item @var{I} @tab The type shall be @code{INTEGER}. 2578@end multitable 2579 2580@item @emph{Return value}: 2581The return value is of type @code{INTEGER} 2582 2583@item @emph{Example}: 2584@smallexample 2585program test_bit_size 2586 integer :: i = 123 2587 integer :: size 2588 size = bit_size(i) 2589 print *, size 2590end program test_bit_size 2591@end smallexample 2592@end table 2593 2594 2595 2596@node BLE 2597@section @code{BLE} --- Bitwise less than or equal to 2598@fnindex BLE 2599@cindex bitwise comparison 2600 2601@table @asis 2602@item @emph{Description}: 2603Determines whether an integral is a bitwise less than or equal to 2604another. 2605 2606@item @emph{Standard}: 2607Fortran 2008 and later 2608 2609@item @emph{Class}: 2610Elemental function 2611 2612@item @emph{Syntax}: 2613@code{RESULT = BLE(I, J)} 2614 2615@item @emph{Arguments}: 2616@multitable @columnfractions .15 .70 2617@item @var{I} @tab Shall be of @code{INTEGER} type. 2618@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2619as @var{I}. 2620@end multitable 2621 2622@item @emph{Return value}: 2623The return value is of type @code{LOGICAL} and of the default kind. 2624 2625@item @emph{See also}: 2626@ref{BGT}, @ref{BGE}, @ref{BLT} 2627@end table 2628 2629 2630 2631@node BLT 2632@section @code{BLT} --- Bitwise less than 2633@fnindex BLT 2634@cindex bitwise comparison 2635 2636@table @asis 2637@item @emph{Description}: 2638Determines whether an integral is a bitwise less than another. 2639 2640@item @emph{Standard}: 2641Fortran 2008 and later 2642 2643@item @emph{Class}: 2644Elemental function 2645 2646@item @emph{Syntax}: 2647@code{RESULT = BLT(I, J)} 2648 2649@item @emph{Arguments}: 2650@multitable @columnfractions .15 .70 2651@item @var{I} @tab Shall be of @code{INTEGER} type. 2652@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind 2653as @var{I}. 2654@end multitable 2655 2656@item @emph{Return value}: 2657The return value is of type @code{LOGICAL} and of the default kind. 2658 2659@item @emph{See also}: 2660@ref{BGE}, @ref{BGT}, @ref{BLE} 2661@end table 2662 2663 2664 2665@node BTEST 2666@section @code{BTEST} --- Bit test function 2667@fnindex BTEST 2668@cindex bits, testing 2669 2670@table @asis 2671@item @emph{Description}: 2672@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} 2673in @var{I} is set. The counting of the bits starts at 0. 2674 2675@item @emph{Standard}: 2676Fortran 95 and later 2677 2678@item @emph{Class}: 2679Elemental function 2680 2681@item @emph{Syntax}: 2682@code{RESULT = BTEST(I, POS)} 2683 2684@item @emph{Arguments}: 2685@multitable @columnfractions .15 .70 2686@item @var{I} @tab The type shall be @code{INTEGER}. 2687@item @var{POS} @tab The type shall be @code{INTEGER}. 2688@end multitable 2689 2690@item @emph{Return value}: 2691The return value is of type @code{LOGICAL} 2692 2693@item @emph{Example}: 2694@smallexample 2695program test_btest 2696 integer :: i = 32768 + 1024 + 64 2697 integer :: pos 2698 logical :: bool 2699 do pos=0,16 2700 bool = btest(i, pos) 2701 print *, pos, bool 2702 end do 2703end program test_btest 2704@end smallexample 2705@end table 2706 2707 2708@node C_ASSOCIATED 2709@section @code{C_ASSOCIATED} --- Status of a C pointer 2710@fnindex C_ASSOCIATED 2711@cindex association status, C pointer 2712@cindex pointer, C association status 2713 2714@table @asis 2715@item @emph{Description}: 2716@code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer 2717@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}. 2718 2719@item @emph{Standard}: 2720Fortran 2003 and later 2721 2722@item @emph{Class}: 2723Inquiry function 2724 2725@item @emph{Syntax}: 2726@code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])} 2727 2728@item @emph{Arguments}: 2729@multitable @columnfractions .15 .70 2730@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}. 2731@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}. 2732@end multitable 2733 2734@item @emph{Return value}: 2735The return value is of type @code{LOGICAL}; it is @code{.false.} if either 2736@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2} 2737point to different addresses. 2738 2739@item @emph{Example}: 2740@smallexample 2741subroutine association_test(a,b) 2742 use iso_c_binding, only: c_associated, c_loc, c_ptr 2743 implicit none 2744 real, pointer :: a 2745 type(c_ptr) :: b 2746 if(c_associated(b, c_loc(a))) & 2747 stop 'b and a do not point to same target' 2748end subroutine association_test 2749@end smallexample 2750 2751@item @emph{See also}: 2752@ref{C_LOC}, @ref{C_FUNLOC} 2753@end table 2754 2755 2756@node C_F_POINTER 2757@section @code{C_F_POINTER} --- Convert C into Fortran pointer 2758@fnindex C_F_POINTER 2759@cindex pointer, convert C to Fortran 2760 2761@table @asis 2762@item @emph{Description}: 2763@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer 2764@var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape. 2765 2766@item @emph{Standard}: 2767Fortran 2003 and later 2768 2769@item @emph{Class}: 2770Subroutine 2771 2772@item @emph{Syntax}: 2773@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])} 2774 2775@item @emph{Arguments}: 2776@multitable @columnfractions .15 .70 2777@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is 2778@code{INTENT(IN)}. 2779@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is 2780@code{INTENT(OUT)}. 2781@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER} 2782with @code{INTENT(IN)}. It shall be present 2783if and only if @var{fptr} is an array. The size 2784must be equal to the rank of @var{fptr}. 2785@end multitable 2786 2787@item @emph{Example}: 2788@smallexample 2789program main 2790 use iso_c_binding 2791 implicit none 2792 interface 2793 subroutine my_routine(p) bind(c,name='myC_func') 2794 import :: c_ptr 2795 type(c_ptr), intent(out) :: p 2796 end subroutine 2797 end interface 2798 type(c_ptr) :: cptr 2799 real,pointer :: a(:) 2800 call my_routine(cptr) 2801 call c_f_pointer(cptr, a, [12]) 2802end program main 2803@end smallexample 2804 2805@item @emph{See also}: 2806@ref{C_LOC}, @ref{C_F_PROCPOINTER} 2807@end table 2808 2809 2810@node C_F_PROCPOINTER 2811@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer 2812@fnindex C_F_PROCPOINTER 2813@cindex pointer, C address of pointers 2814 2815@table @asis 2816@item @emph{Description}: 2817@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer 2818@var{CPTR} to the Fortran procedure pointer @var{FPTR}. 2819 2820@item @emph{Standard}: 2821Fortran 2003 and later 2822 2823@item @emph{Class}: 2824Subroutine 2825 2826@item @emph{Syntax}: 2827@code{CALL C_F_PROCPOINTER(cptr, fptr)} 2828 2829@item @emph{Arguments}: 2830@multitable @columnfractions .15 .70 2831@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is 2832@code{INTENT(IN)}. 2833@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is 2834@code{INTENT(OUT)}. 2835@end multitable 2836 2837@item @emph{Example}: 2838@smallexample 2839program main 2840 use iso_c_binding 2841 implicit none 2842 abstract interface 2843 function func(a) 2844 import :: c_float 2845 real(c_float), intent(in) :: a 2846 real(c_float) :: func 2847 end function 2848 end interface 2849 interface 2850 function getIterFunc() bind(c,name="getIterFunc") 2851 import :: c_funptr 2852 type(c_funptr) :: getIterFunc 2853 end function 2854 end interface 2855 type(c_funptr) :: cfunptr 2856 procedure(func), pointer :: myFunc 2857 cfunptr = getIterFunc() 2858 call c_f_procpointer(cfunptr, myFunc) 2859end program main 2860@end smallexample 2861 2862@item @emph{See also}: 2863@ref{C_LOC}, @ref{C_F_POINTER} 2864@end table 2865 2866 2867@node C_FUNLOC 2868@section @code{C_FUNLOC} --- Obtain the C address of a procedure 2869@fnindex C_FUNLOC 2870@cindex pointer, C address of procedures 2871 2872@table @asis 2873@item @emph{Description}: 2874@code{C_FUNLOC(x)} determines the C address of the argument. 2875 2876@item @emph{Standard}: 2877Fortran 2003 and later 2878 2879@item @emph{Class}: 2880Inquiry function 2881 2882@item @emph{Syntax}: 2883@code{RESULT = C_FUNLOC(x)} 2884 2885@item @emph{Arguments}: 2886@multitable @columnfractions .15 .70 2887@item @var{x} @tab Interoperable function or pointer to such function. 2888@end multitable 2889 2890@item @emph{Return value}: 2891The return value is of type @code{C_FUNPTR} and contains the C address 2892of the argument. 2893 2894@item @emph{Example}: 2895@smallexample 2896module x 2897 use iso_c_binding 2898 implicit none 2899contains 2900 subroutine sub(a) bind(c) 2901 real(c_float) :: a 2902 a = sqrt(a)+5.0 2903 end subroutine sub 2904end module x 2905program main 2906 use iso_c_binding 2907 use x 2908 implicit none 2909 interface 2910 subroutine my_routine(p) bind(c,name='myC_func') 2911 import :: c_funptr 2912 type(c_funptr), intent(in) :: p 2913 end subroutine 2914 end interface 2915 call my_routine(c_funloc(sub)) 2916end program main 2917@end smallexample 2918 2919@item @emph{See also}: 2920@ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} 2921@end table 2922 2923 2924@node C_LOC 2925@section @code{C_LOC} --- Obtain the C address of an object 2926@fnindex C_LOC 2927@cindex procedure pointer, convert C to Fortran 2928 2929@table @asis 2930@item @emph{Description}: 2931@code{C_LOC(X)} determines the C address of the argument. 2932 2933@item @emph{Standard}: 2934Fortran 2003 and later 2935 2936@item @emph{Class}: 2937Inquiry function 2938 2939@item @emph{Syntax}: 2940@code{RESULT = C_LOC(X)} 2941 2942@item @emph{Arguments}: 2943@multitable @columnfractions .10 .75 2944@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. 2945 2946@end multitable 2947 2948@item @emph{Return value}: 2949The return value is of type @code{C_PTR} and contains the C address 2950of the argument. 2951 2952@item @emph{Example}: 2953@smallexample 2954subroutine association_test(a,b) 2955 use iso_c_binding, only: c_associated, c_loc, c_ptr 2956 implicit none 2957 real, pointer :: a 2958 type(c_ptr) :: b 2959 if(c_associated(b, c_loc(a))) & 2960 stop 'b and a do not point to same target' 2961end subroutine association_test 2962@end smallexample 2963 2964@item @emph{See also}: 2965@ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} 2966@end table 2967 2968 2969@node C_SIZEOF 2970@section @code{C_SIZEOF} --- Size in bytes of an expression 2971@fnindex C_SIZEOF 2972@cindex expression size 2973@cindex size of an expression 2974 2975@table @asis 2976@item @emph{Description}: 2977@code{C_SIZEOF(X)} calculates the number of bytes of storage the 2978expression @code{X} occupies. 2979 2980@item @emph{Standard}: 2981Fortran 2008 2982 2983@item @emph{Class}: 2984Inquiry function of the module @code{ISO_C_BINDING} 2985 2986@item @emph{Syntax}: 2987@code{N = C_SIZEOF(X)} 2988 2989@item @emph{Arguments}: 2990@multitable @columnfractions .15 .70 2991@item @var{X} @tab The argument shall be an interoperable data entity. 2992@end multitable 2993 2994@item @emph{Return value}: 2995The return value is of type integer and of the system-dependent kind 2996@code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the 2997number of bytes occupied by the argument. If the argument has the 2998@code{POINTER} attribute, the number of bytes of the storage area pointed 2999to is returned. If the argument is of a derived type with @code{POINTER} 3000or @code{ALLOCATABLE} components, the return value does not account for 3001the sizes of the data pointed to by these components. 3002 3003@item @emph{Example}: 3004@smallexample 3005 use iso_c_binding 3006 integer(c_int) :: i 3007 real(c_float) :: r, s(5) 3008 print *, (c_sizeof(s)/c_sizeof(r) == 5) 3009 end 3010@end smallexample 3011The example will print @code{.TRUE.} unless you are using a platform 3012where default @code{REAL} variables are unusually padded. 3013 3014@item @emph{See also}: 3015@ref{SIZEOF}, @ref{STORAGE_SIZE} 3016@end table 3017 3018 3019@node CEILING 3020@section @code{CEILING} --- Integer ceiling function 3021@fnindex CEILING 3022@cindex ceiling 3023@cindex rounding, ceiling 3024 3025@table @asis 3026@item @emph{Description}: 3027@code{CEILING(A)} returns the least integer greater than or equal to @var{A}. 3028 3029@item @emph{Standard}: 3030Fortran 95 and later 3031 3032@item @emph{Class}: 3033Elemental function 3034 3035@item @emph{Syntax}: 3036@code{RESULT = CEILING(A [, KIND])} 3037 3038@item @emph{Arguments}: 3039@multitable @columnfractions .15 .70 3040@item @var{A} @tab The type shall be @code{REAL}. 3041@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3042expression indicating the kind parameter of the result. 3043@end multitable 3044 3045@item @emph{Return value}: 3046The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 3047and a default-kind @code{INTEGER} otherwise. 3048 3049@item @emph{Example}: 3050@smallexample 3051program test_ceiling 3052 real :: x = 63.29 3053 real :: y = -63.59 3054 print *, ceiling(x) ! returns 64 3055 print *, ceiling(y) ! returns -63 3056end program test_ceiling 3057@end smallexample 3058 3059@item @emph{See also}: 3060@ref{FLOOR}, @ref{NINT} 3061 3062@end table 3063 3064 3065 3066@node CHAR 3067@section @code{CHAR} --- Character conversion function 3068@fnindex CHAR 3069@cindex conversion, to character 3070 3071@table @asis 3072@item @emph{Description}: 3073@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}. 3074 3075@item @emph{Standard}: 3076Fortran 77 and later 3077 3078@item @emph{Class}: 3079Elemental function 3080 3081@item @emph{Syntax}: 3082@code{RESULT = CHAR(I [, KIND])} 3083 3084@item @emph{Arguments}: 3085@multitable @columnfractions .15 .70 3086@item @var{I} @tab The type shall be @code{INTEGER}. 3087@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3088expression indicating the kind parameter of the result. 3089@end multitable 3090 3091@item @emph{Return value}: 3092The return value is of type @code{CHARACTER(1)} 3093 3094@item @emph{Example}: 3095@smallexample 3096program test_char 3097 integer :: i = 74 3098 character(1) :: c 3099 c = char(i) 3100 print *, i, c ! returns 'J' 3101end program test_char 3102@end smallexample 3103 3104@item @emph{Specific names}: 3105@multitable @columnfractions .20 .20 .20 .25 3106@item Name @tab Argument @tab Return type @tab Standard 3107@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later 3108@end multitable 3109 3110@item @emph{Note}: 3111See @ref{ICHAR} for a discussion of converting between numerical values 3112and formatted string representations. 3113 3114@item @emph{See also}: 3115@ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR} 3116 3117@end table 3118 3119 3120 3121@node CHDIR 3122@section @code{CHDIR} --- Change working directory 3123@fnindex CHDIR 3124@cindex system, working directory 3125 3126@table @asis 3127@item @emph{Description}: 3128Change current working directory to a specified path. 3129 3130This intrinsic is provided in both subroutine and function forms; however, 3131only one form can be used in any given program unit. 3132 3133@item @emph{Standard}: 3134GNU extension 3135 3136@item @emph{Class}: 3137Subroutine, function 3138 3139@item @emph{Syntax}: 3140@multitable @columnfractions .80 3141@item @code{CALL CHDIR(NAME [, STATUS])} 3142@item @code{STATUS = CHDIR(NAME)} 3143@end multitable 3144 3145@item @emph{Arguments}: 3146@multitable @columnfractions .15 .70 3147@item @var{NAME} @tab The type shall be @code{CHARACTER} of default 3148kind and shall specify a valid path within the file system. 3149@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default 3150kind. Returns 0 on success, and a system specific and nonzero error code 3151otherwise. 3152@end multitable 3153 3154@item @emph{Example}: 3155@smallexample 3156PROGRAM test_chdir 3157 CHARACTER(len=255) :: path 3158 CALL getcwd(path) 3159 WRITE(*,*) TRIM(path) 3160 CALL chdir("/tmp") 3161 CALL getcwd(path) 3162 WRITE(*,*) TRIM(path) 3163END PROGRAM 3164@end smallexample 3165 3166@item @emph{See also}: 3167@ref{GETCWD} 3168@end table 3169 3170 3171 3172@node CHMOD 3173@section @code{CHMOD} --- Change access permissions of files 3174@fnindex CHMOD 3175@cindex file system, change access mode 3176 3177@table @asis 3178@item @emph{Description}: 3179@code{CHMOD} changes the permissions of a file. 3180 3181This intrinsic is provided in both subroutine and function forms; however, 3182only one form can be used in any given program unit. 3183 3184@item @emph{Standard}: 3185GNU extension 3186 3187@item @emph{Class}: 3188Subroutine, function 3189 3190@item @emph{Syntax}: 3191@multitable @columnfractions .80 3192@item @code{CALL CHMOD(NAME, MODE[, STATUS])} 3193@item @code{STATUS = CHMOD(NAME, MODE)} 3194@end multitable 3195 3196@item @emph{Arguments}: 3197@multitable @columnfractions .15 .70 3198 3199@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the 3200file name. Trailing blanks are ignored unless the character 3201@code{achar(0)} is present, then all characters up to and excluding 3202@code{achar(0)} are used as the file name. 3203 3204@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the 3205file permission. @var{MODE} uses the same syntax as the @code{chmod} utility 3206as defined by the POSIX standard. The argument shall either be a string of 3207a nonnegative octal number or a symbolic mode. 3208 3209@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is 3210@code{0} on success and nonzero otherwise. 3211@end multitable 3212 3213@item @emph{Return value}: 3214In either syntax, @var{STATUS} is set to @code{0} on success and nonzero 3215otherwise. 3216 3217@item @emph{Example}: 3218@code{CHMOD} as subroutine 3219@smallexample 3220program chmod_test 3221 implicit none 3222 integer :: status 3223 call chmod('test.dat','u+x',status) 3224 print *, 'Status: ', status 3225end program chmod_test 3226@end smallexample 3227@code{CHMOD} as function: 3228@smallexample 3229program chmod_test 3230 implicit none 3231 integer :: status 3232 status = chmod('test.dat','u+x') 3233 print *, 'Status: ', status 3234end program chmod_test 3235@end smallexample 3236 3237@end table 3238 3239 3240 3241@node CMPLX 3242@section @code{CMPLX} --- Complex conversion function 3243@fnindex CMPLX 3244@cindex complex numbers, conversion to 3245@cindex conversion, to complex 3246 3247@table @asis 3248@item @emph{Description}: 3249@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to 3250the real component. If @var{Y} is present it is converted to the imaginary 3251component. If @var{Y} is not present then the imaginary component is set to 32520.0. If @var{X} is complex then @var{Y} must not be present. 3253 3254@item @emph{Standard}: 3255Fortran 77 and later 3256 3257@item @emph{Class}: 3258Elemental function 3259 3260@item @emph{Syntax}: 3261@code{RESULT = CMPLX(X [, Y [, KIND]])} 3262 3263@item @emph{Arguments}: 3264@multitable @columnfractions .15 .70 3265@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 3266or @code{COMPLEX}. 3267@item @var{Y} @tab (Optional; only allowed if @var{X} is not 3268@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. 3269@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3270expression indicating the kind parameter of the result. 3271@end multitable 3272 3273@item @emph{Return value}: 3274The return value is of @code{COMPLEX} type, with a kind equal to 3275@var{KIND} if it is specified. If @var{KIND} is not specified, the 3276result is of the default @code{COMPLEX} kind, regardless of the kinds of 3277@var{X} and @var{Y}. 3278 3279@item @emph{Example}: 3280@smallexample 3281program test_cmplx 3282 integer :: i = 42 3283 real :: x = 3.14 3284 complex :: z 3285 z = cmplx(i, x) 3286 print *, z, cmplx(x) 3287end program test_cmplx 3288@end smallexample 3289 3290@item @emph{See also}: 3291@ref{COMPLEX} 3292@end table 3293 3294 3295 3296@node CO_BROADCAST 3297@section @code{CO_BROADCAST} --- Copy a value to all images the current set of images 3298@fnindex CO_BROADCAST 3299@cindex Collectives, value broadcasting 3300 3301@table @asis 3302@item @emph{Description}: 3303@code{CO_BROADCAST} copies the value of argument @var{A} on the image with 3304image index @code{SOURCE_IMAGE} to all images in the current team. @var{A} 3305becomes defined as if by intrinsic assignment. If the execution was 3306successful and @var{STAT} is present, it is assigned the value zero. If the 3307execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3308@var{ERRMSG} gets assigned a value describing the occurred error. 3309 3310@item @emph{Standard}: 3311Technical Specification (TS) 18508 or later 3312 3313@item @emph{Class}: 3314Collective subroutine 3315 3316@item @emph{Syntax}: 3317@code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])} 3318 3319@item @emph{Arguments}: 3320@multitable @columnfractions .15 .70 3321@item @var{A} @tab INTENT(INOUT) argument; shall have the same 3322dynamic type and type paramters on all images of the current team. If it 3323is an array, it shall have the same shape on all images. 3324@item @var{SOURCE_IMAGE} @tab a scalar integer expression. 3325It shall have the same the same value on all images and refer to an 3326image of the current team. 3327@item @var{STAT} @tab (optional) a scalar integer variable 3328@item @var{ERRMSG} @tab (optional) a scalar character variable 3329@end multitable 3330 3331@item @emph{Example}: 3332@smallexample 3333program test 3334 integer :: val(3) 3335 if (this_image() == 1) then 3336 val = [1, 5, 3] 3337 end if 3338 call co_broadcast (val, source_image=1) 3339 print *, this_image, ":", val 3340end program test 3341@end smallexample 3342 3343@item @emph{See also}: 3344@ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE} 3345@end table 3346 3347 3348 3349@node CO_MAX 3350@section @code{CO_MAX} --- Maximal value on the current set of images 3351@fnindex CO_MAX 3352@cindex Collectives, maximal value 3353 3354@table @asis 3355@item @emph{Description}: 3356@code{CO_MAX} determines element-wise the maximal value of @var{A} on all 3357images of the current team. If @var{RESULT_IMAGE} is present, the maximum 3358values are returned in @var{A} on the specified image only and the value 3359of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3360not present, the value is returned on all images. If the execution was 3361successful and @var{STAT} is present, it is assigned the value zero. If the 3362execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3363@var{ERRMSG} gets assigned a value describing the occurred error. 3364 3365@item @emph{Standard}: 3366Technical Specification (TS) 18508 or later 3367 3368@item @emph{Class}: 3369Collective subroutine 3370 3371@item @emph{Syntax}: 3372@code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])} 3373 3374@item @emph{Arguments}: 3375@multitable @columnfractions .15 .70 3376@item @var{A} @tab shall be an integer, real or character variable, 3377which has the same type and type parameters on all images of the team. 3378@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3379present, it shall have the same the same value on all images and refer to an 3380image of the current team. 3381@item @var{STAT} @tab (optional) a scalar integer variable 3382@item @var{ERRMSG} @tab (optional) a scalar character variable 3383@end multitable 3384 3385@item @emph{Example}: 3386@smallexample 3387program test 3388 integer :: val 3389 val = this_image () 3390 call co_max (val, result_image=1) 3391 if (this_image() == 1) then 3392 write(*,*) "Maximal value", val ! prints num_images() 3393 end if 3394end program test 3395@end smallexample 3396 3397@item @emph{See also}: 3398@ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3399@end table 3400 3401 3402 3403@node CO_MIN 3404@section @code{CO_MIN} --- Minimal value on the current set of images 3405@fnindex CO_MIN 3406@cindex Collectives, minimal value 3407 3408@table @asis 3409@item @emph{Description}: 3410@code{CO_MIN} determines element-wise the minimal value of @var{A} on all 3411images of the current team. If @var{RESULT_IMAGE} is present, the minimal 3412values are returned in @var{A} on the specified image only and the value 3413of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3414not present, the value is returned on all images. If the execution was 3415successful and @var{STAT} is present, it is assigned the value zero. If the 3416execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3417@var{ERRMSG} gets assigned a value describing the occurred error. 3418 3419@item @emph{Standard}: 3420Technical Specification (TS) 18508 or later 3421 3422@item @emph{Class}: 3423Collective subroutine 3424 3425@item @emph{Syntax}: 3426@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3427 3428@item @emph{Arguments}: 3429@multitable @columnfractions .15 .70 3430@item @var{A} @tab shall be an integer, real or character variable, 3431which has the same type and type parameters on all images of the team. 3432@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3433present, it shall have the same the same value on all images and refer to an 3434image of the current team. 3435@item @var{STAT} @tab (optional) a scalar integer variable 3436@item @var{ERRMSG} @tab (optional) a scalar character variable 3437@end multitable 3438 3439@item @emph{Example}: 3440@smallexample 3441program test 3442 integer :: val 3443 val = this_image () 3444 call co_min (val, result_image=1) 3445 if (this_image() == 1) then 3446 write(*,*) "Minimal value", val ! prints 1 3447 end if 3448end program test 3449@end smallexample 3450 3451@item @emph{See also}: 3452@ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3453@end table 3454 3455 3456 3457@node CO_REDUCE 3458@section @code{CO_REDUCE} --- Reduction of values on the current set of images 3459@fnindex CO_REDUCE 3460@cindex Collectives, generic reduction 3461 3462@table @asis 3463@item @emph{Description}: 3464@code{CO_REDUCE} determines element-wise the reduction of the value of @var{A} 3465on all images of the current team. The pure function passed as @var{OPERATOR} 3466is used to pairwise reduce the values of @var{A} by passing either the value 3467of @var{A} of different images or the result values of such a reduction as 3468argument. If @var{A} is an array, the deduction is done element wise. If 3469@var{RESULT_IMAGE} is present, the result values are returned in @var{A} on 3470the specified image only and the value of @var{A} on the other images become 3471undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all 3472images. If the execution was successful and @var{STAT} is present, it is 3473assigned the value zero. If the execution failed, @var{STAT} gets assigned 3474a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing 3475the occurred error. 3476 3477@item @emph{Standard}: 3478Technical Specification (TS) 18508 or later 3479 3480@item @emph{Class}: 3481Collective subroutine 3482 3483@item @emph{Syntax}: 3484@code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])} 3485 3486@item @emph{Arguments}: 3487@multitable @columnfractions .15 .70 3488@item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be 3489nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, 3490it shall be associated. @var{A} shall have the same type and type parameters on 3491all images of the team; if it is an array, it shall have the same shape on all 3492images. 3493@item @var{OPERATOR} @tab pure function with two scalar nonallocatable 3494arguments, which shall be nonpolymorphic and have the same type and type 3495parameters as @var{A}. The function shall return a nonallocatable scalar of 3496the same type and type parameters as @var{A}. The function shall be the same on 3497all images and with regards to the arguments mathematically commutative and 3498associative. Note that @var{OPERATOR} may not be an elemental function, unless 3499it is an intrisic function. 3500@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3501present, it shall have the same the same value on all images and refer to an 3502image of the current team. 3503@item @var{STAT} @tab (optional) a scalar integer variable 3504@item @var{ERRMSG} @tab (optional) a scalar character variable 3505@end multitable 3506 3507@item @emph{Example}: 3508@smallexample 3509program test 3510 integer :: val 3511 val = this_image () 3512 call co_reduce (val, result_image=1, operator=myprod) 3513 if (this_image() == 1) then 3514 write(*,*) "Product value", val ! prints num_images() factorial 3515 end if 3516contains 3517 pure function myprod(a, b) 3518 integer, value :: a, b 3519 integer :: myprod 3520 myprod = a * b 3521 end function myprod 3522end program test 3523@end smallexample 3524 3525@item @emph{Note}: 3526While the rules permit in principle an intrinsic function, none of the 3527intrinsics in the standard fulfill the criteria of having a specific 3528function, which takes two arguments of the same type and returning that 3529type as result. 3530 3531@item @emph{See also}: 3532@ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST} 3533@end table 3534 3535 3536 3537@node CO_SUM 3538@section @code{CO_SUM} --- Sum of values on the current set of images 3539@fnindex CO_SUM 3540@cindex Collectives, sum of values 3541 3542@table @asis 3543@item @emph{Description}: 3544@code{CO_SUM} sums up the values of each element of @var{A} on all 3545images of the current team. If @var{RESULT_IMAGE} is present, the summed-up 3546values are returned in @var{A} on the specified image only and the value 3547of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is 3548not present, the value is returned on all images. If the execution was 3549successful and @var{STAT} is present, it is assigned the value zero. If the 3550execution failed, @var{STAT} gets assigned a nonzero value and, if present, 3551@var{ERRMSG} gets assigned a value describing the occurred error. 3552 3553@item @emph{Standard}: 3554Technical Specification (TS) 18508 or later 3555 3556@item @emph{Class}: 3557Collective subroutine 3558 3559@item @emph{Syntax}: 3560@code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} 3561 3562@item @emph{Arguments}: 3563@multitable @columnfractions .15 .70 3564@item @var{A} @tab shall be an integer, real or complex variable, 3565which has the same type and type parameters on all images of the team. 3566@item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if 3567present, it shall have the same the same value on all images and refer to an 3568image of the current team. 3569@item @var{STAT} @tab (optional) a scalar integer variable 3570@item @var{ERRMSG} @tab (optional) a scalar character variable 3571@end multitable 3572 3573@item @emph{Example}: 3574@smallexample 3575program test 3576 integer :: val 3577 val = this_image () 3578 call co_sum (val, result_image=1) 3579 if (this_image() == 1) then 3580 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images() 3581 end if 3582end program test 3583@end smallexample 3584 3585@item @emph{See also}: 3586@ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} 3587@end table 3588 3589 3590 3591@node COMMAND_ARGUMENT_COUNT 3592@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments 3593@fnindex COMMAND_ARGUMENT_COUNT 3594@cindex command-line arguments 3595@cindex command-line arguments, number of 3596@cindex arguments, to program 3597 3598@table @asis 3599@item @emph{Description}: 3600@code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the 3601command line when the containing program was invoked. 3602 3603@item @emph{Standard}: 3604Fortran 2003 and later 3605 3606@item @emph{Class}: 3607Inquiry function 3608 3609@item @emph{Syntax}: 3610@code{RESULT = COMMAND_ARGUMENT_COUNT()} 3611 3612@item @emph{Arguments}: 3613@multitable @columnfractions .15 .70 3614@item None 3615@end multitable 3616 3617@item @emph{Return value}: 3618The return value is an @code{INTEGER} of default kind. 3619 3620@item @emph{Example}: 3621@smallexample 3622program test_command_argument_count 3623 integer :: count 3624 count = command_argument_count() 3625 print *, count 3626end program test_command_argument_count 3627@end smallexample 3628 3629@item @emph{See also}: 3630@ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT} 3631@end table 3632 3633 3634 3635@node COMPILER_OPTIONS 3636@section @code{COMPILER_OPTIONS} --- Options passed to the compiler 3637@fnindex COMPILER_OPTIONS 3638@cindex flags inquiry function 3639@cindex options inquiry function 3640@cindex compiler flags inquiry function 3641 3642@table @asis 3643@item @emph{Description}: 3644@code{COMPILER_OPTIONS} returns a string with the options used for 3645compiling. 3646 3647@item @emph{Standard}: 3648Fortran 2008 3649 3650@item @emph{Class}: 3651Inquiry function of the module @code{ISO_FORTRAN_ENV} 3652 3653@item @emph{Syntax}: 3654@code{STR = COMPILER_OPTIONS()} 3655 3656@item @emph{Arguments}: 3657None. 3658 3659@item @emph{Return value}: 3660The return value is a default-kind string with system-dependent length. 3661It contains the compiler flags used to compile the file, which called 3662the @code{COMPILER_OPTIONS} intrinsic. 3663 3664@item @emph{Example}: 3665@smallexample 3666 use iso_fortran_env 3667 print '(4a)', 'This file was compiled by ', & 3668 compiler_version(), ' using the options ', & 3669 compiler_options() 3670 end 3671@end smallexample 3672 3673@item @emph{See also}: 3674@ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV} 3675@end table 3676 3677 3678 3679@node COMPILER_VERSION 3680@section @code{COMPILER_VERSION} --- Compiler version string 3681@fnindex COMPILER_VERSION 3682@cindex compiler, name and version 3683@cindex version of the compiler 3684 3685@table @asis 3686@item @emph{Description}: 3687@code{COMPILER_VERSION} returns a string with the name and the 3688version of the compiler. 3689 3690@item @emph{Standard}: 3691Fortran 2008 3692 3693@item @emph{Class}: 3694Inquiry function of the module @code{ISO_FORTRAN_ENV} 3695 3696@item @emph{Syntax}: 3697@code{STR = COMPILER_VERSION()} 3698 3699@item @emph{Arguments}: 3700None. 3701 3702@item @emph{Return value}: 3703The return value is a default-kind string with system-dependent length. 3704It contains the name of the compiler and its version number. 3705 3706@item @emph{Example}: 3707@smallexample 3708 use iso_fortran_env 3709 print '(4a)', 'This file was compiled by ', & 3710 compiler_version(), ' using the options ', & 3711 compiler_options() 3712 end 3713@end smallexample 3714 3715@item @emph{See also}: 3716@ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV} 3717@end table 3718 3719 3720 3721@node COMPLEX 3722@section @code{COMPLEX} --- Complex conversion function 3723@fnindex COMPLEX 3724@cindex complex numbers, conversion to 3725@cindex conversion, to complex 3726 3727@table @asis 3728@item @emph{Description}: 3729@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted 3730to the real component and @var{Y} is converted to the imaginary 3731component. 3732 3733@item @emph{Standard}: 3734GNU extension 3735 3736@item @emph{Class}: 3737Elemental function 3738 3739@item @emph{Syntax}: 3740@code{RESULT = COMPLEX(X, Y)} 3741 3742@item @emph{Arguments}: 3743@multitable @columnfractions .15 .70 3744@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 3745@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}. 3746@end multitable 3747 3748@item @emph{Return value}: 3749If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return 3750value is of default @code{COMPLEX} type. 3751 3752If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL} 3753type and one is of @code{INTEGER} type, then the return value is of 3754@code{COMPLEX} type with a kind equal to that of the @code{REAL} 3755argument with the highest precision. 3756 3757@item @emph{Example}: 3758@smallexample 3759program test_complex 3760 integer :: i = 42 3761 real :: x = 3.14 3762 print *, complex(i, x) 3763end program test_complex 3764@end smallexample 3765 3766@item @emph{See also}: 3767@ref{CMPLX} 3768@end table 3769 3770 3771 3772@node CONJG 3773@section @code{CONJG} --- Complex conjugate function 3774@fnindex CONJG 3775@fnindex DCONJG 3776@cindex complex conjugate 3777 3778@table @asis 3779@item @emph{Description}: 3780@code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)} 3781then the result is @code{(x, -y)} 3782 3783@item @emph{Standard}: 3784Fortran 77 and later, has overloads that are GNU extensions 3785 3786@item @emph{Class}: 3787Elemental function 3788 3789@item @emph{Syntax}: 3790@code{Z = CONJG(Z)} 3791 3792@item @emph{Arguments}: 3793@multitable @columnfractions .15 .70 3794@item @var{Z} @tab The type shall be @code{COMPLEX}. 3795@end multitable 3796 3797@item @emph{Return value}: 3798The return value is of type @code{COMPLEX}. 3799 3800@item @emph{Example}: 3801@smallexample 3802program test_conjg 3803 complex :: z = (2.0, 3.0) 3804 complex(8) :: dz = (2.71_8, -3.14_8) 3805 z= conjg(z) 3806 print *, z 3807 dz = dconjg(dz) 3808 print *, dz 3809end program test_conjg 3810@end smallexample 3811 3812@item @emph{Specific names}: 3813@multitable @columnfractions .20 .20 .20 .25 3814@item Name @tab Argument @tab Return type @tab Standard 3815@item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension 3816@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension 3817@end multitable 3818@end table 3819 3820 3821 3822@node COS 3823@section @code{COS} --- Cosine function 3824@fnindex COS 3825@fnindex DCOS 3826@fnindex CCOS 3827@fnindex ZCOS 3828@fnindex CDCOS 3829@cindex trigonometric function, cosine 3830@cindex cosine 3831 3832@table @asis 3833@item @emph{Description}: 3834@code{COS(X)} computes the cosine of @var{X}. 3835 3836@item @emph{Standard}: 3837Fortran 77 and later, has overloads that are GNU extensions 3838 3839@item @emph{Class}: 3840Elemental function 3841 3842@item @emph{Syntax}: 3843@code{RESULT = COS(X)} 3844 3845@item @emph{Arguments}: 3846@multitable @columnfractions .15 .70 3847@item @var{X} @tab The type shall be @code{REAL} or 3848@code{COMPLEX}. 3849@end multitable 3850 3851@item @emph{Return value}: 3852The return value is of the same type and kind as @var{X}. The real part 3853of the result is in radians. If @var{X} is of the type @code{REAL}, 3854the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}. 3855 3856@item @emph{Example}: 3857@smallexample 3858program test_cos 3859 real :: x = 0.0 3860 x = cos(x) 3861end program test_cos 3862@end smallexample 3863 3864@item @emph{Specific names}: 3865@multitable @columnfractions .20 .20 .20 .25 3866@item Name @tab Argument @tab Return type @tab Standard 3867@item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 3868@item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 3869@item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 3870@item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 3871@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 3872@end multitable 3873 3874@item @emph{See also}: 3875Inverse function: @ref{ACOS} 3876 3877@end table 3878 3879 3880 3881@node COSH 3882@section @code{COSH} --- Hyperbolic cosine function 3883@fnindex COSH 3884@fnindex DCOSH 3885@cindex hyperbolic cosine 3886@cindex hyperbolic function, cosine 3887@cindex cosine, hyperbolic 3888 3889@table @asis 3890@item @emph{Description}: 3891@code{COSH(X)} computes the hyperbolic cosine of @var{X}. 3892 3893@item @emph{Standard}: 3894Fortran 77 and later, for a complex argument Fortran 2008 or later 3895 3896@item @emph{Class}: 3897Elemental function 3898 3899@item @emph{Syntax}: 3900@code{X = COSH(X)} 3901 3902@item @emph{Arguments}: 3903@multitable @columnfractions .15 .70 3904@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 3905@end multitable 3906 3907@item @emph{Return value}: 3908The return value has same type and kind as @var{X}. If @var{X} is 3909complex, the imaginary part of the result is in radians. If @var{X} 3910is @code{REAL}, the return value has a lower bound of one, 3911@math{\cosh (x) \geq 1}. 3912 3913@item @emph{Example}: 3914@smallexample 3915program test_cosh 3916 real(8) :: x = 1.0_8 3917 x = cosh(x) 3918end program test_cosh 3919@end smallexample 3920 3921@item @emph{Specific names}: 3922@multitable @columnfractions .20 .20 .20 .25 3923@item Name @tab Argument @tab Return type @tab Standard 3924@item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 3925@item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 3926@end multitable 3927 3928@item @emph{See also}: 3929Inverse function: @ref{ACOSH} 3930 3931@end table 3932 3933 3934 3935@node COUNT 3936@section @code{COUNT} --- Count function 3937@fnindex COUNT 3938@cindex array, conditionally count elements 3939@cindex array, element counting 3940@cindex array, number of elements 3941 3942@table @asis 3943@item @emph{Description}: 3944 3945Counts the number of @code{.TRUE.} elements in a logical @var{MASK}, 3946or, if the @var{DIM} argument is supplied, counts the number of 3947elements along each row of the array in the @var{DIM} direction. 3948If the array has zero size, or all of the elements of @var{MASK} are 3949@code{.FALSE.}, then the result is @code{0}. 3950 3951@item @emph{Standard}: 3952Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 3953 3954@item @emph{Class}: 3955Transformational function 3956 3957@item @emph{Syntax}: 3958@code{RESULT = COUNT(MASK [, DIM, KIND])} 3959 3960@item @emph{Arguments}: 3961@multitable @columnfractions .15 .70 3962@item @var{MASK} @tab The type shall be @code{LOGICAL}. 3963@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}. 3964@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 3965expression indicating the kind parameter of the result. 3966@end multitable 3967 3968@item @emph{Return value}: 3969The return value is of type @code{INTEGER} and of kind @var{KIND}. If 3970@var{KIND} is absent, the return value is of default integer kind. 3971If @var{DIM} is present, the result is an array with a rank one less 3972than the rank of @var{ARRAY}, and a size corresponding to the shape 3973of @var{ARRAY} with the @var{DIM} dimension removed. 3974 3975@item @emph{Example}: 3976@smallexample 3977program test_count 3978 integer, dimension(2,3) :: a, b 3979 logical, dimension(2,3) :: mask 3980 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) 3981 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /)) 3982 print '(3i3)', a(1,:) 3983 print '(3i3)', a(2,:) 3984 print * 3985 print '(3i3)', b(1,:) 3986 print '(3i3)', b(2,:) 3987 print * 3988 mask = a.ne.b 3989 print '(3l3)', mask(1,:) 3990 print '(3l3)', mask(2,:) 3991 print * 3992 print '(3i3)', count(mask) 3993 print * 3994 print '(3i3)', count(mask, 1) 3995 print * 3996 print '(3i3)', count(mask, 2) 3997end program test_count 3998@end smallexample 3999@end table 4000 4001 4002 4003@node CPU_TIME 4004@section @code{CPU_TIME} --- CPU elapsed time in seconds 4005@fnindex CPU_TIME 4006@cindex time, elapsed 4007 4008@table @asis 4009@item @emph{Description}: 4010Returns a @code{REAL} value representing the elapsed CPU time in 4011seconds. This is useful for testing segments of code to determine 4012execution time. 4013 4014If a time source is available, time will be reported with microsecond 4015resolution. If no time source is available, @var{TIME} is set to 4016@code{-1.0}. 4017 4018Note that @var{TIME} may contain a, system dependent, arbitrary offset 4019and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute 4020value is meaningless, only differences between subsequent calls to 4021this subroutine, as shown in the example below, should be used. 4022 4023 4024@item @emph{Standard}: 4025Fortran 95 and later 4026 4027@item @emph{Class}: 4028Subroutine 4029 4030@item @emph{Syntax}: 4031@code{CALL CPU_TIME(TIME)} 4032 4033@item @emph{Arguments}: 4034@multitable @columnfractions .15 .70 4035@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}. 4036@end multitable 4037 4038@item @emph{Return value}: 4039None 4040 4041@item @emph{Example}: 4042@smallexample 4043program test_cpu_time 4044 real :: start, finish 4045 call cpu_time(start) 4046 ! put code to test here 4047 call cpu_time(finish) 4048 print '("Time = ",f6.3," seconds.")',finish-start 4049end program test_cpu_time 4050@end smallexample 4051 4052@item @emph{See also}: 4053@ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME} 4054@end table 4055 4056 4057 4058@node CSHIFT 4059@section @code{CSHIFT} --- Circular shift elements of an array 4060@fnindex CSHIFT 4061@cindex array, shift circularly 4062@cindex array, permutation 4063@cindex array, rotate 4064 4065@table @asis 4066@item @emph{Description}: 4067@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of 4068@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is 4069taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the 4070range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. 4071If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted 4072by @var{SHIFT} places. If rank is greater than one, then all complete rank one 4073sections of @var{ARRAY} along the given dimension are shifted. Elements 4074shifted out one end of each rank one section are shifted back in the other end. 4075 4076@item @emph{Standard}: 4077Fortran 95 and later 4078 4079@item @emph{Class}: 4080Transformational function 4081 4082@item @emph{Syntax}: 4083@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])} 4084 4085@item @emph{Arguments}: 4086@multitable @columnfractions .15 .70 4087@item @var{ARRAY} @tab Shall be an array of any type. 4088@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 4089@item @var{DIM} @tab The type shall be @code{INTEGER}. 4090@end multitable 4091 4092@item @emph{Return value}: 4093Returns an array of same type and rank as the @var{ARRAY} argument. 4094 4095@item @emph{Example}: 4096@smallexample 4097program test_cshift 4098 integer, dimension(3,3) :: a 4099 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 4100 print '(3i3)', a(1,:) 4101 print '(3i3)', a(2,:) 4102 print '(3i3)', a(3,:) 4103 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2) 4104 print * 4105 print '(3i3)', a(1,:) 4106 print '(3i3)', a(2,:) 4107 print '(3i3)', a(3,:) 4108end program test_cshift 4109@end smallexample 4110@end table 4111 4112 4113 4114@node CTIME 4115@section @code{CTIME} --- Convert a time into a string 4116@fnindex CTIME 4117@cindex time, conversion to string 4118@cindex conversion, to string 4119 4120@table @asis 4121@item @emph{Description}: 4122@code{CTIME} converts a system time value, such as returned by 4123@code{TIME8}, to a string. The output will be of the form @samp{Sat 4124Aug 19 18:13:14 1995}. 4125 4126This intrinsic is provided in both subroutine and function forms; however, 4127only one form can be used in any given program unit. 4128 4129@item @emph{Standard}: 4130GNU extension 4131 4132@item @emph{Class}: 4133Subroutine, function 4134 4135@item @emph{Syntax}: 4136@multitable @columnfractions .80 4137@item @code{CALL CTIME(TIME, RESULT)}. 4138@item @code{RESULT = CTIME(TIME)}. 4139@end multitable 4140 4141@item @emph{Arguments}: 4142@multitable @columnfractions .15 .70 4143@item @var{TIME} @tab The type shall be of type @code{INTEGER}. 4144@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and 4145of default kind. It is an @code{INTENT(OUT)} argument. If the length 4146of this variable is too short for the time and date string to fit 4147completely, it will be blank on procedure return. 4148@end multitable 4149 4150@item @emph{Return value}: 4151The converted date and time as a string. 4152 4153@item @emph{Example}: 4154@smallexample 4155program test_ctime 4156 integer(8) :: i 4157 character(len=30) :: date 4158 i = time8() 4159 4160 ! Do something, main part of the program 4161 4162 call ctime(i,date) 4163 print *, 'Program was started on ', date 4164end program test_ctime 4165@end smallexample 4166 4167@item @emph{See Also}: 4168@ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} 4169@end table 4170 4171 4172 4173@node DATE_AND_TIME 4174@section @code{DATE_AND_TIME} --- Date and time subroutine 4175@fnindex DATE_AND_TIME 4176@cindex date, current 4177@cindex current date 4178@cindex time, current 4179@cindex current time 4180 4181@table @asis 4182@item @emph{Description}: 4183@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and 4184time information from the real-time system clock. @var{DATE} is 4185@code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and 4186has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, 4187representing the difference with respect to Coordinated Universal Time (UTC). 4188Unavailable time and date parameters return blanks. 4189 4190@var{VALUES} is @code{INTENT(OUT)} and provides the following: 4191 4192@multitable @columnfractions .15 .30 .40 4193@item @tab @code{VALUE(1)}: @tab The year 4194@item @tab @code{VALUE(2)}: @tab The month 4195@item @tab @code{VALUE(3)}: @tab The day of the month 4196@item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes 4197@item @tab @code{VALUE(5)}: @tab The hour of the day 4198@item @tab @code{VALUE(6)}: @tab The minutes of the hour 4199@item @tab @code{VALUE(7)}: @tab The seconds of the minute 4200@item @tab @code{VALUE(8)}: @tab The milliseconds of the second 4201@end multitable 4202 4203@item @emph{Standard}: 4204Fortran 95 and later 4205 4206@item @emph{Class}: 4207Subroutine 4208 4209@item @emph{Syntax}: 4210@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])} 4211 4212@item @emph{Arguments}: 4213@multitable @columnfractions .15 .70 4214@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)} 4215or larger, and of default kind. 4216@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)} 4217or larger, and of default kind. 4218@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)} 4219or larger, and of default kind. 4220@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}. 4221@end multitable 4222 4223@item @emph{Return value}: 4224None 4225 4226@item @emph{Example}: 4227@smallexample 4228program test_time_and_date 4229 character(8) :: date 4230 character(10) :: time 4231 character(5) :: zone 4232 integer,dimension(8) :: values 4233 ! using keyword arguments 4234 call date_and_time(date,time,zone,values) 4235 call date_and_time(DATE=date,ZONE=zone) 4236 call date_and_time(TIME=time) 4237 call date_and_time(VALUES=values) 4238 print '(a,2x,a,2x,a)', date, time, zone 4239 print '(8i5)', values 4240end program test_time_and_date 4241@end smallexample 4242 4243@item @emph{See also}: 4244@ref{CPU_TIME}, @ref{SYSTEM_CLOCK} 4245@end table 4246 4247 4248 4249@node DBLE 4250@section @code{DBLE} --- Double conversion function 4251@fnindex DBLE 4252@cindex conversion, to real 4253 4254@table @asis 4255@item @emph{Description}: 4256@code{DBLE(A)} Converts @var{A} to double precision real type. 4257 4258@item @emph{Standard}: 4259Fortran 77 and later 4260 4261@item @emph{Class}: 4262Elemental function 4263 4264@item @emph{Syntax}: 4265@code{RESULT = DBLE(A)} 4266 4267@item @emph{Arguments}: 4268@multitable @columnfractions .15 .70 4269@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL}, 4270or @code{COMPLEX}. 4271@end multitable 4272 4273@item @emph{Return value}: 4274The return value is of type double precision real. 4275 4276@item @emph{Example}: 4277@smallexample 4278program test_dble 4279 real :: x = 2.18 4280 integer :: i = 5 4281 complex :: z = (2.3,1.14) 4282 print *, dble(x), dble(i), dble(z) 4283end program test_dble 4284@end smallexample 4285 4286@item @emph{See also}: 4287@ref{REAL} 4288@end table 4289 4290 4291 4292@node DCMPLX 4293@section @code{DCMPLX} --- Double complex conversion function 4294@fnindex DCMPLX 4295@cindex complex numbers, conversion to 4296@cindex conversion, to complex 4297 4298@table @asis 4299@item @emph{Description}: 4300@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is 4301converted to the real component. If @var{Y} is present it is converted to the 4302imaginary component. If @var{Y} is not present then the imaginary component is 4303set to 0.0. If @var{X} is complex then @var{Y} must not be present. 4304 4305@item @emph{Standard}: 4306GNU extension 4307 4308@item @emph{Class}: 4309Elemental function 4310 4311@item @emph{Syntax}: 4312@code{RESULT = DCMPLX(X [, Y])} 4313 4314@item @emph{Arguments}: 4315@multitable @columnfractions .15 .70 4316@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, 4317or @code{COMPLEX}. 4318@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be 4319@code{INTEGER} or @code{REAL}. 4320@end multitable 4321 4322@item @emph{Return value}: 4323The return value is of type @code{COMPLEX(8)} 4324 4325@item @emph{Example}: 4326@smallexample 4327program test_dcmplx 4328 integer :: i = 42 4329 real :: x = 3.14 4330 complex :: z 4331 z = cmplx(i, x) 4332 print *, dcmplx(i) 4333 print *, dcmplx(x) 4334 print *, dcmplx(z) 4335 print *, dcmplx(x,i) 4336end program test_dcmplx 4337@end smallexample 4338@end table 4339 4340 4341@node DIGITS 4342@section @code{DIGITS} --- Significant binary digits function 4343@fnindex DIGITS 4344@cindex model representation, significant digits 4345 4346@table @asis 4347@item @emph{Description}: 4348@code{DIGITS(X)} returns the number of significant binary digits of the internal 4349model representation of @var{X}. For example, on a system using a 32-bit 4350floating point representation, a default real number would likely return 24. 4351 4352@item @emph{Standard}: 4353Fortran 95 and later 4354 4355@item @emph{Class}: 4356Inquiry function 4357 4358@item @emph{Syntax}: 4359@code{RESULT = DIGITS(X)} 4360 4361@item @emph{Arguments}: 4362@multitable @columnfractions .15 .70 4363@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. 4364@end multitable 4365 4366@item @emph{Return value}: 4367The return value is of type @code{INTEGER}. 4368 4369@item @emph{Example}: 4370@smallexample 4371program test_digits 4372 integer :: i = 12345 4373 real :: x = 3.143 4374 real(8) :: y = 2.33 4375 print *, digits(i) 4376 print *, digits(x) 4377 print *, digits(y) 4378end program test_digits 4379@end smallexample 4380@end table 4381 4382 4383 4384@node DIM 4385@section @code{DIM} --- Positive difference 4386@fnindex DIM 4387@fnindex IDIM 4388@fnindex DDIM 4389@cindex positive difference 4390 4391@table @asis 4392@item @emph{Description}: 4393@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive; 4394otherwise returns zero. 4395 4396@item @emph{Standard}: 4397Fortran 77 and later 4398 4399@item @emph{Class}: 4400Elemental function 4401 4402@item @emph{Syntax}: 4403@code{RESULT = DIM(X, Y)} 4404 4405@item @emph{Arguments}: 4406@multitable @columnfractions .15 .70 4407@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL} 4408@item @var{Y} @tab The type shall be the same type and kind as @var{X}. 4409@end multitable 4410 4411@item @emph{Return value}: 4412The return value is of type @code{INTEGER} or @code{REAL}. 4413 4414@item @emph{Example}: 4415@smallexample 4416program test_dim 4417 integer :: i 4418 real(8) :: x 4419 i = dim(4, 15) 4420 x = dim(4.345_8, 2.111_8) 4421 print *, i 4422 print *, x 4423end program test_dim 4424@end smallexample 4425 4426@item @emph{Specific names}: 4427@multitable @columnfractions .20 .20 .20 .25 4428@item Name @tab Argument @tab Return type @tab Standard 4429@item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later 4430@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later 4431@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 4432@end multitable 4433@end table 4434 4435 4436 4437@node DOT_PRODUCT 4438@section @code{DOT_PRODUCT} --- Dot product function 4439@fnindex DOT_PRODUCT 4440@cindex dot product 4441@cindex vector product 4442@cindex product, vector 4443 4444@table @asis 4445@item @emph{Description}: 4446@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication 4447of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be 4448either numeric or logical and must be arrays of rank one and of equal size. If 4449the vectors are @code{INTEGER} or @code{REAL}, the result is 4450@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result 4451is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL}, 4452the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}. 4453 4454@item @emph{Standard}: 4455Fortran 95 and later 4456 4457@item @emph{Class}: 4458Transformational function 4459 4460@item @emph{Syntax}: 4461@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)} 4462 4463@item @emph{Arguments}: 4464@multitable @columnfractions .15 .70 4465@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1. 4466@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. 4467@end multitable 4468 4469@item @emph{Return value}: 4470If the arguments are numeric, the return value is a scalar of numeric type, 4471@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are 4472@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}. 4473 4474@item @emph{Example}: 4475@smallexample 4476program test_dot_prod 4477 integer, dimension(3) :: a, b 4478 a = (/ 1, 2, 3 /) 4479 b = (/ 4, 5, 6 /) 4480 print '(3i3)', a 4481 print * 4482 print '(3i3)', b 4483 print * 4484 print *, dot_product(a,b) 4485end program test_dot_prod 4486@end smallexample 4487@end table 4488 4489 4490 4491@node DPROD 4492@section @code{DPROD} --- Double product function 4493@fnindex DPROD 4494@cindex product, double-precision 4495 4496@table @asis 4497@item @emph{Description}: 4498@code{DPROD(X,Y)} returns the product @code{X*Y}. 4499 4500@item @emph{Standard}: 4501Fortran 77 and later 4502 4503@item @emph{Class}: 4504Elemental function 4505 4506@item @emph{Syntax}: 4507@code{RESULT = DPROD(X, Y)} 4508 4509@item @emph{Arguments}: 4510@multitable @columnfractions .15 .70 4511@item @var{X} @tab The type shall be @code{REAL}. 4512@item @var{Y} @tab The type shall be @code{REAL}. 4513@end multitable 4514 4515@item @emph{Return value}: 4516The return value is of type @code{REAL(8)}. 4517 4518@item @emph{Example}: 4519@smallexample 4520program test_dprod 4521 real :: x = 5.2 4522 real :: y = 2.3 4523 real(8) :: d 4524 d = dprod(x,y) 4525 print *, d 4526end program test_dprod 4527@end smallexample 4528 4529@item @emph{Specific names}: 4530@multitable @columnfractions .20 .20 .20 .25 4531@item Name @tab Argument @tab Return type @tab Standard 4532@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later 4533@end multitable 4534 4535@end table 4536 4537 4538@node DREAL 4539@section @code{DREAL} --- Double real part function 4540@fnindex DREAL 4541@cindex complex numbers, real part 4542 4543@table @asis 4544@item @emph{Description}: 4545@code{DREAL(Z)} returns the real part of complex variable @var{Z}. 4546 4547@item @emph{Standard}: 4548GNU extension 4549 4550@item @emph{Class}: 4551Elemental function 4552 4553@item @emph{Syntax}: 4554@code{RESULT = DREAL(A)} 4555 4556@item @emph{Arguments}: 4557@multitable @columnfractions .15 .70 4558@item @var{A} @tab The type shall be @code{COMPLEX(8)}. 4559@end multitable 4560 4561@item @emph{Return value}: 4562The return value is of type @code{REAL(8)}. 4563 4564@item @emph{Example}: 4565@smallexample 4566program test_dreal 4567 complex(8) :: z = (1.3_8,7.2_8) 4568 print *, dreal(z) 4569end program test_dreal 4570@end smallexample 4571 4572@item @emph{See also}: 4573@ref{AIMAG} 4574 4575@end table 4576 4577 4578 4579@node DSHIFTL 4580@section @code{DSHIFTL} --- Combined left shift 4581@fnindex DSHIFTL 4582@cindex left shift, combined 4583@cindex shift, left 4584 4585@table @asis 4586@item @emph{Description}: 4587@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 4588rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT} 4589bits of @var{J}, and the remaining bits are the rightmost bits of 4590@var{I}. 4591 4592@item @emph{Standard}: 4593Fortran 2008 and later 4594 4595@item @emph{Class}: 4596Elemental function 4597 4598@item @emph{Syntax}: 4599@code{RESULT = DSHIFTL(I, J, SHIFT)} 4600 4601@item @emph{Arguments}: 4602@multitable @columnfractions .15 .70 4603@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 4604@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 4605If both @var{I} and @var{J} have integer type, then they shall have 4606the same kind type parameter. @var{I} and @var{J} shall not both be 4607BOZ constants. 4608@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 4609be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 4610shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 4611@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 4612@end multitable 4613 4614@item @emph{Return value}: 4615If either @var{I} or @var{J} is a BOZ constant, it is first converted 4616as if by the intrinsic function @code{INT} to an integer type with the 4617kind type parameter of the other. 4618 4619@item @emph{See also}: 4620@ref{DSHIFTR} 4621@end table 4622 4623 4624@node DSHIFTR 4625@section @code{DSHIFTR} --- Combined right shift 4626@fnindex DSHIFTR 4627@cindex right shift, combined 4628@cindex shift, right 4629 4630@table @asis 4631@item @emph{Description}: 4632@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The 4633leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT} 4634bits of @var{I}, and the remaining bits are the leftmost bits of 4635@var{J}. 4636 4637@item @emph{Standard}: 4638Fortran 2008 and later 4639 4640@item @emph{Class}: 4641Elemental function 4642 4643@item @emph{Syntax}: 4644@code{RESULT = DSHIFTR(I, J, SHIFT)} 4645 4646@item @emph{Arguments}: 4647@multitable @columnfractions .15 .70 4648@item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. 4649@item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. 4650If both @var{I} and @var{J} have integer type, then they shall have 4651the same kind type parameter. @var{I} and @var{J} shall not both be 4652BOZ constants. 4653@item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall 4654be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} 4655shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, 4656@var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. 4657@end multitable 4658 4659@item @emph{Return value}: 4660If either @var{I} or @var{J} is a BOZ constant, it is first converted 4661as if by the intrinsic function @code{INT} to an integer type with the 4662kind type parameter of the other. 4663 4664@item @emph{See also}: 4665@ref{DSHIFTL} 4666@end table 4667 4668 4669@node DTIME 4670@section @code{DTIME} --- Execution time subroutine (or function) 4671@fnindex DTIME 4672@cindex time, elapsed 4673@cindex elapsed time 4674 4675@table @asis 4676@item @emph{Description}: 4677@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime 4678since the start of the process's execution in @var{TIME}. @var{VALUES} 4679returns the user and system components of this time in @code{VALUES(1)} and 4680@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + 4681VALUES(2)}. 4682 4683Subsequent invocations of @code{DTIME} return values accumulated since the 4684previous invocation. 4685 4686On some systems, the underlying timings are represented using types with 4687sufficiently small limits that overflows (wrap around) are possible, such as 468832-bit types. Therefore, the values returned by this intrinsic might be, or 4689become, negative, or numerically less than previous values, during a single 4690run of the compiled program. 4691 4692Please note, that this implementation is thread safe if used within OpenMP 4693directives, i.e., its state will be consistent while called from multiple 4694threads. However, if @code{DTIME} is called from multiple threads, the result 4695is still the time since the last invocation. This may not give the intended 4696results. If possible, use @code{CPU_TIME} instead. 4697 4698This intrinsic is provided in both subroutine and function forms; however, 4699only one form can be used in any given program unit. 4700 4701@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 4702 4703@multitable @columnfractions .15 .30 .40 4704@item @tab @code{VALUES(1)}: @tab User time in seconds. 4705@item @tab @code{VALUES(2)}: @tab System time in seconds. 4706@item @tab @code{TIME}: @tab Run time since start in seconds. 4707@end multitable 4708 4709@item @emph{Standard}: 4710GNU extension 4711 4712@item @emph{Class}: 4713Subroutine, function 4714 4715@item @emph{Syntax}: 4716@multitable @columnfractions .80 4717@item @code{CALL DTIME(VALUES, TIME)}. 4718@item @code{TIME = DTIME(VALUES)}, (not recommended). 4719@end multitable 4720 4721@item @emph{Arguments}: 4722@multitable @columnfractions .15 .70 4723@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 4724@item @var{TIME}@tab The type shall be @code{REAL(4)}. 4725@end multitable 4726 4727@item @emph{Return value}: 4728Elapsed time in seconds since the last invocation or since the start of program 4729execution if not called before. 4730 4731@item @emph{Example}: 4732@smallexample 4733program test_dtime 4734 integer(8) :: i, j 4735 real, dimension(2) :: tarray 4736 real :: result 4737 call dtime(tarray, result) 4738 print *, result 4739 print *, tarray(1) 4740 print *, tarray(2) 4741 do i=1,100000000 ! Just a delay 4742 j = i * i - i 4743 end do 4744 call dtime(tarray, result) 4745 print *, result 4746 print *, tarray(1) 4747 print *, tarray(2) 4748end program test_dtime 4749@end smallexample 4750 4751@item @emph{See also}: 4752@ref{CPU_TIME} 4753 4754@end table 4755 4756 4757 4758@node EOSHIFT 4759@section @code{EOSHIFT} --- End-off shift elements of an array 4760@fnindex EOSHIFT 4761@cindex array, shift 4762 4763@table @asis 4764@item @emph{Description}: 4765@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on 4766elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is 4767omitted it is taken to be @code{1}. @var{DIM} is a scalar of type 4768@code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the 4769rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of 4770@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, 4771then all complete rank one sections of @var{ARRAY} along the given dimension are 4772shifted. Elements shifted out one end of each rank one section are dropped. If 4773@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY} 4774is copied back in the other end. If @var{BOUNDARY} is not present then the 4775following are copied in depending on the type of @var{ARRAY}. 4776 4777@multitable @columnfractions .15 .80 4778@item @emph{Array Type} @tab @emph{Boundary Value} 4779@item Numeric @tab 0 of the type and kind of @var{ARRAY}. 4780@item Logical @tab @code{.FALSE.}. 4781@item Character(@var{len}) @tab @var{len} blanks. 4782@end multitable 4783 4784@item @emph{Standard}: 4785Fortran 95 and later 4786 4787@item @emph{Class}: 4788Transformational function 4789 4790@item @emph{Syntax}: 4791@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])} 4792 4793@item @emph{Arguments}: 4794@multitable @columnfractions .15 .70 4795@item @var{ARRAY} @tab May be any type, not scalar. 4796@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 4797@item @var{BOUNDARY} @tab Same type as @var{ARRAY}. 4798@item @var{DIM} @tab The type shall be @code{INTEGER}. 4799@end multitable 4800 4801@item @emph{Return value}: 4802Returns an array of same type and rank as the @var{ARRAY} argument. 4803 4804@item @emph{Example}: 4805@smallexample 4806program test_eoshift 4807 integer, dimension(3,3) :: a 4808 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) 4809 print '(3i3)', a(1,:) 4810 print '(3i3)', a(2,:) 4811 print '(3i3)', a(3,:) 4812 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) 4813 print * 4814 print '(3i3)', a(1,:) 4815 print '(3i3)', a(2,:) 4816 print '(3i3)', a(3,:) 4817end program test_eoshift 4818@end smallexample 4819@end table 4820 4821 4822 4823@node EPSILON 4824@section @code{EPSILON} --- Epsilon function 4825@fnindex EPSILON 4826@cindex model representation, epsilon 4827 4828@table @asis 4829@item @emph{Description}: 4830@code{EPSILON(X)} returns the smallest number @var{E} of the same kind 4831as @var{X} such that @math{1 + E > 1}. 4832 4833@item @emph{Standard}: 4834Fortran 95 and later 4835 4836@item @emph{Class}: 4837Inquiry function 4838 4839@item @emph{Syntax}: 4840@code{RESULT = EPSILON(X)} 4841 4842@item @emph{Arguments}: 4843@multitable @columnfractions .15 .70 4844@item @var{X} @tab The type shall be @code{REAL}. 4845@end multitable 4846 4847@item @emph{Return value}: 4848The return value is of same type as the argument. 4849 4850@item @emph{Example}: 4851@smallexample 4852program test_epsilon 4853 real :: x = 3.143 4854 real(8) :: y = 2.33 4855 print *, EPSILON(x) 4856 print *, EPSILON(y) 4857end program test_epsilon 4858@end smallexample 4859@end table 4860 4861 4862 4863@node ERF 4864@section @code{ERF} --- Error function 4865@fnindex ERF 4866@cindex error function 4867 4868@table @asis 4869@item @emph{Description}: 4870@code{ERF(X)} computes the error function of @var{X}. 4871 4872@item @emph{Standard}: 4873Fortran 2008 and later 4874 4875@item @emph{Class}: 4876Elemental function 4877 4878@item @emph{Syntax}: 4879@code{RESULT = ERF(X)} 4880 4881@item @emph{Arguments}: 4882@multitable @columnfractions .15 .70 4883@item @var{X} @tab The type shall be @code{REAL}. 4884@end multitable 4885 4886@item @emph{Return value}: 4887The return value is of type @code{REAL}, of the same kind as 4888@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }. 4889 4890@item @emph{Example}: 4891@smallexample 4892program test_erf 4893 real(8) :: x = 0.17_8 4894 x = erf(x) 4895end program test_erf 4896@end smallexample 4897 4898@item @emph{Specific names}: 4899@multitable @columnfractions .20 .20 .20 .25 4900@item Name @tab Argument @tab Return type @tab Standard 4901@item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4902@end multitable 4903@end table 4904 4905 4906 4907@node ERFC 4908@section @code{ERFC} --- Error function 4909@fnindex ERFC 4910@cindex error function, complementary 4911 4912@table @asis 4913@item @emph{Description}: 4914@code{ERFC(X)} computes the complementary error function of @var{X}. 4915 4916@item @emph{Standard}: 4917Fortran 2008 and later 4918 4919@item @emph{Class}: 4920Elemental function 4921 4922@item @emph{Syntax}: 4923@code{RESULT = ERFC(X)} 4924 4925@item @emph{Arguments}: 4926@multitable @columnfractions .15 .70 4927@item @var{X} @tab The type shall be @code{REAL}. 4928@end multitable 4929 4930@item @emph{Return value}: 4931The return value is of type @code{REAL} and of the same kind as @var{X}. 4932It lies in the range @math{ 0 \leq erfc (x) \leq 2 }. 4933 4934@item @emph{Example}: 4935@smallexample 4936program test_erfc 4937 real(8) :: x = 0.17_8 4938 x = erfc(x) 4939end program test_erfc 4940@end smallexample 4941 4942@item @emph{Specific names}: 4943@multitable @columnfractions .20 .20 .20 .25 4944@item Name @tab Argument @tab Return type @tab Standard 4945@item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension 4946@end multitable 4947@end table 4948 4949 4950 4951@node ERFC_SCALED 4952@section @code{ERFC_SCALED} --- Error function 4953@fnindex ERFC_SCALED 4954@cindex error function, complementary, exponentially-scaled 4955 4956@table @asis 4957@item @emph{Description}: 4958@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary 4959error function of @var{X}. 4960 4961@item @emph{Standard}: 4962Fortran 2008 and later 4963 4964@item @emph{Class}: 4965Elemental function 4966 4967@item @emph{Syntax}: 4968@code{RESULT = ERFC_SCALED(X)} 4969 4970@item @emph{Arguments}: 4971@multitable @columnfractions .15 .70 4972@item @var{X} @tab The type shall be @code{REAL}. 4973@end multitable 4974 4975@item @emph{Return value}: 4976The return value is of type @code{REAL} and of the same kind as @var{X}. 4977 4978@item @emph{Example}: 4979@smallexample 4980program test_erfc_scaled 4981 real(8) :: x = 0.17_8 4982 x = erfc_scaled(x) 4983end program test_erfc_scaled 4984@end smallexample 4985@end table 4986 4987 4988 4989@node ETIME 4990@section @code{ETIME} --- Execution time subroutine (or function) 4991@fnindex ETIME 4992@cindex time, elapsed 4993 4994@table @asis 4995@item @emph{Description}: 4996@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime 4997since the start of the process's execution in @var{TIME}. @var{VALUES} 4998returns the user and system components of this time in @code{VALUES(1)} and 4999@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. 5000 5001On some systems, the underlying timings are represented using types with 5002sufficiently small limits that overflows (wrap around) are possible, such as 500332-bit types. Therefore, the values returned by this intrinsic might be, or 5004become, negative, or numerically less than previous values, during a single 5005run of the compiled program. 5006 5007This intrinsic is provided in both subroutine and function forms; however, 5008only one form can be used in any given program unit. 5009 5010@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: 5011 5012@multitable @columnfractions .15 .30 .60 5013@item @tab @code{VALUES(1)}: @tab User time in seconds. 5014@item @tab @code{VALUES(2)}: @tab System time in seconds. 5015@item @tab @code{TIME}: @tab Run time since start in seconds. 5016@end multitable 5017 5018@item @emph{Standard}: 5019GNU extension 5020 5021@item @emph{Class}: 5022Subroutine, function 5023 5024@item @emph{Syntax}: 5025@multitable @columnfractions .80 5026@item @code{CALL ETIME(VALUES, TIME)}. 5027@item @code{TIME = ETIME(VALUES)}, (not recommended). 5028@end multitable 5029 5030@item @emph{Arguments}: 5031@multitable @columnfractions .15 .70 5032@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. 5033@item @var{TIME}@tab The type shall be @code{REAL(4)}. 5034@end multitable 5035 5036@item @emph{Return value}: 5037Elapsed time in seconds since the start of program execution. 5038 5039@item @emph{Example}: 5040@smallexample 5041program test_etime 5042 integer(8) :: i, j 5043 real, dimension(2) :: tarray 5044 real :: result 5045 call ETIME(tarray, result) 5046 print *, result 5047 print *, tarray(1) 5048 print *, tarray(2) 5049 do i=1,100000000 ! Just a delay 5050 j = i * i - i 5051 end do 5052 call ETIME(tarray, result) 5053 print *, result 5054 print *, tarray(1) 5055 print *, tarray(2) 5056end program test_etime 5057@end smallexample 5058 5059@item @emph{See also}: 5060@ref{CPU_TIME} 5061 5062@end table 5063 5064 5065 5066@node EXECUTE_COMMAND_LINE 5067@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command 5068@fnindex EXECUTE_COMMAND_LINE 5069@cindex system, system call 5070@cindex command line 5071 5072@table @asis 5073@item @emph{Description}: 5074@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or 5075asynchronously. 5076 5077The @code{COMMAND} argument is passed to the shell and executed, using 5078the C library's @code{system} call. (The shell is @code{sh} on Unix 5079systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present 5080and has the value false, the execution of the command is asynchronous 5081if the system supports it; otherwise, the command is executed 5082synchronously. 5083 5084The three last arguments allow the user to get status information. After 5085synchronous execution, @code{EXITSTAT} contains the integer exit code of 5086the command, as returned by @code{system}. @code{CMDSTAT} is set to zero 5087if the command line was executed (whatever its exit status was). 5088@code{CMDMSG} is assigned an error message if an error has occurred. 5089 5090Note that the @code{system} function need not be thread-safe. It is 5091the responsibility of the user to ensure that @code{system} is not 5092called concurrently. 5093 5094@item @emph{Standard}: 5095Fortran 2008 and later 5096 5097@item @emph{Class}: 5098Subroutine 5099 5100@item @emph{Syntax}: 5101@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])} 5102 5103@item @emph{Arguments}: 5104@multitable @columnfractions .15 .70 5105@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar. 5106@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar. 5107@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5108default kind. 5109@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the 5110default kind. 5111@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the 5112default kind. 5113@end multitable 5114 5115@item @emph{Example}: 5116@smallexample 5117program test_exec 5118 integer :: i 5119 5120 call execute_command_line ("external_prog.exe", exitstat=i) 5121 print *, "Exit status of external_prog.exe was ", i 5122 5123 call execute_command_line ("reindex_files.exe", wait=.false.) 5124 print *, "Now reindexing files in the background" 5125 5126end program test_exec 5127@end smallexample 5128 5129 5130@item @emph{Note}: 5131 5132Because this intrinsic is implemented in terms of the @code{system} 5133function call, its behavior with respect to signaling is processor 5134dependent. In particular, on POSIX-compliant systems, the SIGINT and 5135SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As 5136such, if the parent process is terminated, the child process might not be 5137terminated alongside. 5138 5139 5140@item @emph{See also}: 5141@ref{SYSTEM} 5142@end table 5143 5144 5145 5146@node EXIT 5147@section @code{EXIT} --- Exit the program with status. 5148@fnindex EXIT 5149@cindex program termination 5150@cindex terminate program 5151 5152@table @asis 5153@item @emph{Description}: 5154@code{EXIT} causes immediate termination of the program with status. If status 5155is omitted it returns the canonical @emph{success} for the system. All Fortran 5156I/O units are closed. 5157 5158@item @emph{Standard}: 5159GNU extension 5160 5161@item @emph{Class}: 5162Subroutine 5163 5164@item @emph{Syntax}: 5165@code{CALL EXIT([STATUS])} 5166 5167@item @emph{Arguments}: 5168@multitable @columnfractions .15 .70 5169@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind. 5170@end multitable 5171 5172@item @emph{Return value}: 5173@code{STATUS} is passed to the parent process on exit. 5174 5175@item @emph{Example}: 5176@smallexample 5177program test_exit 5178 integer :: STATUS = 0 5179 print *, 'This program is going to exit.' 5180 call EXIT(STATUS) 5181end program test_exit 5182@end smallexample 5183 5184@item @emph{See also}: 5185@ref{ABORT}, @ref{KILL} 5186@end table 5187 5188 5189 5190@node EXP 5191@section @code{EXP} --- Exponential function 5192@fnindex EXP 5193@fnindex DEXP 5194@fnindex CEXP 5195@fnindex ZEXP 5196@fnindex CDEXP 5197@cindex exponential function 5198@cindex logarithm function, inverse 5199 5200@table @asis 5201@item @emph{Description}: 5202@code{EXP(X)} computes the base @math{e} exponential of @var{X}. 5203 5204@item @emph{Standard}: 5205Fortran 77 and later, has overloads that are GNU extensions 5206 5207@item @emph{Class}: 5208Elemental function 5209 5210@item @emph{Syntax}: 5211@code{RESULT = EXP(X)} 5212 5213@item @emph{Arguments}: 5214@multitable @columnfractions .15 .70 5215@item @var{X} @tab The type shall be @code{REAL} or 5216@code{COMPLEX}. 5217@end multitable 5218 5219@item @emph{Return value}: 5220The return value has same type and kind as @var{X}. 5221 5222@item @emph{Example}: 5223@smallexample 5224program test_exp 5225 real :: x = 1.0 5226 x = exp(x) 5227end program test_exp 5228@end smallexample 5229 5230@item @emph{Specific names}: 5231@multitable @columnfractions .20 .20 .20 .25 5232@item Name @tab Argument @tab Return type @tab Standard 5233@item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later 5234@item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later 5235@item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later 5236@item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5237@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 5238@end multitable 5239@end table 5240 5241 5242 5243@node EXPONENT 5244@section @code{EXPONENT} --- Exponent function 5245@fnindex EXPONENT 5246@cindex real number, exponent 5247@cindex floating point, exponent 5248 5249@table @asis 5250@item @emph{Description}: 5251@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X} 5252is zero the value returned is zero. 5253 5254@item @emph{Standard}: 5255Fortran 95 and later 5256 5257@item @emph{Class}: 5258Elemental function 5259 5260@item @emph{Syntax}: 5261@code{RESULT = EXPONENT(X)} 5262 5263@item @emph{Arguments}: 5264@multitable @columnfractions .15 .70 5265@item @var{X} @tab The type shall be @code{REAL}. 5266@end multitable 5267 5268@item @emph{Return value}: 5269The return value is of type default @code{INTEGER}. 5270 5271@item @emph{Example}: 5272@smallexample 5273program test_exponent 5274 real :: x = 1.0 5275 integer :: i 5276 i = exponent(x) 5277 print *, i 5278 print *, exponent(0.0) 5279end program test_exponent 5280@end smallexample 5281@end table 5282 5283 5284 5285@node EXTENDS_TYPE_OF 5286@section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension 5287@fnindex EXTENDS_TYPE_OF 5288 5289@table @asis 5290@item @emph{Description}: 5291Query dynamic type for extension. 5292 5293@item @emph{Standard}: 5294Fortran 2003 and later 5295 5296@item @emph{Class}: 5297Inquiry function 5298 5299@item @emph{Syntax}: 5300@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)} 5301 5302@item @emph{Arguments}: 5303@multitable @columnfractions .15 .70 5304@item @var{A} @tab Shall be an object of extensible declared type or 5305unlimited polymorphic. 5306@item @var{MOLD} @tab Shall be an object of extensible declared type or 5307unlimited polymorphic. 5308@end multitable 5309 5310@item @emph{Return value}: 5311The return value is a scalar of type default logical. It is true if and only if 5312the dynamic type of A is an extension type of the dynamic type of MOLD. 5313 5314 5315@item @emph{See also}: 5316@ref{SAME_TYPE_AS} 5317@end table 5318 5319 5320 5321@node FDATE 5322@section @code{FDATE} --- Get the current time as a string 5323@fnindex FDATE 5324@cindex time, current 5325@cindex current time 5326@cindex date, current 5327@cindex current date 5328 5329@table @asis 5330@item @emph{Description}: 5331@code{FDATE(DATE)} returns the current date (using the same format as 5332@code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE, 5333TIME())}. 5334 5335This intrinsic is provided in both subroutine and function forms; however, 5336only one form can be used in any given program unit. 5337 5338@item @emph{Standard}: 5339GNU extension 5340 5341@item @emph{Class}: 5342Subroutine, function 5343 5344@item @emph{Syntax}: 5345@multitable @columnfractions .80 5346@item @code{CALL FDATE(DATE)}. 5347@item @code{DATE = FDATE()}. 5348@end multitable 5349 5350@item @emph{Arguments}: 5351@multitable @columnfractions .15 .70 5352@item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the 5353default kind. It is an @code{INTENT(OUT)} argument. If the length of 5354this variable is too short for the date and time string to fit 5355completely, it will be blank on procedure return. 5356@end multitable 5357 5358@item @emph{Return value}: 5359The current date and time as a string. 5360 5361@item @emph{Example}: 5362@smallexample 5363program test_fdate 5364 integer(8) :: i, j 5365 character(len=30) :: date 5366 call fdate(date) 5367 print *, 'Program started on ', date 5368 do i = 1, 100000000 ! Just a delay 5369 j = i * i - i 5370 end do 5371 call fdate(date) 5372 print *, 'Program ended on ', date 5373end program test_fdate 5374@end smallexample 5375 5376@item @emph{See also}: 5377@ref{DATE_AND_TIME}, @ref{CTIME} 5378@end table 5379 5380 5381@node FGET 5382@section @code{FGET} --- Read a single character in stream mode from stdin 5383@fnindex FGET 5384@cindex read character, stream mode 5385@cindex stream mode, read character 5386@cindex file operation, read character 5387 5388@table @asis 5389@item @emph{Description}: 5390Read a single character in stream mode from stdin by bypassing normal 5391formatted output. Stream I/O should not be mixed with normal record-oriented 5392(formatted or unformatted) I/O on the same unit; the results are unpredictable. 5393 5394This intrinsic is provided in both subroutine and function forms; however, 5395only one form can be used in any given program unit. 5396 5397Note that the @code{FGET} intrinsic is provided for backwards compatibility with 5398@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 5399Programmers should consider the use of new stream IO feature in new code 5400for future portability. See also @ref{Fortran 2003 status}. 5401 5402@item @emph{Standard}: 5403GNU extension 5404 5405@item @emph{Class}: 5406Subroutine, function 5407 5408@item @emph{Syntax}: 5409@multitable @columnfractions .80 5410@item @code{CALL FGET(C [, STATUS])} 5411@item @code{STATUS = FGET(C)} 5412@end multitable 5413 5414@item @emph{Arguments}: 5415@multitable @columnfractions .15 .70 5416@item @var{C} @tab The type shall be @code{CHARACTER} and of default 5417kind. 5418@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 5419Returns 0 on success, -1 on end-of-file, and a system specific positive 5420error code otherwise. 5421@end multitable 5422 5423@item @emph{Example}: 5424@smallexample 5425PROGRAM test_fget 5426 INTEGER, PARAMETER :: strlen = 100 5427 INTEGER :: status, i = 1 5428 CHARACTER(len=strlen) :: str = "" 5429 5430 WRITE (*,*) 'Enter text:' 5431 DO 5432 CALL fget(str(i:i), status) 5433 if (status /= 0 .OR. i > strlen) exit 5434 i = i + 1 5435 END DO 5436 WRITE (*,*) TRIM(str) 5437END PROGRAM 5438@end smallexample 5439 5440@item @emph{See also}: 5441@ref{FGETC}, @ref{FPUT}, @ref{FPUTC} 5442@end table 5443 5444 5445 5446@node FGETC 5447@section @code{FGETC} --- Read a single character in stream mode 5448@fnindex FGETC 5449@cindex read character, stream mode 5450@cindex stream mode, read character 5451@cindex file operation, read character 5452 5453@table @asis 5454@item @emph{Description}: 5455Read a single character in stream mode by bypassing normal formatted output. 5456Stream I/O should not be mixed with normal record-oriented (formatted or 5457unformatted) I/O on the same unit; the results are unpredictable. 5458 5459This intrinsic is provided in both subroutine and function forms; however, 5460only one form can be used in any given program unit. 5461 5462Note that the @code{FGET} intrinsic is provided for backwards compatibility 5463with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 5464Programmers should consider the use of new stream IO feature in new code 5465for future portability. See also @ref{Fortran 2003 status}. 5466 5467@item @emph{Standard}: 5468GNU extension 5469 5470@item @emph{Class}: 5471Subroutine, function 5472 5473@item @emph{Syntax}: 5474@multitable @columnfractions .80 5475@item @code{CALL FGETC(UNIT, C [, STATUS])} 5476@item @code{STATUS = FGETC(UNIT, C)} 5477@end multitable 5478 5479@item @emph{Arguments}: 5480@multitable @columnfractions .15 .70 5481@item @var{UNIT} @tab The type shall be @code{INTEGER}. 5482@item @var{C} @tab The type shall be @code{CHARACTER} and of default 5483kind. 5484@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 5485Returns 0 on success, -1 on end-of-file and a system specific positive 5486error code otherwise. 5487@end multitable 5488 5489@item @emph{Example}: 5490@smallexample 5491PROGRAM test_fgetc 5492 INTEGER :: fd = 42, status 5493 CHARACTER :: c 5494 5495 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD") 5496 DO 5497 CALL fgetc(fd, c, status) 5498 IF (status /= 0) EXIT 5499 call fput(c) 5500 END DO 5501 CLOSE(UNIT=fd) 5502END PROGRAM 5503@end smallexample 5504 5505@item @emph{See also}: 5506@ref{FGET}, @ref{FPUT}, @ref{FPUTC} 5507@end table 5508 5509 5510 5511@node FLOOR 5512@section @code{FLOOR} --- Integer floor function 5513@fnindex FLOOR 5514@cindex floor 5515@cindex rounding, floor 5516 5517@table @asis 5518@item @emph{Description}: 5519@code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}. 5520 5521@item @emph{Standard}: 5522Fortran 95 and later 5523 5524@item @emph{Class}: 5525Elemental function 5526 5527@item @emph{Syntax}: 5528@code{RESULT = FLOOR(A [, KIND])} 5529 5530@item @emph{Arguments}: 5531@multitable @columnfractions .15 .70 5532@item @var{A} @tab The type shall be @code{REAL}. 5533@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 5534expression indicating the kind parameter of the result. 5535@end multitable 5536 5537@item @emph{Return value}: 5538The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present 5539and of default-kind @code{INTEGER} otherwise. 5540 5541@item @emph{Example}: 5542@smallexample 5543program test_floor 5544 real :: x = 63.29 5545 real :: y = -63.59 5546 print *, floor(x) ! returns 63 5547 print *, floor(y) ! returns -64 5548end program test_floor 5549@end smallexample 5550 5551@item @emph{See also}: 5552@ref{CEILING}, @ref{NINT} 5553 5554@end table 5555 5556 5557 5558@node FLUSH 5559@section @code{FLUSH} --- Flush I/O unit(s) 5560@fnindex FLUSH 5561@cindex file operation, flush 5562 5563@table @asis 5564@item @emph{Description}: 5565Flushes Fortran unit(s) currently open for output. Without the optional 5566argument, all units are flushed, otherwise just the unit specified. 5567 5568@item @emph{Standard}: 5569GNU extension 5570 5571@item @emph{Class}: 5572Subroutine 5573 5574@item @emph{Syntax}: 5575@code{CALL FLUSH(UNIT)} 5576 5577@item @emph{Arguments}: 5578@multitable @columnfractions .15 .70 5579@item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}. 5580@end multitable 5581 5582@item @emph{Note}: 5583Beginning with the Fortran 2003 standard, there is a @code{FLUSH} 5584statement that should be preferred over the @code{FLUSH} intrinsic. 5585 5586The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement 5587have identical effect: they flush the runtime library's I/O buffer so 5588that the data becomes visible to other processes. This does not guarantee 5589that the data is committed to disk. 5590 5591On POSIX systems, you can request that all data is transferred to the 5592storage device by calling the @code{fsync} function, with the POSIX file 5593descriptor of the I/O unit as argument (retrieved with GNU intrinsic 5594@code{FNUM}). The following example shows how: 5595 5596@smallexample 5597 ! Declare the interface for POSIX fsync function 5598 interface 5599 function fsync (fd) bind(c,name="fsync") 5600 use iso_c_binding, only: c_int 5601 integer(c_int), value :: fd 5602 integer(c_int) :: fsync 5603 end function fsync 5604 end interface 5605 5606 ! Variable declaration 5607 integer :: ret 5608 5609 ! Opening unit 10 5610 open (10,file="foo") 5611 5612 ! ... 5613 ! Perform I/O on unit 10 5614 ! ... 5615 5616 ! Flush and sync 5617 flush(10) 5618 ret = fsync(fnum(10)) 5619 5620 ! Handle possible error 5621 if (ret /= 0) stop "Error calling FSYNC" 5622@end smallexample 5623 5624@end table 5625 5626 5627 5628@node FNUM 5629@section @code{FNUM} --- File number function 5630@fnindex FNUM 5631@cindex file operation, file number 5632 5633@table @asis 5634@item @emph{Description}: 5635@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the 5636open Fortran I/O unit @code{UNIT}. 5637 5638@item @emph{Standard}: 5639GNU extension 5640 5641@item @emph{Class}: 5642Function 5643 5644@item @emph{Syntax}: 5645@code{RESULT = FNUM(UNIT)} 5646 5647@item @emph{Arguments}: 5648@multitable @columnfractions .15 .70 5649@item @var{UNIT} @tab The type shall be @code{INTEGER}. 5650@end multitable 5651 5652@item @emph{Return value}: 5653The return value is of type @code{INTEGER} 5654 5655@item @emph{Example}: 5656@smallexample 5657program test_fnum 5658 integer :: i 5659 open (unit=10, status = "scratch") 5660 i = fnum(10) 5661 print *, i 5662 close (10) 5663end program test_fnum 5664@end smallexample 5665@end table 5666 5667 5668 5669@node FPUT 5670@section @code{FPUT} --- Write a single character in stream mode to stdout 5671@fnindex FPUT 5672@cindex write character, stream mode 5673@cindex stream mode, write character 5674@cindex file operation, write character 5675 5676@table @asis 5677@item @emph{Description}: 5678Write a single character in stream mode to stdout by bypassing normal 5679formatted output. Stream I/O should not be mixed with normal record-oriented 5680(formatted or unformatted) I/O on the same unit; the results are unpredictable. 5681 5682This intrinsic is provided in both subroutine and function forms; however, 5683only one form can be used in any given program unit. 5684 5685Note that the @code{FGET} intrinsic is provided for backwards compatibility with 5686@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 5687Programmers should consider the use of new stream IO feature in new code 5688for future portability. See also @ref{Fortran 2003 status}. 5689 5690@item @emph{Standard}: 5691GNU extension 5692 5693@item @emph{Class}: 5694Subroutine, function 5695 5696@item @emph{Syntax}: 5697@multitable @columnfractions .80 5698@item @code{CALL FPUT(C [, STATUS])} 5699@item @code{STATUS = FPUT(C)} 5700@end multitable 5701 5702@item @emph{Arguments}: 5703@multitable @columnfractions .15 .70 5704@item @var{C} @tab The type shall be @code{CHARACTER} and of default 5705kind. 5706@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 5707Returns 0 on success, -1 on end-of-file and a system specific positive 5708error code otherwise. 5709@end multitable 5710 5711@item @emph{Example}: 5712@smallexample 5713PROGRAM test_fput 5714 CHARACTER(len=10) :: str = "gfortran" 5715 INTEGER :: i 5716 DO i = 1, len_trim(str) 5717 CALL fput(str(i:i)) 5718 END DO 5719END PROGRAM 5720@end smallexample 5721 5722@item @emph{See also}: 5723@ref{FPUTC}, @ref{FGET}, @ref{FGETC} 5724@end table 5725 5726 5727 5728@node FPUTC 5729@section @code{FPUTC} --- Write a single character in stream mode 5730@fnindex FPUTC 5731@cindex write character, stream mode 5732@cindex stream mode, write character 5733@cindex file operation, write character 5734 5735@table @asis 5736@item @emph{Description}: 5737Write a single character in stream mode by bypassing normal formatted 5738output. Stream I/O should not be mixed with normal record-oriented 5739(formatted or unformatted) I/O on the same unit; the results are unpredictable. 5740 5741This intrinsic is provided in both subroutine and function forms; however, 5742only one form can be used in any given program unit. 5743 5744Note that the @code{FGET} intrinsic is provided for backwards compatibility with 5745@command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. 5746Programmers should consider the use of new stream IO feature in new code 5747for future portability. See also @ref{Fortran 2003 status}. 5748 5749@item @emph{Standard}: 5750GNU extension 5751 5752@item @emph{Class}: 5753Subroutine, function 5754 5755@item @emph{Syntax}: 5756@multitable @columnfractions .80 5757@item @code{CALL FPUTC(UNIT, C [, STATUS])} 5758@item @code{STATUS = FPUTC(UNIT, C)} 5759@end multitable 5760 5761@item @emph{Arguments}: 5762@multitable @columnfractions .15 .70 5763@item @var{UNIT} @tab The type shall be @code{INTEGER}. 5764@item @var{C} @tab The type shall be @code{CHARACTER} and of default 5765kind. 5766@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 5767Returns 0 on success, -1 on end-of-file and a system specific positive 5768error code otherwise. 5769@end multitable 5770 5771@item @emph{Example}: 5772@smallexample 5773PROGRAM test_fputc 5774 CHARACTER(len=10) :: str = "gfortran" 5775 INTEGER :: fd = 42, i 5776 5777 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW") 5778 DO i = 1, len_trim(str) 5779 CALL fputc(fd, str(i:i)) 5780 END DO 5781 CLOSE(fd) 5782END PROGRAM 5783@end smallexample 5784 5785@item @emph{See also}: 5786@ref{FPUT}, @ref{FGET}, @ref{FGETC} 5787@end table 5788 5789 5790 5791@node FRACTION 5792@section @code{FRACTION} --- Fractional part of the model representation 5793@fnindex FRACTION 5794@cindex real number, fraction 5795@cindex floating point, fraction 5796 5797@table @asis 5798@item @emph{Description}: 5799@code{FRACTION(X)} returns the fractional part of the model 5800representation of @code{X}. 5801 5802@item @emph{Standard}: 5803Fortran 95 and later 5804 5805@item @emph{Class}: 5806Elemental function 5807 5808@item @emph{Syntax}: 5809@code{Y = FRACTION(X)} 5810 5811@item @emph{Arguments}: 5812@multitable @columnfractions .15 .70 5813@item @var{X} @tab The type of the argument shall be a @code{REAL}. 5814@end multitable 5815 5816@item @emph{Return value}: 5817The return value is of the same type and kind as the argument. 5818The fractional part of the model representation of @code{X} is returned; 5819it is @code{X * RADIX(X)**(-EXPONENT(X))}. 5820 5821@item @emph{Example}: 5822@smallexample 5823program test_fraction 5824 real :: x 5825 x = 178.1387e-4 5826 print *, fraction(x), x * radix(x)**(-exponent(x)) 5827end program test_fraction 5828@end smallexample 5829 5830@end table 5831 5832 5833 5834@node FREE 5835@section @code{FREE} --- Frees memory 5836@fnindex FREE 5837@cindex pointer, cray 5838 5839@table @asis 5840@item @emph{Description}: 5841Frees memory previously allocated by @code{MALLOC}. The @code{FREE} 5842intrinsic is an extension intended to be used with Cray pointers, and is 5843provided in GNU Fortran to allow user to compile legacy code. For 5844new code using Fortran 95 pointers, the memory de-allocation intrinsic is 5845@code{DEALLOCATE}. 5846 5847@item @emph{Standard}: 5848GNU extension 5849 5850@item @emph{Class}: 5851Subroutine 5852 5853@item @emph{Syntax}: 5854@code{CALL FREE(PTR)} 5855 5856@item @emph{Arguments}: 5857@multitable @columnfractions .15 .70 5858@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the 5859location of the memory that should be de-allocated. 5860@end multitable 5861 5862@item @emph{Return value}: 5863None 5864 5865@item @emph{Example}: 5866See @code{MALLOC} for an example. 5867 5868@item @emph{See also}: 5869@ref{MALLOC} 5870@end table 5871 5872 5873 5874@node FSEEK 5875@section @code{FSEEK} --- Low level file positioning subroutine 5876@fnindex FSEEK 5877@cindex file operation, seek 5878@cindex file operation, position 5879 5880@table @asis 5881@item @emph{Description}: 5882Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} 5883is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET}, 5884if set to 1, @var{OFFSET} is taken to be relative to the current position 5885@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}. 5886On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek 5887fails silently. 5888 5889This intrinsic routine is not fully backwards compatible with @command{g77}. 5890In @command{g77}, the @code{FSEEK} takes a statement label instead of a 5891@var{STATUS} variable. If FSEEK is used in old code, change 5892@smallexample 5893 CALL FSEEK(UNIT, OFFSET, WHENCE, *label) 5894@end smallexample 5895to 5896@smallexample 5897 INTEGER :: status 5898 CALL FSEEK(UNIT, OFFSET, WHENCE, status) 5899 IF (status /= 0) GOTO label 5900@end smallexample 5901 5902Please note that GNU Fortran provides the Fortran 2003 Stream facility. 5903Programmers should consider the use of new stream IO feature in new code 5904for future portability. See also @ref{Fortran 2003 status}. 5905 5906@item @emph{Standard}: 5907GNU extension 5908 5909@item @emph{Class}: 5910Subroutine 5911 5912@item @emph{Syntax}: 5913@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])} 5914 5915@item @emph{Arguments}: 5916@multitable @columnfractions .15 .70 5917@item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}. 5918@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}. 5919@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}. 5920Its value shall be either 0, 1 or 2. 5921@item @var{STATUS} @tab (Optional) shall be a scalar of type 5922@code{INTEGER(4)}. 5923@end multitable 5924 5925@item @emph{Example}: 5926@smallexample 5927PROGRAM test_fseek 5928 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2 5929 INTEGER :: fd, offset, ierr 5930 5931 ierr = 0 5932 offset = 5 5933 fd = 10 5934 5935 OPEN(UNIT=fd, FILE="fseek.test") 5936 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET 5937 print *, FTELL(fd), ierr 5938 5939 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end 5940 print *, FTELL(fd), ierr 5941 5942 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning 5943 print *, FTELL(fd), ierr 5944 5945 CLOSE(UNIT=fd) 5946END PROGRAM 5947@end smallexample 5948 5949@item @emph{See also}: 5950@ref{FTELL} 5951@end table 5952 5953 5954 5955@node FSTAT 5956@section @code{FSTAT} --- Get file status 5957@fnindex FSTAT 5958@cindex file system, file status 5959 5960@table @asis 5961@item @emph{Description}: 5962@code{FSTAT} is identical to @ref{STAT}, except that information about an 5963already opened file is obtained. 5964 5965The elements in @code{VALUES} are the same as described by @ref{STAT}. 5966 5967This intrinsic is provided in both subroutine and function forms; however, 5968only one form can be used in any given program unit. 5969 5970@item @emph{Standard}: 5971GNU extension 5972 5973@item @emph{Class}: 5974Subroutine, function 5975 5976@item @emph{Syntax}: 5977@multitable @columnfractions .80 5978@item @code{CALL FSTAT(UNIT, VALUES [, STATUS])} 5979@item @code{STATUS = FSTAT(UNIT, VALUES)} 5980@end multitable 5981 5982@item @emph{Arguments}: 5983@multitable @columnfractions .15 .70 5984@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. 5985@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 5986@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 5987on success and a system specific error code otherwise. 5988@end multitable 5989 5990@item @emph{Example}: 5991See @ref{STAT} for an example. 5992 5993@item @emph{See also}: 5994To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT} 5995@end table 5996 5997 5998 5999@node FTELL 6000@section @code{FTELL} --- Current stream position 6001@fnindex FTELL 6002@cindex file operation, position 6003 6004@table @asis 6005@item @emph{Description}: 6006Retrieves the current position within an open file. 6007 6008This intrinsic is provided in both subroutine and function forms; however, 6009only one form can be used in any given program unit. 6010 6011@item @emph{Standard}: 6012GNU extension 6013 6014@item @emph{Class}: 6015Subroutine, function 6016 6017@item @emph{Syntax}: 6018@multitable @columnfractions .80 6019@item @code{CALL FTELL(UNIT, OFFSET)} 6020@item @code{OFFSET = FTELL(UNIT)} 6021@end multitable 6022 6023@item @emph{Arguments}: 6024@multitable @columnfractions .15 .70 6025@item @var{OFFSET} @tab Shall of type @code{INTEGER}. 6026@item @var{UNIT} @tab Shall of type @code{INTEGER}. 6027@end multitable 6028 6029@item @emph{Return value}: 6030In either syntax, @var{OFFSET} is set to the current offset of unit 6031number @var{UNIT}, or to @math{-1} if the unit is not currently open. 6032 6033@item @emph{Example}: 6034@smallexample 6035PROGRAM test_ftell 6036 INTEGER :: i 6037 OPEN(10, FILE="temp.dat") 6038 CALL ftell(10,i) 6039 WRITE(*,*) i 6040END PROGRAM 6041@end smallexample 6042 6043@item @emph{See also}: 6044@ref{FSEEK} 6045@end table 6046 6047 6048 6049@node GAMMA 6050@section @code{GAMMA} --- Gamma function 6051@fnindex GAMMA 6052@fnindex DGAMMA 6053@cindex Gamma function 6054@cindex Factorial function 6055 6056@table @asis 6057@item @emph{Description}: 6058@code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive, 6059integer values of @var{X} the Gamma function simplifies to the factorial 6060function @math{\Gamma(x)=(x-1)!}. 6061 6062@tex 6063$$ 6064\Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t 6065$$ 6066@end tex 6067 6068@item @emph{Standard}: 6069Fortran 2008 and later 6070 6071@item @emph{Class}: 6072Elemental function 6073 6074@item @emph{Syntax}: 6075@code{X = GAMMA(X)} 6076 6077@item @emph{Arguments}: 6078@multitable @columnfractions .15 .70 6079@item @var{X} @tab Shall be of type @code{REAL} and neither zero 6080nor a negative integer. 6081@end multitable 6082 6083@item @emph{Return value}: 6084The return value is of type @code{REAL} of the same kind as @var{X}. 6085 6086@item @emph{Example}: 6087@smallexample 6088program test_gamma 6089 real :: x = 1.0 6090 x = gamma(x) ! returns 1.0 6091end program test_gamma 6092@end smallexample 6093 6094@item @emph{Specific names}: 6095@multitable @columnfractions .20 .20 .20 .25 6096@item Name @tab Argument @tab Return type @tab Standard 6097@item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 6098@item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 6099@end multitable 6100 6101@item @emph{See also}: 6102Logarithm of the Gamma function: @ref{LOG_GAMMA} 6103 6104@end table 6105 6106 6107 6108@node GERROR 6109@section @code{GERROR} --- Get last system error message 6110@fnindex GERROR 6111@cindex system, error handling 6112 6113@table @asis 6114@item @emph{Description}: 6115Returns the system error message corresponding to the last system error. 6116This resembles the functionality of @code{strerror(3)} in C. 6117 6118@item @emph{Standard}: 6119GNU extension 6120 6121@item @emph{Class}: 6122Subroutine 6123 6124@item @emph{Syntax}: 6125@code{CALL GERROR(RESULT)} 6126 6127@item @emph{Arguments}: 6128@multitable @columnfractions .15 .70 6129@item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default 6130@end multitable 6131 6132@item @emph{Example}: 6133@smallexample 6134PROGRAM test_gerror 6135 CHARACTER(len=100) :: msg 6136 CALL gerror(msg) 6137 WRITE(*,*) msg 6138END PROGRAM 6139@end smallexample 6140 6141@item @emph{See also}: 6142@ref{IERRNO}, @ref{PERROR} 6143@end table 6144 6145 6146 6147@node GETARG 6148@section @code{GETARG} --- Get command line arguments 6149@fnindex GETARG 6150@cindex command-line arguments 6151@cindex arguments, to program 6152 6153@table @asis 6154@item @emph{Description}: 6155Retrieve the @var{POS}-th argument that was passed on the 6156command line when the containing program was invoked. 6157 6158This intrinsic routine is provided for backwards compatibility with 6159GNU Fortran 77. In new code, programmers should consider the use of 6160the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 6161standard. 6162 6163@item @emph{Standard}: 6164GNU extension 6165 6166@item @emph{Class}: 6167Subroutine 6168 6169@item @emph{Syntax}: 6170@code{CALL GETARG(POS, VALUE)} 6171 6172@item @emph{Arguments}: 6173@multitable @columnfractions .15 .70 6174@item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than 6175the default integer kind; @math{@var{POS} \geq 0} 6176@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default 6177kind. 6178@item @var{VALUE} @tab Shall be of type @code{CHARACTER}. 6179@end multitable 6180 6181@item @emph{Return value}: 6182After @code{GETARG} returns, the @var{VALUE} argument holds the 6183@var{POS}th command line argument. If @var{VALUE} can not hold the 6184argument, it is truncated to fit the length of @var{VALUE}. If there are 6185less than @var{POS} arguments specified at the command line, @var{VALUE} 6186will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set 6187to the name of the program (on systems that support this feature). 6188 6189@item @emph{Example}: 6190@smallexample 6191PROGRAM test_getarg 6192 INTEGER :: i 6193 CHARACTER(len=32) :: arg 6194 6195 DO i = 1, iargc() 6196 CALL getarg(i, arg) 6197 WRITE (*,*) arg 6198 END DO 6199END PROGRAM 6200@end smallexample 6201 6202@item @emph{See also}: 6203GNU Fortran 77 compatibility function: @ref{IARGC} 6204 6205Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, 6206@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 6207@end table 6208 6209 6210 6211@node GET_COMMAND 6212@section @code{GET_COMMAND} --- Get the entire command line 6213@fnindex GET_COMMAND 6214@cindex command-line arguments 6215@cindex arguments, to program 6216 6217@table @asis 6218@item @emph{Description}: 6219Retrieve the entire command line that was used to invoke the program. 6220 6221@item @emph{Standard}: 6222Fortran 2003 and later 6223 6224@item @emph{Class}: 6225Subroutine 6226 6227@item @emph{Syntax}: 6228@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])} 6229 6230@item @emph{Arguments}: 6231@multitable @columnfractions .15 .70 6232@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and 6233of default kind. 6234@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of 6235default kind. 6236@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of 6237default kind. 6238@end multitable 6239 6240@item @emph{Return value}: 6241If @var{COMMAND} is present, stores the entire command line that was used 6242to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is 6243assigned the length of the command line. If @var{STATUS} is present, it 6244is assigned 0 upon success of the command, -1 if @var{COMMAND} is too 6245short to store the command line, or a positive value in case of an error. 6246 6247@item @emph{Example}: 6248@smallexample 6249PROGRAM test_get_command 6250 CHARACTER(len=255) :: cmd 6251 CALL get_command(cmd) 6252 WRITE (*,*) TRIM(cmd) 6253END PROGRAM 6254@end smallexample 6255 6256@item @emph{See also}: 6257@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 6258@end table 6259 6260 6261 6262@node GET_COMMAND_ARGUMENT 6263@section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments 6264@fnindex GET_COMMAND_ARGUMENT 6265@cindex command-line arguments 6266@cindex arguments, to program 6267 6268@table @asis 6269@item @emph{Description}: 6270Retrieve the @var{NUMBER}-th argument that was passed on the 6271command line when the containing program was invoked. 6272 6273@item @emph{Standard}: 6274Fortran 2003 and later 6275 6276@item @emph{Class}: 6277Subroutine 6278 6279@item @emph{Syntax}: 6280@code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])} 6281 6282@item @emph{Arguments}: 6283@multitable @columnfractions .15 .70 6284@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of 6285default kind, @math{@var{NUMBER} \geq 0} 6286@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 6287and of default kind. 6288@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6289and of default kind. 6290@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6291and of default kind. 6292@end multitable 6293 6294@item @emph{Return value}: 6295After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the 6296@var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is 6297truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER} 6298arguments specified at the command line, @var{VALUE} will be filled with blanks. 6299If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on 6300systems that support this feature). The @var{LENGTH} argument contains the 6301length of the @var{NUMBER}-th command line argument. If the argument retrieval 6302fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated 6303command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is 6304zero. 6305 6306@item @emph{Example}: 6307@smallexample 6308PROGRAM test_get_command_argument 6309 INTEGER :: i 6310 CHARACTER(len=32) :: arg 6311 6312 i = 0 6313 DO 6314 CALL get_command_argument(i, arg) 6315 IF (LEN_TRIM(arg) == 0) EXIT 6316 6317 WRITE (*,*) TRIM(arg) 6318 i = i+1 6319 END DO 6320END PROGRAM 6321@end smallexample 6322 6323@item @emph{See also}: 6324@ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT} 6325@end table 6326 6327 6328 6329@node GETCWD 6330@section @code{GETCWD} --- Get current working directory 6331@fnindex GETCWD 6332@cindex system, working directory 6333 6334@table @asis 6335@item @emph{Description}: 6336Get current working directory. 6337 6338This intrinsic is provided in both subroutine and function forms; however, 6339only one form can be used in any given program unit. 6340 6341@item @emph{Standard}: 6342GNU extension 6343 6344@item @emph{Class}: 6345Subroutine, function 6346 6347@item @emph{Syntax}: 6348@multitable @columnfractions .80 6349@item @code{CALL GETCWD(C [, STATUS])} 6350@item @code{STATUS = GETCWD(C)} 6351@end multitable 6352 6353@item @emph{Arguments}: 6354@multitable @columnfractions .15 .70 6355@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. 6356@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, 6357a system specific and nonzero error code otherwise. 6358@end multitable 6359 6360@item @emph{Example}: 6361@smallexample 6362PROGRAM test_getcwd 6363 CHARACTER(len=255) :: cwd 6364 CALL getcwd(cwd) 6365 WRITE(*,*) TRIM(cwd) 6366END PROGRAM 6367@end smallexample 6368 6369@item @emph{See also}: 6370@ref{CHDIR} 6371@end table 6372 6373 6374 6375@node GETENV 6376@section @code{GETENV} --- Get an environmental variable 6377@fnindex GETENV 6378@cindex environment variable 6379 6380@table @asis 6381@item @emph{Description}: 6382Get the @var{VALUE} of the environmental variable @var{NAME}. 6383 6384This intrinsic routine is provided for backwards compatibility with 6385GNU Fortran 77. In new code, programmers should consider the use of 6386the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran 63872003 standard. 6388 6389Note that @code{GETENV} need not be thread-safe. It is the 6390responsibility of the user to ensure that the environment is not being 6391updated concurrently with a call to the @code{GETENV} intrinsic. 6392 6393@item @emph{Standard}: 6394GNU extension 6395 6396@item @emph{Class}: 6397Subroutine 6398 6399@item @emph{Syntax}: 6400@code{CALL GETENV(NAME, VALUE)} 6401 6402@item @emph{Arguments}: 6403@multitable @columnfractions .15 .70 6404@item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind. 6405@item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. 6406@end multitable 6407 6408@item @emph{Return value}: 6409Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 6410not large enough to hold the data, it is truncated. If @var{NAME} 6411is not set, @var{VALUE} will be filled with blanks. 6412 6413@item @emph{Example}: 6414@smallexample 6415PROGRAM test_getenv 6416 CHARACTER(len=255) :: homedir 6417 CALL getenv("HOME", homedir) 6418 WRITE (*,*) TRIM(homedir) 6419END PROGRAM 6420@end smallexample 6421 6422@item @emph{See also}: 6423@ref{GET_ENVIRONMENT_VARIABLE} 6424@end table 6425 6426 6427 6428@node GET_ENVIRONMENT_VARIABLE 6429@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable 6430@fnindex GET_ENVIRONMENT_VARIABLE 6431@cindex environment variable 6432 6433@table @asis 6434@item @emph{Description}: 6435Get the @var{VALUE} of the environmental variable @var{NAME}. 6436 6437Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It 6438is the responsibility of the user to ensure that the environment is 6439not being updated concurrently with a call to the 6440@code{GET_ENVIRONMENT_VARIABLE} intrinsic. 6441 6442@item @emph{Standard}: 6443Fortran 2003 and later 6444 6445@item @emph{Class}: 6446Subroutine 6447 6448@item @emph{Syntax}: 6449@code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)} 6450 6451@item @emph{Arguments}: 6452@multitable @columnfractions .15 .70 6453@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER} 6454and of default kind. 6455@item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} 6456and of default kind. 6457@item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6458and of default kind. 6459@item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} 6460and of default kind. 6461@item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL} 6462and of default kind. 6463@end multitable 6464 6465@item @emph{Return value}: 6466Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is 6467not large enough to hold the data, it is truncated. If @var{NAME} 6468is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH} 6469contains the length needed for storing the environment variable @var{NAME} 6470or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present 6471but too short for the environment variable; it is 1 if the environment 6472variable does not exist and 2 if the processor does not support environment 6473variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is 6474present with the value @code{.FALSE.}, the trailing blanks in @var{NAME} 6475are significant; otherwise they are not part of the environment variable 6476name. 6477 6478@item @emph{Example}: 6479@smallexample 6480PROGRAM test_getenv 6481 CHARACTER(len=255) :: homedir 6482 CALL get_environment_variable("HOME", homedir) 6483 WRITE (*,*) TRIM(homedir) 6484END PROGRAM 6485@end smallexample 6486@end table 6487 6488 6489 6490@node GETGID 6491@section @code{GETGID} --- Group ID function 6492@fnindex GETGID 6493@cindex system, group ID 6494 6495@table @asis 6496@item @emph{Description}: 6497Returns the numerical group ID of the current process. 6498 6499@item @emph{Standard}: 6500GNU extension 6501 6502@item @emph{Class}: 6503Function 6504 6505@item @emph{Syntax}: 6506@code{RESULT = GETGID()} 6507 6508@item @emph{Return value}: 6509The return value of @code{GETGID} is an @code{INTEGER} of the default 6510kind. 6511 6512 6513@item @emph{Example}: 6514See @code{GETPID} for an example. 6515 6516@item @emph{See also}: 6517@ref{GETPID}, @ref{GETUID} 6518@end table 6519 6520 6521 6522@node GETLOG 6523@section @code{GETLOG} --- Get login name 6524@fnindex GETLOG 6525@cindex system, login name 6526@cindex login name 6527 6528@table @asis 6529@item @emph{Description}: 6530Gets the username under which the program is running. 6531 6532@item @emph{Standard}: 6533GNU extension 6534 6535@item @emph{Class}: 6536Subroutine 6537 6538@item @emph{Syntax}: 6539@code{CALL GETLOG(C)} 6540 6541@item @emph{Arguments}: 6542@multitable @columnfractions .15 .70 6543@item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind. 6544@end multitable 6545 6546@item @emph{Return value}: 6547Stores the current user name in @var{LOGIN}. (On systems where POSIX 6548functions @code{geteuid} and @code{getpwuid} are not available, and 6549the @code{getlogin} function is not implemented either, this will 6550return a blank string.) 6551 6552@item @emph{Example}: 6553@smallexample 6554PROGRAM TEST_GETLOG 6555 CHARACTER(32) :: login 6556 CALL GETLOG(login) 6557 WRITE(*,*) login 6558END PROGRAM 6559@end smallexample 6560 6561@item @emph{See also}: 6562@ref{GETUID} 6563@end table 6564 6565 6566 6567@node GETPID 6568@section @code{GETPID} --- Process ID function 6569@fnindex GETPID 6570@cindex system, process ID 6571@cindex process ID 6572 6573@table @asis 6574@item @emph{Description}: 6575Returns the numerical process identifier of the current process. 6576 6577@item @emph{Standard}: 6578GNU extension 6579 6580@item @emph{Class}: 6581Function 6582 6583@item @emph{Syntax}: 6584@code{RESULT = GETPID()} 6585 6586@item @emph{Return value}: 6587The return value of @code{GETPID} is an @code{INTEGER} of the default 6588kind. 6589 6590 6591@item @emph{Example}: 6592@smallexample 6593program info 6594 print *, "The current process ID is ", getpid() 6595 print *, "Your numerical user ID is ", getuid() 6596 print *, "Your numerical group ID is ", getgid() 6597end program info 6598@end smallexample 6599 6600@item @emph{See also}: 6601@ref{GETGID}, @ref{GETUID} 6602@end table 6603 6604 6605 6606@node GETUID 6607@section @code{GETUID} --- User ID function 6608@fnindex GETUID 6609@cindex system, user ID 6610@cindex user id 6611 6612@table @asis 6613@item @emph{Description}: 6614Returns the numerical user ID of the current process. 6615 6616@item @emph{Standard}: 6617GNU extension 6618 6619@item @emph{Class}: 6620Function 6621 6622@item @emph{Syntax}: 6623@code{RESULT = GETUID()} 6624 6625@item @emph{Return value}: 6626The return value of @code{GETUID} is an @code{INTEGER} of the default 6627kind. 6628 6629 6630@item @emph{Example}: 6631See @code{GETPID} for an example. 6632 6633@item @emph{See also}: 6634@ref{GETPID}, @ref{GETLOG} 6635@end table 6636 6637 6638 6639@node GMTIME 6640@section @code{GMTIME} --- Convert time to GMT info 6641@fnindex GMTIME 6642@cindex time, conversion to GMT info 6643 6644@table @asis 6645@item @emph{Description}: 6646Given a system time value @var{TIME} (as provided by the @code{TIME8} 6647intrinsic), fills @var{VALUES} with values extracted from it appropriate 6648to the UTC time zone (Universal Coordinated Time, also known in some 6649countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}. 6650 6651@item @emph{Standard}: 6652GNU extension 6653 6654@item @emph{Class}: 6655Subroutine 6656 6657@item @emph{Syntax}: 6658@code{CALL GMTIME(TIME, VALUES)} 6659 6660@item @emph{Arguments}: 6661@multitable @columnfractions .15 .70 6662@item @var{TIME} @tab An @code{INTEGER} scalar expression 6663corresponding to a system time, with @code{INTENT(IN)}. 6664@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 6665with @code{INTENT(OUT)}. 6666@end multitable 6667 6668@item @emph{Return value}: 6669The elements of @var{VALUES} are assigned as follows: 6670@enumerate 6671@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 6672seconds 6673@item Minutes after the hour, range 0--59 6674@item Hours past midnight, range 0--23 6675@item Day of month, range 0--31 6676@item Number of months since January, range 0--12 6677@item Years since 1900 6678@item Number of days since Sunday, range 0--6 6679@item Days since January 1 6680@item Daylight savings indicator: positive if daylight savings is in 6681effect, zero if not, and negative if the information is not available. 6682@end enumerate 6683 6684@item @emph{See also}: 6685@ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} 6686 6687@end table 6688 6689 6690 6691@node HOSTNM 6692@section @code{HOSTNM} --- Get system host name 6693@fnindex HOSTNM 6694@cindex system, host name 6695 6696@table @asis 6697@item @emph{Description}: 6698Retrieves the host name of the system on which the program is running. 6699 6700This intrinsic is provided in both subroutine and function forms; however, 6701only one form can be used in any given program unit. 6702 6703@item @emph{Standard}: 6704GNU extension 6705 6706@item @emph{Class}: 6707Subroutine, function 6708 6709@item @emph{Syntax}: 6710@multitable @columnfractions .80 6711@item @code{CALL HOSTNM(C [, STATUS])} 6712@item @code{STATUS = HOSTNM(NAME)} 6713@end multitable 6714 6715@item @emph{Arguments}: 6716@multitable @columnfractions .15 .70 6717@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind. 6718@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. 6719Returns 0 on success, or a system specific error code otherwise. 6720@end multitable 6721 6722@item @emph{Return value}: 6723In either syntax, @var{NAME} is set to the current hostname if it can 6724be obtained, or to a blank string otherwise. 6725 6726@end table 6727 6728 6729 6730@node HUGE 6731@section @code{HUGE} --- Largest number of a kind 6732@fnindex HUGE 6733@cindex limits, largest number 6734@cindex model representation, largest number 6735 6736@table @asis 6737@item @emph{Description}: 6738@code{HUGE(X)} returns the largest number that is not an infinity in 6739the model of the type of @code{X}. 6740 6741@item @emph{Standard}: 6742Fortran 95 and later 6743 6744@item @emph{Class}: 6745Inquiry function 6746 6747@item @emph{Syntax}: 6748@code{RESULT = HUGE(X)} 6749 6750@item @emph{Arguments}: 6751@multitable @columnfractions .15 .70 6752@item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}. 6753@end multitable 6754 6755@item @emph{Return value}: 6756The return value is of the same type and kind as @var{X} 6757 6758@item @emph{Example}: 6759@smallexample 6760program test_huge_tiny 6761 print *, huge(0), huge(0.0), huge(0.0d0) 6762 print *, tiny(0.0), tiny(0.0d0) 6763end program test_huge_tiny 6764@end smallexample 6765@end table 6766 6767 6768 6769@node HYPOT 6770@section @code{HYPOT} --- Euclidean distance function 6771@fnindex HYPOT 6772@cindex Euclidean distance 6773 6774@table @asis 6775@item @emph{Description}: 6776@code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to 6777@math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow. 6778 6779@item @emph{Standard}: 6780Fortran 2008 and later 6781 6782@item @emph{Class}: 6783Elemental function 6784 6785@item @emph{Syntax}: 6786@code{RESULT = HYPOT(X, Y)} 6787 6788@item @emph{Arguments}: 6789@multitable @columnfractions .15 .70 6790@item @var{X} @tab The type shall be @code{REAL}. 6791@item @var{Y} @tab The type and kind type parameter shall be the same as 6792@var{X}. 6793@end multitable 6794 6795@item @emph{Return value}: 6796The return value has the same type and kind type parameter as @var{X}. 6797 6798@item @emph{Example}: 6799@smallexample 6800program test_hypot 6801 real(4) :: x = 1.e0_4, y = 0.5e0_4 6802 x = hypot(x,y) 6803end program test_hypot 6804@end smallexample 6805@end table 6806 6807 6808 6809@node IACHAR 6810@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence 6811@fnindex IACHAR 6812@cindex @acronym{ASCII} collating sequence 6813@cindex collating sequence, @acronym{ASCII} 6814@cindex conversion, to integer 6815 6816@table @asis 6817@item @emph{Description}: 6818@code{IACHAR(C)} returns the code for the @acronym{ASCII} character 6819in the first character position of @code{C}. 6820 6821@item @emph{Standard}: 6822Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 6823 6824@item @emph{Class}: 6825Elemental function 6826 6827@item @emph{Syntax}: 6828@code{RESULT = IACHAR(C [, KIND])} 6829 6830@item @emph{Arguments}: 6831@multitable @columnfractions .15 .70 6832@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 6833@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 6834expression indicating the kind parameter of the result. 6835@end multitable 6836 6837@item @emph{Return value}: 6838The return value is of type @code{INTEGER} and of kind @var{KIND}. If 6839@var{KIND} is absent, the return value is of default integer kind. 6840 6841@item @emph{Example}: 6842@smallexample 6843program test_iachar 6844 integer i 6845 i = iachar(' ') 6846end program test_iachar 6847@end smallexample 6848 6849@item @emph{Note}: 6850See @ref{ICHAR} for a discussion of converting between numerical values 6851and formatted string representations. 6852 6853@item @emph{See also}: 6854@ref{ACHAR}, @ref{CHAR}, @ref{ICHAR} 6855 6856@end table 6857 6858 6859 6860@node IALL 6861@section @code{IALL} --- Bitwise AND of array elements 6862@fnindex IALL 6863@cindex array, AND 6864@cindex bits, AND of array elements 6865 6866@table @asis 6867@item @emph{Description}: 6868Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM} 6869if the corresponding element in @var{MASK} is @code{TRUE}. 6870 6871@item @emph{Standard}: 6872Fortran 2008 and later 6873 6874@item @emph{Class}: 6875Transformational function 6876 6877@item @emph{Syntax}: 6878@multitable @columnfractions .80 6879@item @code{RESULT = IALL(ARRAY[, MASK])} 6880@item @code{RESULT = IALL(ARRAY, DIM[, MASK])} 6881@end multitable 6882 6883@item @emph{Arguments}: 6884@multitable @columnfractions .15 .70 6885@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 6886@item @var{DIM} @tab (Optional) shall be a scalar of type 6887@code{INTEGER} with a value in the range from 1 to n, where n 6888equals the rank of @var{ARRAY}. 6889@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 6890and either be a scalar or an array of the same shape as @var{ARRAY}. 6891@end multitable 6892 6893@item @emph{Return value}: 6894The result is of the same type as @var{ARRAY}. 6895 6896If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in 6897@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 6898the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 6899dimension @var{DIM} dropped is returned. 6900 6901@item @emph{Example}: 6902@smallexample 6903PROGRAM test_iall 6904 INTEGER(1) :: a(2) 6905 6906 a(1) = b'00100100' 6907 a(2) = b'01101010' 6908 6909 ! prints 00100000 6910 PRINT '(b8.8)', IALL(a) 6911END PROGRAM 6912@end smallexample 6913 6914@item @emph{See also}: 6915@ref{IANY}, @ref{IPARITY}, @ref{IAND} 6916@end table 6917 6918 6919 6920@node IAND 6921@section @code{IAND} --- Bitwise logical and 6922@fnindex IAND 6923@cindex bitwise logical and 6924@cindex logical and, bitwise 6925 6926@table @asis 6927@item @emph{Description}: 6928Bitwise logical @code{AND}. 6929 6930@item @emph{Standard}: 6931Fortran 95 and later 6932 6933@item @emph{Class}: 6934Elemental function 6935 6936@item @emph{Syntax}: 6937@code{RESULT = IAND(I, J)} 6938 6939@item @emph{Arguments}: 6940@multitable @columnfractions .15 .70 6941@item @var{I} @tab The type shall be @code{INTEGER}. 6942@item @var{J} @tab The type shall be @code{INTEGER}, of the same 6943kind as @var{I}. (As a GNU extension, different kinds are also 6944permitted.) 6945@end multitable 6946 6947@item @emph{Return value}: 6948The return type is @code{INTEGER}, of the same kind as the 6949arguments. (If the argument kinds differ, it is of the same kind as 6950the larger argument.) 6951 6952@item @emph{Example}: 6953@smallexample 6954PROGRAM test_iand 6955 INTEGER :: a, b 6956 DATA a / Z'F' /, b / Z'3' / 6957 WRITE (*,*) IAND(a, b) 6958END PROGRAM 6959@end smallexample 6960 6961@item @emph{See also}: 6962@ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 6963 6964@end table 6965 6966 6967 6968@node IANY 6969@section @code{IANY} --- Bitwise OR of array elements 6970@fnindex IANY 6971@cindex array, OR 6972@cindex bits, OR of array elements 6973 6974@table @asis 6975@item @emph{Description}: 6976Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along 6977dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 6978 6979@item @emph{Standard}: 6980Fortran 2008 and later 6981 6982@item @emph{Class}: 6983Transformational function 6984 6985@item @emph{Syntax}: 6986@multitable @columnfractions .80 6987@item @code{RESULT = IANY(ARRAY[, MASK])} 6988@item @code{RESULT = IANY(ARRAY, DIM[, MASK])} 6989@end multitable 6990 6991@item @emph{Arguments}: 6992@multitable @columnfractions .15 .70 6993@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 6994@item @var{DIM} @tab (Optional) shall be a scalar of type 6995@code{INTEGER} with a value in the range from 1 to n, where n 6996equals the rank of @var{ARRAY}. 6997@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 6998and either be a scalar or an array of the same shape as @var{ARRAY}. 6999@end multitable 7000 7001@item @emph{Return value}: 7002The result is of the same type as @var{ARRAY}. 7003 7004If @var{DIM} is absent, a scalar with the bitwise OR of all elements in 7005@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7006the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7007dimension @var{DIM} dropped is returned. 7008 7009@item @emph{Example}: 7010@smallexample 7011PROGRAM test_iany 7012 INTEGER(1) :: a(2) 7013 7014 a(1) = b'00100100' 7015 a(2) = b'01101010' 7016 7017 ! prints 01101110 7018 PRINT '(b8.8)', IANY(a) 7019END PROGRAM 7020@end smallexample 7021 7022@item @emph{See also}: 7023@ref{IPARITY}, @ref{IALL}, @ref{IOR} 7024@end table 7025 7026 7027 7028@node IARGC 7029@section @code{IARGC} --- Get the number of command line arguments 7030@fnindex IARGC 7031@cindex command-line arguments 7032@cindex command-line arguments, number of 7033@cindex arguments, to program 7034 7035@table @asis 7036@item @emph{Description}: 7037@code{IARGC} returns the number of arguments passed on the 7038command line when the containing program was invoked. 7039 7040This intrinsic routine is provided for backwards compatibility with 7041GNU Fortran 77. In new code, programmers should consider the use of 7042the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 7043standard. 7044 7045@item @emph{Standard}: 7046GNU extension 7047 7048@item @emph{Class}: 7049Function 7050 7051@item @emph{Syntax}: 7052@code{RESULT = IARGC()} 7053 7054@item @emph{Arguments}: 7055None. 7056 7057@item @emph{Return value}: 7058The number of command line arguments, type @code{INTEGER(4)}. 7059 7060@item @emph{Example}: 7061See @ref{GETARG} 7062 7063@item @emph{See also}: 7064GNU Fortran 77 compatibility subroutine: @ref{GETARG} 7065 7066Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, 7067@ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} 7068@end table 7069 7070 7071 7072@node IBCLR 7073@section @code{IBCLR} --- Clear bit 7074@fnindex IBCLR 7075@cindex bits, unset 7076@cindex bits, clear 7077 7078@table @asis 7079@item @emph{Description}: 7080@code{IBCLR} returns the value of @var{I} with the bit at position 7081@var{POS} set to zero. 7082 7083@item @emph{Standard}: 7084Fortran 95 and later 7085 7086@item @emph{Class}: 7087Elemental function 7088 7089@item @emph{Syntax}: 7090@code{RESULT = IBCLR(I, POS)} 7091 7092@item @emph{Arguments}: 7093@multitable @columnfractions .15 .70 7094@item @var{I} @tab The type shall be @code{INTEGER}. 7095@item @var{POS} @tab The type shall be @code{INTEGER}. 7096@end multitable 7097 7098@item @emph{Return value}: 7099The return value is of type @code{INTEGER} and of the same kind as 7100@var{I}. 7101 7102@item @emph{See also}: 7103@ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} 7104 7105@end table 7106 7107 7108 7109@node IBITS 7110@section @code{IBITS} --- Bit extraction 7111@fnindex IBITS 7112@cindex bits, get 7113@cindex bits, extract 7114 7115@table @asis 7116@item @emph{Description}: 7117@code{IBITS} extracts a field of length @var{LEN} from @var{I}, 7118starting from bit position @var{POS} and extending left for @var{LEN} 7119bits. The result is right-justified and the remaining bits are 7120zeroed. The value of @code{POS+LEN} must be less than or equal to the 7121value @code{BIT_SIZE(I)}. 7122 7123@item @emph{Standard}: 7124Fortran 95 and later 7125 7126@item @emph{Class}: 7127Elemental function 7128 7129@item @emph{Syntax}: 7130@code{RESULT = IBITS(I, POS, LEN)} 7131 7132@item @emph{Arguments}: 7133@multitable @columnfractions .15 .70 7134@item @var{I} @tab The type shall be @code{INTEGER}. 7135@item @var{POS} @tab The type shall be @code{INTEGER}. 7136@item @var{LEN} @tab The type shall be @code{INTEGER}. 7137@end multitable 7138 7139@item @emph{Return value}: 7140The return value is of type @code{INTEGER} and of the same kind as 7141@var{I}. 7142 7143@item @emph{See also}: 7144@ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR} 7145@end table 7146 7147 7148 7149@node IBSET 7150@section @code{IBSET} --- Set bit 7151@fnindex IBSET 7152@cindex bits, set 7153 7154@table @asis 7155@item @emph{Description}: 7156@code{IBSET} returns the value of @var{I} with the bit at position 7157@var{POS} set to one. 7158 7159@item @emph{Standard}: 7160Fortran 95 and later 7161 7162@item @emph{Class}: 7163Elemental function 7164 7165@item @emph{Syntax}: 7166@code{RESULT = IBSET(I, POS)} 7167 7168@item @emph{Arguments}: 7169@multitable @columnfractions .15 .70 7170@item @var{I} @tab The type shall be @code{INTEGER}. 7171@item @var{POS} @tab The type shall be @code{INTEGER}. 7172@end multitable 7173 7174@item @emph{Return value}: 7175The return value is of type @code{INTEGER} and of the same kind as 7176@var{I}. 7177 7178@item @emph{See also}: 7179@ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} 7180 7181@end table 7182 7183 7184 7185@node ICHAR 7186@section @code{ICHAR} --- Character-to-integer conversion function 7187@fnindex ICHAR 7188@cindex conversion, to integer 7189 7190@table @asis 7191@item @emph{Description}: 7192@code{ICHAR(C)} returns the code for the character in the first character 7193position of @code{C} in the system's native character set. 7194The correspondence between characters and their codes is not necessarily 7195the same across different GNU Fortran implementations. 7196 7197@item @emph{Standard}: 7198Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 7199 7200@item @emph{Class}: 7201Elemental function 7202 7203@item @emph{Syntax}: 7204@code{RESULT = ICHAR(C [, KIND])} 7205 7206@item @emph{Arguments}: 7207@multitable @columnfractions .15 .70 7208@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} 7209@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7210expression indicating the kind parameter of the result. 7211@end multitable 7212 7213@item @emph{Return value}: 7214The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7215@var{KIND} is absent, the return value is of default integer kind. 7216 7217@item @emph{Example}: 7218@smallexample 7219program test_ichar 7220 integer i 7221 i = ichar(' ') 7222end program test_ichar 7223@end smallexample 7224 7225@item @emph{Specific names}: 7226@multitable @columnfractions .20 .20 .20 .25 7227@item Name @tab Argument @tab Return type @tab Standard 7228@item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later 7229@end multitable 7230 7231@item @emph{Note}: 7232No intrinsic exists to convert between a numeric value and a formatted 7233character string representation -- for instance, given the 7234@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or 7235@code{REAL} value with the value 154, or vice versa. Instead, this 7236functionality is provided by internal-file I/O, as in the following 7237example: 7238@smallexample 7239program read_val 7240 integer value 7241 character(len=10) string, string2 7242 string = '154' 7243 7244 ! Convert a string to a numeric value 7245 read (string,'(I10)') value 7246 print *, value 7247 7248 ! Convert a value to a formatted string 7249 write (string2,'(I10)') value 7250 print *, string2 7251end program read_val 7252@end smallexample 7253 7254@item @emph{See also}: 7255@ref{ACHAR}, @ref{CHAR}, @ref{IACHAR} 7256 7257@end table 7258 7259 7260 7261@node IDATE 7262@section @code{IDATE} --- Get current local time subroutine (day/month/year) 7263@fnindex IDATE 7264@cindex date, current 7265@cindex current date 7266 7267@table @asis 7268@item @emph{Description}: 7269@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the 7270current local time. The day (in the range 1-31), month (in the range 1-12), 7271and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively. 7272The year has four significant digits. 7273 7274@item @emph{Standard}: 7275GNU extension 7276 7277@item @emph{Class}: 7278Subroutine 7279 7280@item @emph{Syntax}: 7281@code{CALL IDATE(VALUES)} 7282 7283@item @emph{Arguments}: 7284@multitable @columnfractions .15 .70 7285@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and 7286the kind shall be the default integer kind. 7287@end multitable 7288 7289@item @emph{Return value}: 7290Does not return anything. 7291 7292@item @emph{Example}: 7293@smallexample 7294program test_idate 7295 integer, dimension(3) :: tarray 7296 call idate(tarray) 7297 print *, tarray(1) 7298 print *, tarray(2) 7299 print *, tarray(3) 7300end program test_idate 7301@end smallexample 7302@end table 7303 7304 7305 7306@node IEOR 7307@section @code{IEOR} --- Bitwise logical exclusive or 7308@fnindex IEOR 7309@cindex bitwise logical exclusive or 7310@cindex logical exclusive or, bitwise 7311 7312@table @asis 7313@item @emph{Description}: 7314@code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and 7315@var{J}. 7316 7317@item @emph{Standard}: 7318Fortran 95 and later 7319 7320@item @emph{Class}: 7321Elemental function 7322 7323@item @emph{Syntax}: 7324@code{RESULT = IEOR(I, J)} 7325 7326@item @emph{Arguments}: 7327@multitable @columnfractions .15 .70 7328@item @var{I} @tab The type shall be @code{INTEGER}. 7329@item @var{J} @tab The type shall be @code{INTEGER}, of the same 7330kind as @var{I}. (As a GNU extension, different kinds are also 7331permitted.) 7332@end multitable 7333 7334@item @emph{Return value}: 7335The return type is @code{INTEGER}, of the same kind as the 7336arguments. (If the argument kinds differ, it is of the same kind as 7337the larger argument.) 7338 7339@item @emph{See also}: 7340@ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 7341@end table 7342 7343 7344 7345@node IERRNO 7346@section @code{IERRNO} --- Get the last system error number 7347@fnindex IERRNO 7348@cindex system, error handling 7349 7350@table @asis 7351@item @emph{Description}: 7352Returns the last system error number, as given by the C @code{errno} 7353variable. 7354 7355@item @emph{Standard}: 7356GNU extension 7357 7358@item @emph{Class}: 7359Function 7360 7361@item @emph{Syntax}: 7362@code{RESULT = IERRNO()} 7363 7364@item @emph{Arguments}: 7365None. 7366 7367@item @emph{Return value}: 7368The return value is of type @code{INTEGER} and of the default integer 7369kind. 7370 7371@item @emph{See also}: 7372@ref{PERROR} 7373@end table 7374 7375 7376 7377@node IMAGE_INDEX 7378@section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index 7379@fnindex IMAGE_INDEX 7380@cindex coarray, @code{IMAGE_INDEX} 7381@cindex images, cosubscript to image index conversion 7382 7383@table @asis 7384@item @emph{Description}: 7385Returns the image index belonging to a cosubscript. 7386 7387@item @emph{Standard}: 7388Fortran 2008 and later 7389 7390@item @emph{Class}: 7391Inquiry function. 7392 7393@item @emph{Syntax}: 7394@code{RESULT = IMAGE_INDEX(COARRAY, SUB)} 7395 7396@item @emph{Arguments}: None. 7397@multitable @columnfractions .15 .70 7398@item @var{COARRAY} @tab Coarray of any type. 7399@item @var{SUB} @tab default integer rank-1 array of a size equal to 7400the corank of @var{COARRAY}. 7401@end multitable 7402 7403 7404@item @emph{Return value}: 7405Scalar default integer with the value of the image index which corresponds 7406to the cosubscripts. For invalid cosubscripts the result is zero. 7407 7408@item @emph{Example}: 7409@smallexample 7410INTEGER :: array[2,-1:4,8,*] 7411! Writes 28 (or 0 if there are fewer than 28 images) 7412WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1]) 7413@end smallexample 7414 7415@item @emph{See also}: 7416@ref{THIS_IMAGE}, @ref{NUM_IMAGES} 7417@end table 7418 7419 7420 7421@node INDEX intrinsic 7422@section @code{INDEX} --- Position of a substring within a string 7423@fnindex INDEX 7424@cindex substring position 7425@cindex string, find substring 7426 7427@table @asis 7428@item @emph{Description}: 7429Returns the position of the start of the first occurrence of string 7430@var{SUBSTRING} as a substring in @var{STRING}, counting from one. If 7431@var{SUBSTRING} is not present in @var{STRING}, zero is returned. If 7432the @var{BACK} argument is present and true, the return value is the 7433start of the last occurrence rather than the first. 7434 7435@item @emph{Standard}: 7436Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 7437 7438@item @emph{Class}: 7439Elemental function 7440 7441@item @emph{Syntax}: 7442@code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])} 7443 7444@item @emph{Arguments}: 7445@multitable @columnfractions .15 .70 7446@item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with 7447@code{INTENT(IN)} 7448@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with 7449@code{INTENT(IN)} 7450@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with 7451@code{INTENT(IN)} 7452@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7453expression indicating the kind parameter of the result. 7454@end multitable 7455 7456@item @emph{Return value}: 7457The return value is of type @code{INTEGER} and of kind @var{KIND}. If 7458@var{KIND} is absent, the return value is of default integer kind. 7459 7460@item @emph{Specific names}: 7461@multitable @columnfractions .20 .20 .20 .25 7462@item Name @tab Argument @tab Return type @tab Standard 7463@item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later 7464@end multitable 7465 7466@item @emph{See also}: 7467@ref{SCAN}, @ref{VERIFY} 7468@end table 7469 7470 7471 7472@node INT 7473@section @code{INT} --- Convert to integer type 7474@fnindex INT 7475@fnindex IFIX 7476@fnindex IDINT 7477@cindex conversion, to integer 7478 7479@table @asis 7480@item @emph{Description}: 7481Convert to integer type 7482 7483@item @emph{Standard}: 7484Fortran 77 and later 7485 7486@item @emph{Class}: 7487Elemental function 7488 7489@item @emph{Syntax}: 7490@code{RESULT = INT(A [, KIND))} 7491 7492@item @emph{Arguments}: 7493@multitable @columnfractions .15 .70 7494@item @var{A} @tab Shall be of type @code{INTEGER}, 7495@code{REAL}, or @code{COMPLEX}. 7496@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 7497expression indicating the kind parameter of the result. 7498@end multitable 7499 7500@item @emph{Return value}: 7501These functions return a @code{INTEGER} variable or array under 7502the following rules: 7503 7504@table @asis 7505@item (A) 7506If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} 7507@item (B) 7508If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} 7509equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer 7510whose magnitude is the largest integer that does not exceed the magnitude 7511of @var{A} and whose sign is the same as the sign of @var{A}. 7512@item (C) 7513If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}. 7514@end table 7515 7516@item @emph{Example}: 7517@smallexample 7518program test_int 7519 integer :: i = 42 7520 complex :: z = (-3.7, 1.0) 7521 print *, int(i) 7522 print *, int(z), int(z,8) 7523end program 7524@end smallexample 7525 7526@item @emph{Specific names}: 7527@multitable @columnfractions .20 .20 .20 .25 7528@item Name @tab Argument @tab Return type @tab Standard 7529@item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 7530@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later 7531@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later 7532@end multitable 7533 7534@end table 7535 7536 7537@node INT2 7538@section @code{INT2} --- Convert to 16-bit integer type 7539@fnindex INT2 7540@fnindex SHORT 7541@cindex conversion, to integer 7542 7543@table @asis 7544@item @emph{Description}: 7545Convert to a @code{KIND=2} integer type. This is equivalent to the 7546standard @code{INT} intrinsic with an optional argument of 7547@code{KIND=2}, and is only included for backwards compatibility. 7548 7549The @code{SHORT} intrinsic is equivalent to @code{INT2}. 7550 7551@item @emph{Standard}: 7552GNU extension 7553 7554@item @emph{Class}: 7555Elemental function 7556 7557@item @emph{Syntax}: 7558@code{RESULT = INT2(A)} 7559 7560@item @emph{Arguments}: 7561@multitable @columnfractions .15 .70 7562@item @var{A} @tab Shall be of type @code{INTEGER}, 7563@code{REAL}, or @code{COMPLEX}. 7564@end multitable 7565 7566@item @emph{Return value}: 7567The return value is a @code{INTEGER(2)} variable. 7568 7569@item @emph{See also}: 7570@ref{INT}, @ref{INT8}, @ref{LONG} 7571@end table 7572 7573 7574 7575@node INT8 7576@section @code{INT8} --- Convert to 64-bit integer type 7577@fnindex INT8 7578@cindex conversion, to integer 7579 7580@table @asis 7581@item @emph{Description}: 7582Convert to a @code{KIND=8} integer type. This is equivalent to the 7583standard @code{INT} intrinsic with an optional argument of 7584@code{KIND=8}, and is only included for backwards compatibility. 7585 7586@item @emph{Standard}: 7587GNU extension 7588 7589@item @emph{Class}: 7590Elemental function 7591 7592@item @emph{Syntax}: 7593@code{RESULT = INT8(A)} 7594 7595@item @emph{Arguments}: 7596@multitable @columnfractions .15 .70 7597@item @var{A} @tab Shall be of type @code{INTEGER}, 7598@code{REAL}, or @code{COMPLEX}. 7599@end multitable 7600 7601@item @emph{Return value}: 7602The return value is a @code{INTEGER(8)} variable. 7603 7604@item @emph{See also}: 7605@ref{INT}, @ref{INT2}, @ref{LONG} 7606@end table 7607 7608 7609 7610@node IOR 7611@section @code{IOR} --- Bitwise logical or 7612@fnindex IOR 7613@cindex bitwise logical or 7614@cindex logical or, bitwise 7615 7616@table @asis 7617@item @emph{Description}: 7618@code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and 7619@var{J}. 7620 7621@item @emph{Standard}: 7622Fortran 95 and later 7623 7624@item @emph{Class}: 7625Elemental function 7626 7627@item @emph{Syntax}: 7628@code{RESULT = IOR(I, J)} 7629 7630@item @emph{Arguments}: 7631@multitable @columnfractions .15 .70 7632@item @var{I} @tab The type shall be @code{INTEGER}. 7633@item @var{J} @tab The type shall be @code{INTEGER}, of the same 7634kind as @var{I}. (As a GNU extension, different kinds are also 7635permitted.) 7636@end multitable 7637 7638@item @emph{Return value}: 7639The return type is @code{INTEGER}, of the same kind as the 7640arguments. (If the argument kinds differ, it is of the same kind as 7641the larger argument.) 7642 7643@item @emph{See also}: 7644@ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} 7645@end table 7646 7647 7648 7649@node IPARITY 7650@section @code{IPARITY} --- Bitwise XOR of array elements 7651@fnindex IPARITY 7652@cindex array, parity 7653@cindex array, XOR 7654@cindex bits, XOR of array elements 7655 7656@table @asis 7657@item @emph{Description}: 7658Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along 7659dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. 7660 7661@item @emph{Standard}: 7662Fortran 2008 and later 7663 7664@item @emph{Class}: 7665Transformational function 7666 7667@item @emph{Syntax}: 7668@multitable @columnfractions .80 7669@item @code{RESULT = IPARITY(ARRAY[, MASK])} 7670@item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])} 7671@end multitable 7672 7673@item @emph{Arguments}: 7674@multitable @columnfractions .15 .70 7675@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} 7676@item @var{DIM} @tab (Optional) shall be a scalar of type 7677@code{INTEGER} with a value in the range from 1 to n, where n 7678equals the rank of @var{ARRAY}. 7679@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 7680and either be a scalar or an array of the same shape as @var{ARRAY}. 7681@end multitable 7682 7683@item @emph{Return value}: 7684The result is of the same type as @var{ARRAY}. 7685 7686If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in 7687@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 7688the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 7689dimension @var{DIM} dropped is returned. 7690 7691@item @emph{Example}: 7692@smallexample 7693PROGRAM test_iparity 7694 INTEGER(1) :: a(2) 7695 7696 a(1) = b'00100100' 7697 a(2) = b'01101010' 7698 7699 ! prints 01001110 7700 PRINT '(b8.8)', IPARITY(a) 7701END PROGRAM 7702@end smallexample 7703 7704@item @emph{See also}: 7705@ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY} 7706@end table 7707 7708 7709 7710@node IRAND 7711@section @code{IRAND} --- Integer pseudo-random number 7712@fnindex IRAND 7713@cindex random number generation 7714 7715@table @asis 7716@item @emph{Description}: 7717@code{IRAND(FLAG)} returns a pseudo-random number from a uniform 7718distribution between 0 and a system-dependent limit (which is in most 7719cases 2147483647). If @var{FLAG} is 0, the next number 7720in the current sequence is returned; if @var{FLAG} is 1, the generator 7721is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 7722it is used as a new seed with @code{SRAND}. 7723 7724This intrinsic routine is provided for backwards compatibility with 7725GNU Fortran 77. It implements a simple modulo generator as provided 7726by @command{g77}. For new code, one should consider the use of 7727@ref{RANDOM_NUMBER} as it implements a superior algorithm. 7728 7729@item @emph{Standard}: 7730GNU extension 7731 7732@item @emph{Class}: 7733Function 7734 7735@item @emph{Syntax}: 7736@code{RESULT = IRAND(I)} 7737 7738@item @emph{Arguments}: 7739@multitable @columnfractions .15 .70 7740@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 7741@end multitable 7742 7743@item @emph{Return value}: 7744The return value is of @code{INTEGER(kind=4)} type. 7745 7746@item @emph{Example}: 7747@smallexample 7748program test_irand 7749 integer,parameter :: seed = 86456 7750 7751 call srand(seed) 7752 print *, irand(), irand(), irand(), irand() 7753 print *, irand(seed), irand(), irand(), irand() 7754end program test_irand 7755@end smallexample 7756 7757@end table 7758 7759 7760 7761@node IS_IOSTAT_END 7762@section @code{IS_IOSTAT_END} --- Test for end-of-file value 7763@fnindex IS_IOSTAT_END 7764@cindex @code{IOSTAT}, end of file 7765 7766@table @asis 7767@item @emph{Description}: 7768@code{IS_IOSTAT_END} tests whether an variable has the value of the I/O 7769status ``end of file''. The function is equivalent to comparing the variable 7770with the @code{IOSTAT_END} parameter of the intrinsic module 7771@code{ISO_FORTRAN_ENV}. 7772 7773@item @emph{Standard}: 7774Fortran 2003 and later 7775 7776@item @emph{Class}: 7777Elemental function 7778 7779@item @emph{Syntax}: 7780@code{RESULT = IS_IOSTAT_END(I)} 7781 7782@item @emph{Arguments}: 7783@multitable @columnfractions .15 .70 7784@item @var{I} @tab Shall be of the type @code{INTEGER}. 7785@end multitable 7786 7787@item @emph{Return value}: 7788Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 7789@var{I} has the value which indicates an end of file condition for 7790@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 7791 7792@item @emph{Example}: 7793@smallexample 7794PROGRAM iostat 7795 IMPLICIT NONE 7796 INTEGER :: stat, i 7797 OPEN(88, FILE='test.dat') 7798 READ(88, *, IOSTAT=stat) i 7799 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE' 7800END PROGRAM 7801@end smallexample 7802@end table 7803 7804 7805 7806@node IS_IOSTAT_EOR 7807@section @code{IS_IOSTAT_EOR} --- Test for end-of-record value 7808@fnindex IS_IOSTAT_EOR 7809@cindex @code{IOSTAT}, end of record 7810 7811@table @asis 7812@item @emph{Description}: 7813@code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O 7814status ``end of record''. The function is equivalent to comparing the 7815variable with the @code{IOSTAT_EOR} parameter of the intrinsic module 7816@code{ISO_FORTRAN_ENV}. 7817 7818@item @emph{Standard}: 7819Fortran 2003 and later 7820 7821@item @emph{Class}: 7822Elemental function 7823 7824@item @emph{Syntax}: 7825@code{RESULT = IS_IOSTAT_EOR(I)} 7826 7827@item @emph{Arguments}: 7828@multitable @columnfractions .15 .70 7829@item @var{I} @tab Shall be of the type @code{INTEGER}. 7830@end multitable 7831 7832@item @emph{Return value}: 7833Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if 7834@var{I} has the value which indicates an end of file condition for 7835@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. 7836 7837@item @emph{Example}: 7838@smallexample 7839PROGRAM iostat 7840 IMPLICIT NONE 7841 INTEGER :: stat, i(50) 7842 OPEN(88, FILE='test.dat', FORM='UNFORMATTED') 7843 READ(88, IOSTAT=stat) i 7844 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD' 7845END PROGRAM 7846@end smallexample 7847@end table 7848 7849 7850 7851@node ISATTY 7852@section @code{ISATTY} --- Whether a unit is a terminal device. 7853@fnindex ISATTY 7854@cindex system, terminal 7855 7856@table @asis 7857@item @emph{Description}: 7858Determine whether a unit is connected to a terminal device. 7859 7860@item @emph{Standard}: 7861GNU extension 7862 7863@item @emph{Class}: 7864Function 7865 7866@item @emph{Syntax}: 7867@code{RESULT = ISATTY(UNIT)} 7868 7869@item @emph{Arguments}: 7870@multitable @columnfractions .15 .70 7871@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 7872@end multitable 7873 7874@item @emph{Return value}: 7875Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal 7876device, @code{.FALSE.} otherwise. 7877 7878@item @emph{Example}: 7879@smallexample 7880PROGRAM test_isatty 7881 INTEGER(kind=1) :: unit 7882 DO unit = 1, 10 7883 write(*,*) isatty(unit=unit) 7884 END DO 7885END PROGRAM 7886@end smallexample 7887@item @emph{See also}: 7888@ref{TTYNAM} 7889@end table 7890 7891 7892 7893@node ISHFT 7894@section @code{ISHFT} --- Shift bits 7895@fnindex ISHFT 7896@cindex bits, shift 7897 7898@table @asis 7899@item @emph{Description}: 7900@code{ISHFT} returns a value corresponding to @var{I} with all of the 7901bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than 7902zero corresponds to a left shift, a value of zero corresponds to no 7903shift, and a value less than zero corresponds to a right shift. If the 7904absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the 7905value is undefined. Bits shifted out from the left end or right end are 7906lost; zeros are shifted in from the opposite end. 7907 7908@item @emph{Standard}: 7909Fortran 95 and later 7910 7911@item @emph{Class}: 7912Elemental function 7913 7914@item @emph{Syntax}: 7915@code{RESULT = ISHFT(I, SHIFT)} 7916 7917@item @emph{Arguments}: 7918@multitable @columnfractions .15 .70 7919@item @var{I} @tab The type shall be @code{INTEGER}. 7920@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 7921@end multitable 7922 7923@item @emph{Return value}: 7924The return value is of type @code{INTEGER} and of the same kind as 7925@var{I}. 7926 7927@item @emph{See also}: 7928@ref{ISHFTC} 7929@end table 7930 7931 7932 7933@node ISHFTC 7934@section @code{ISHFTC} --- Shift bits circularly 7935@fnindex ISHFTC 7936@cindex bits, shift circular 7937 7938@table @asis 7939@item @emph{Description}: 7940@code{ISHFTC} returns a value corresponding to @var{I} with the 7941rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that 7942is, bits shifted out one end are shifted into the opposite end. A value 7943of @var{SHIFT} greater than zero corresponds to a left shift, a value of 7944zero corresponds to no shift, and a value less than zero corresponds to 7945a right shift. The absolute value of @var{SHIFT} must be less than 7946@var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be 7947equivalent to @code{BIT_SIZE(I)}. 7948 7949@item @emph{Standard}: 7950Fortran 95 and later 7951 7952@item @emph{Class}: 7953Elemental function 7954 7955@item @emph{Syntax}: 7956@code{RESULT = ISHFTC(I, SHIFT [, SIZE])} 7957 7958@item @emph{Arguments}: 7959@multitable @columnfractions .15 .70 7960@item @var{I} @tab The type shall be @code{INTEGER}. 7961@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 7962@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER}; 7963the value must be greater than zero and less than or equal to 7964@code{BIT_SIZE(I)}. 7965@end multitable 7966 7967@item @emph{Return value}: 7968The return value is of type @code{INTEGER} and of the same kind as 7969@var{I}. 7970 7971@item @emph{See also}: 7972@ref{ISHFT} 7973@end table 7974 7975 7976 7977@node ISNAN 7978@section @code{ISNAN} --- Test for a NaN 7979@fnindex ISNAN 7980@cindex IEEE, ISNAN 7981 7982@table @asis 7983@item @emph{Description}: 7984@code{ISNAN} tests whether a floating-point value is an IEEE 7985Not-a-Number (NaN). 7986@item @emph{Standard}: 7987GNU extension 7988 7989@item @emph{Class}: 7990Elemental function 7991 7992@item @emph{Syntax}: 7993@code{ISNAN(X)} 7994 7995@item @emph{Arguments}: 7996@multitable @columnfractions .15 .70 7997@item @var{X} @tab Variable of the type @code{REAL}. 7998 7999@end multitable 8000 8001@item @emph{Return value}: 8002Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE} 8003if @var{X} is a NaN and @code{FALSE} otherwise. 8004 8005@item @emph{Example}: 8006@smallexample 8007program test_nan 8008 implicit none 8009 real :: x 8010 x = -1.0 8011 x = sqrt(x) 8012 if (isnan(x)) stop '"x" is a NaN' 8013end program test_nan 8014@end smallexample 8015@end table 8016 8017 8018 8019@node ITIME 8020@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) 8021@fnindex ITIME 8022@cindex time, current 8023@cindex current time 8024 8025@table @asis 8026@item @emph{Description}: 8027@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the 8028current local time. The hour (in the range 1-24), minute (in the range 1-60), 8029and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES}, 8030respectively. 8031 8032@item @emph{Standard}: 8033GNU extension 8034 8035@item @emph{Class}: 8036Subroutine 8037 8038@item @emph{Syntax}: 8039@code{CALL ITIME(VALUES)} 8040 8041@item @emph{Arguments}: 8042@multitable @columnfractions .15 .70 8043@item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} 8044and the kind shall be the default integer kind. 8045@end multitable 8046 8047@item @emph{Return value}: 8048Does not return anything. 8049 8050 8051@item @emph{Example}: 8052@smallexample 8053program test_itime 8054 integer, dimension(3) :: tarray 8055 call itime(tarray) 8056 print *, tarray(1) 8057 print *, tarray(2) 8058 print *, tarray(3) 8059end program test_itime 8060@end smallexample 8061@end table 8062 8063 8064 8065@node KILL 8066@section @code{KILL} --- Send a signal to a process 8067@fnindex KILL 8068 8069@table @asis 8070@item @emph{Description}: 8071@item @emph{Standard}: 8072Sends the signal specified by @var{SIGNAL} to the process @var{PID}. 8073See @code{kill(2)}. 8074 8075This intrinsic is provided in both subroutine and function forms; however, 8076only one form can be used in any given program unit. 8077 8078@item @emph{Class}: 8079Subroutine, function 8080 8081@item @emph{Syntax}: 8082@multitable @columnfractions .80 8083@item @code{CALL KILL(C, VALUE [, STATUS])} 8084@item @code{STATUS = KILL(C, VALUE)} 8085@end multitable 8086 8087@item @emph{Arguments}: 8088@multitable @columnfractions .15 .70 8089@item @var{C} @tab Shall be a scalar @code{INTEGER}, with 8090@code{INTENT(IN)} 8091@item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with 8092@code{INTENT(IN)} 8093@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or 8094@code{INTEGER(8)}. Returns 0 on success, or a system-specific error code 8095otherwise. 8096@end multitable 8097 8098@item @emph{See also}: 8099@ref{ABORT}, @ref{EXIT} 8100@end table 8101 8102 8103 8104@node KIND 8105@section @code{KIND} --- Kind of an entity 8106@fnindex KIND 8107@cindex kind 8108 8109@table @asis 8110@item @emph{Description}: 8111@code{KIND(X)} returns the kind value of the entity @var{X}. 8112 8113@item @emph{Standard}: 8114Fortran 95 and later 8115 8116@item @emph{Class}: 8117Inquiry function 8118 8119@item @emph{Syntax}: 8120@code{K = KIND(X)} 8121 8122@item @emph{Arguments}: 8123@multitable @columnfractions .15 .70 8124@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER}, 8125@code{REAL}, @code{COMPLEX} or @code{CHARACTER}. 8126@end multitable 8127 8128@item @emph{Return value}: 8129The return value is a scalar of type @code{INTEGER} and of the default 8130integer kind. 8131 8132@item @emph{Example}: 8133@smallexample 8134program test_kind 8135 integer,parameter :: kc = kind(' ') 8136 integer,parameter :: kl = kind(.true.) 8137 8138 print *, "The default character kind is ", kc 8139 print *, "The default logical kind is ", kl 8140end program test_kind 8141@end smallexample 8142 8143@end table 8144 8145 8146 8147@node LBOUND 8148@section @code{LBOUND} --- Lower dimension bounds of an array 8149@fnindex LBOUND 8150@cindex array, lower bound 8151 8152@table @asis 8153@item @emph{Description}: 8154Returns the lower bounds of an array, or a single lower bound 8155along the @var{DIM} dimension. 8156@item @emph{Standard}: 8157Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 8158 8159@item @emph{Class}: 8160Inquiry function 8161 8162@item @emph{Syntax}: 8163@code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])} 8164 8165@item @emph{Arguments}: 8166@multitable @columnfractions .15 .70 8167@item @var{ARRAY} @tab Shall be an array, of any type. 8168@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 8169@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8170expression indicating the kind parameter of the result. 8171@end multitable 8172 8173@item @emph{Return value}: 8174The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8175@var{KIND} is absent, the return value is of default integer kind. 8176If @var{DIM} is absent, the result is an array of the lower bounds of 8177@var{ARRAY}. If @var{DIM} is present, the result is a scalar 8178corresponding to the lower bound of the array along that dimension. If 8179@var{ARRAY} is an expression rather than a whole array or array 8180structure component, or if it has a zero extent along the relevant 8181dimension, the lower bound is taken to be 1. 8182 8183@item @emph{See also}: 8184@ref{UBOUND}, @ref{LCOBOUND} 8185@end table 8186 8187 8188 8189@node LCOBOUND 8190@section @code{LCOBOUND} --- Lower codimension bounds of an array 8191@fnindex LCOBOUND 8192@cindex coarray, lower bound 8193 8194@table @asis 8195@item @emph{Description}: 8196Returns the lower bounds of a coarray, or a single lower cobound 8197along the @var{DIM} codimension. 8198@item @emph{Standard}: 8199Fortran 2008 and later 8200 8201@item @emph{Class}: 8202Inquiry function 8203 8204@item @emph{Syntax}: 8205@code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])} 8206 8207@item @emph{Arguments}: 8208@multitable @columnfractions .15 .70 8209@item @var{ARRAY} @tab Shall be an coarray, of any type. 8210@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 8211@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8212expression indicating the kind parameter of the result. 8213@end multitable 8214 8215@item @emph{Return value}: 8216The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8217@var{KIND} is absent, the return value is of default integer kind. 8218If @var{DIM} is absent, the result is an array of the lower cobounds of 8219@var{COARRAY}. If @var{DIM} is present, the result is a scalar 8220corresponding to the lower cobound of the array along that codimension. 8221 8222@item @emph{See also}: 8223@ref{UCOBOUND}, @ref{LBOUND} 8224@end table 8225 8226 8227 8228@node LEADZ 8229@section @code{LEADZ} --- Number of leading zero bits of an integer 8230@fnindex LEADZ 8231@cindex zero bits 8232 8233@table @asis 8234@item @emph{Description}: 8235@code{LEADZ} returns the number of leading zero bits of an integer. 8236 8237@item @emph{Standard}: 8238Fortran 2008 and later 8239 8240@item @emph{Class}: 8241Elemental function 8242 8243@item @emph{Syntax}: 8244@code{RESULT = LEADZ(I)} 8245 8246@item @emph{Arguments}: 8247@multitable @columnfractions .15 .70 8248@item @var{I} @tab Shall be of type @code{INTEGER}. 8249@end multitable 8250 8251@item @emph{Return value}: 8252The type of the return value is the default @code{INTEGER}. 8253If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 8254 8255@item @emph{Example}: 8256@smallexample 8257PROGRAM test_leadz 8258 WRITE (*,*) BIT_SIZE(1) ! prints 32 8259 WRITE (*,*) LEADZ(1) ! prints 31 8260END PROGRAM 8261@end smallexample 8262 8263@item @emph{See also}: 8264@ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR} 8265@end table 8266 8267 8268 8269@node LEN 8270@section @code{LEN} --- Length of a character entity 8271@fnindex LEN 8272@cindex string, length 8273 8274@table @asis 8275@item @emph{Description}: 8276Returns the length of a character string. If @var{STRING} is an array, 8277the length of an element of @var{STRING} is returned. Note that 8278@var{STRING} need not be defined when this intrinsic is invoked, since 8279only the length, not the content, of @var{STRING} is needed. 8280 8281@item @emph{Standard}: 8282Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later 8283 8284@item @emph{Class}: 8285Inquiry function 8286 8287@item @emph{Syntax}: 8288@code{L = LEN(STRING [, KIND])} 8289 8290@item @emph{Arguments}: 8291@multitable @columnfractions .15 .70 8292@item @var{STRING} @tab Shall be a scalar or array of type 8293@code{CHARACTER}, with @code{INTENT(IN)} 8294@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8295expression indicating the kind parameter of the result. 8296@end multitable 8297 8298@item @emph{Return value}: 8299The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8300@var{KIND} is absent, the return value is of default integer kind. 8301 8302 8303@item @emph{Specific names}: 8304@multitable @columnfractions .20 .20 .20 .25 8305@item Name @tab Argument @tab Return type @tab Standard 8306@item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later 8307@end multitable 8308 8309 8310@item @emph{See also}: 8311@ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR} 8312@end table 8313 8314 8315 8316@node LEN_TRIM 8317@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters 8318@fnindex LEN_TRIM 8319@cindex string, length, without trailing whitespace 8320 8321@table @asis 8322@item @emph{Description}: 8323Returns the length of a character string, ignoring any trailing blanks. 8324 8325@item @emph{Standard}: 8326Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 8327 8328@item @emph{Class}: 8329Elemental function 8330 8331@item @emph{Syntax}: 8332@code{RESULT = LEN_TRIM(STRING [, KIND])} 8333 8334@item @emph{Arguments}: 8335@multitable @columnfractions .15 .70 8336@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 8337with @code{INTENT(IN)} 8338@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8339expression indicating the kind parameter of the result. 8340@end multitable 8341 8342@item @emph{Return value}: 8343The return value is of type @code{INTEGER} and of kind @var{KIND}. If 8344@var{KIND} is absent, the return value is of default integer kind. 8345 8346@item @emph{See also}: 8347@ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR} 8348@end table 8349 8350 8351 8352@node LGE 8353@section @code{LGE} --- Lexical greater than or equal 8354@fnindex LGE 8355@cindex lexical comparison of strings 8356@cindex string, comparison 8357 8358@table @asis 8359@item @emph{Description}: 8360Determines whether one string is lexically greater than or equal to 8361another string, where the two strings are interpreted as containing 8362ASCII character codes. If the String A and String B are not the same 8363length, the shorter is compared as if spaces were appended to it to form 8364a value that has the same length as the longer. 8365 8366In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 8367@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 8368operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 8369that the latter use the processor's character ordering (which is not 8370ASCII on some targets), whereas the former always use the ASCII 8371ordering. 8372 8373@item @emph{Standard}: 8374Fortran 77 and later 8375 8376@item @emph{Class}: 8377Elemental function 8378 8379@item @emph{Syntax}: 8380@code{RESULT = LGE(STRING_A, STRING_B)} 8381 8382@item @emph{Arguments}: 8383@multitable @columnfractions .15 .70 8384@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 8385@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 8386@end multitable 8387 8388@item @emph{Return value}: 8389Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.} 8390otherwise, based on the ASCII ordering. 8391 8392@item @emph{Specific names}: 8393@multitable @columnfractions .20 .20 .20 .25 8394@item Name @tab Argument @tab Return type @tab Standard 8395@item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 8396@end multitable 8397 8398@item @emph{See also}: 8399@ref{LGT}, @ref{LLE}, @ref{LLT} 8400@end table 8401 8402 8403 8404@node LGT 8405@section @code{LGT} --- Lexical greater than 8406@fnindex LGT 8407@cindex lexical comparison of strings 8408@cindex string, comparison 8409 8410@table @asis 8411@item @emph{Description}: 8412Determines whether one string is lexically greater than another string, 8413where the two strings are interpreted as containing ASCII character 8414codes. If the String A and String B are not the same length, the 8415shorter is compared as if spaces were appended to it to form a value 8416that has the same length as the longer. 8417 8418In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 8419@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 8420operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 8421that the latter use the processor's character ordering (which is not 8422ASCII on some targets), whereas the former always use the ASCII 8423ordering. 8424 8425@item @emph{Standard}: 8426Fortran 77 and later 8427 8428@item @emph{Class}: 8429Elemental function 8430 8431@item @emph{Syntax}: 8432@code{RESULT = LGT(STRING_A, STRING_B)} 8433 8434@item @emph{Arguments}: 8435@multitable @columnfractions .15 .70 8436@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 8437@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 8438@end multitable 8439 8440@item @emph{Return value}: 8441Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.} 8442otherwise, based on the ASCII ordering. 8443 8444@item @emph{Specific names}: 8445@multitable @columnfractions .20 .20 .20 .25 8446@item Name @tab Argument @tab Return type @tab Standard 8447@item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 8448@end multitable 8449 8450@item @emph{See also}: 8451@ref{LGE}, @ref{LLE}, @ref{LLT} 8452@end table 8453 8454 8455 8456@node LINK 8457@section @code{LINK} --- Create a hard link 8458@fnindex LINK 8459@cindex file system, create link 8460@cindex file system, hard link 8461 8462@table @asis 8463@item @emph{Description}: 8464Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null 8465character (@code{CHAR(0)}) can be used to mark the end of the names in 8466@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 8467names are ignored. If the @var{STATUS} argument is supplied, it 8468contains 0 on success or a nonzero error code upon return; see 8469@code{link(2)}. 8470 8471This intrinsic is provided in both subroutine and function forms; 8472however, only one form can be used in any given program unit. 8473 8474@item @emph{Standard}: 8475GNU extension 8476 8477@item @emph{Class}: 8478Subroutine, function 8479 8480@item @emph{Syntax}: 8481@multitable @columnfractions .80 8482@item @code{CALL LINK(PATH1, PATH2 [, STATUS])} 8483@item @code{STATUS = LINK(PATH1, PATH2)} 8484@end multitable 8485 8486@item @emph{Arguments}: 8487@multitable @columnfractions .15 .70 8488@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 8489@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 8490@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 8491@end multitable 8492 8493@item @emph{See also}: 8494@ref{SYMLNK}, @ref{UNLINK} 8495@end table 8496 8497 8498 8499@node LLE 8500@section @code{LLE} --- Lexical less than or equal 8501@fnindex LLE 8502@cindex lexical comparison of strings 8503@cindex string, comparison 8504 8505@table @asis 8506@item @emph{Description}: 8507Determines whether one string is lexically less than or equal to another 8508string, where the two strings are interpreted as containing ASCII 8509character codes. If the String A and String B are not the same length, 8510the shorter is compared as if spaces were appended to it to form a value 8511that has the same length as the longer. 8512 8513In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 8514@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 8515operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 8516that the latter use the processor's character ordering (which is not 8517ASCII on some targets), whereas the former always use the ASCII 8518ordering. 8519 8520@item @emph{Standard}: 8521Fortran 77 and later 8522 8523@item @emph{Class}: 8524Elemental function 8525 8526@item @emph{Syntax}: 8527@code{RESULT = LLE(STRING_A, STRING_B)} 8528 8529@item @emph{Arguments}: 8530@multitable @columnfractions .15 .70 8531@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 8532@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 8533@end multitable 8534 8535@item @emph{Return value}: 8536Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.} 8537otherwise, based on the ASCII ordering. 8538 8539@item @emph{Specific names}: 8540@multitable @columnfractions .20 .20 .20 .25 8541@item Name @tab Argument @tab Return type @tab Standard 8542@item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 8543@end multitable 8544 8545@item @emph{See also}: 8546@ref{LGE}, @ref{LGT}, @ref{LLT} 8547@end table 8548 8549 8550 8551@node LLT 8552@section @code{LLT} --- Lexical less than 8553@fnindex LLT 8554@cindex lexical comparison of strings 8555@cindex string, comparison 8556 8557@table @asis 8558@item @emph{Description}: 8559Determines whether one string is lexically less than another string, 8560where the two strings are interpreted as containing ASCII character 8561codes. If the String A and String B are not the same length, the 8562shorter is compared as if spaces were appended to it to form a value 8563that has the same length as the longer. 8564 8565In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, 8566@code{LLE}, and @code{LLT} differ from the corresponding intrinsic 8567operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in 8568that the latter use the processor's character ordering (which is not 8569ASCII on some targets), whereas the former always use the ASCII 8570ordering. 8571 8572@item @emph{Standard}: 8573Fortran 77 and later 8574 8575@item @emph{Class}: 8576Elemental function 8577 8578@item @emph{Syntax}: 8579@code{RESULT = LLT(STRING_A, STRING_B)} 8580 8581@item @emph{Arguments}: 8582@multitable @columnfractions .15 .70 8583@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. 8584@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. 8585@end multitable 8586 8587@item @emph{Return value}: 8588Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.} 8589otherwise, based on the ASCII ordering. 8590 8591@item @emph{Specific names}: 8592@multitable @columnfractions .20 .20 .20 .25 8593@item Name @tab Argument @tab Return type @tab Standard 8594@item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later 8595@end multitable 8596 8597@item @emph{See also}: 8598@ref{LGE}, @ref{LGT}, @ref{LLE} 8599@end table 8600 8601 8602 8603@node LNBLNK 8604@section @code{LNBLNK} --- Index of the last non-blank character in a string 8605@fnindex LNBLNK 8606@cindex string, find non-blank character 8607 8608@table @asis 8609@item @emph{Description}: 8610Returns the length of a character string, ignoring any trailing blanks. 8611This is identical to the standard @code{LEN_TRIM} intrinsic, and is only 8612included for backwards compatibility. 8613 8614@item @emph{Standard}: 8615GNU extension 8616 8617@item @emph{Class}: 8618Elemental function 8619 8620@item @emph{Syntax}: 8621@code{RESULT = LNBLNK(STRING)} 8622 8623@item @emph{Arguments}: 8624@multitable @columnfractions .15 .70 8625@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, 8626with @code{INTENT(IN)} 8627@end multitable 8628 8629@item @emph{Return value}: 8630The return value is of @code{INTEGER(kind=4)} type. 8631 8632@item @emph{See also}: 8633@ref{INDEX intrinsic}, @ref{LEN_TRIM} 8634@end table 8635 8636 8637 8638@node LOC 8639@section @code{LOC} --- Returns the address of a variable 8640@fnindex LOC 8641@cindex location of a variable in memory 8642 8643@table @asis 8644@item @emph{Description}: 8645@code{LOC(X)} returns the address of @var{X} as an integer. 8646 8647@item @emph{Standard}: 8648GNU extension 8649 8650@item @emph{Class}: 8651Inquiry function 8652 8653@item @emph{Syntax}: 8654@code{RESULT = LOC(X)} 8655 8656@item @emph{Arguments}: 8657@multitable @columnfractions .15 .70 8658@item @var{X} @tab Variable of any type. 8659@end multitable 8660 8661@item @emph{Return value}: 8662The return value is of type @code{INTEGER}, with a @code{KIND} 8663corresponding to the size (in bytes) of a memory address on the target 8664machine. 8665 8666@item @emph{Example}: 8667@smallexample 8668program test_loc 8669 integer :: i 8670 real :: r 8671 i = loc(r) 8672 print *, i 8673end program test_loc 8674@end smallexample 8675@end table 8676 8677 8678 8679@node LOG 8680@section @code{LOG} --- Natural logarithm function 8681@fnindex LOG 8682@fnindex ALOG 8683@fnindex DLOG 8684@fnindex CLOG 8685@fnindex ZLOG 8686@fnindex CDLOG 8687@cindex exponential function, inverse 8688@cindex logarithm function 8689@cindex natural logarithm function 8690 8691@table @asis 8692@item @emph{Description}: 8693@code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the 8694logarithm to the base @math{e}. 8695 8696@item @emph{Standard}: 8697Fortran 77 and later 8698 8699@item @emph{Class}: 8700Elemental function 8701 8702@item @emph{Syntax}: 8703@code{RESULT = LOG(X)} 8704 8705@item @emph{Arguments}: 8706@multitable @columnfractions .15 .70 8707@item @var{X} @tab The type shall be @code{REAL} or 8708@code{COMPLEX}. 8709@end multitable 8710 8711@item @emph{Return value}: 8712The return value is of type @code{REAL} or @code{COMPLEX}. 8713The kind type parameter is the same as @var{X}. 8714If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range 8715@math{-\pi < \omega \leq \pi}. 8716 8717@item @emph{Example}: 8718@smallexample 8719program test_log 8720 real(8) :: x = 2.7182818284590451_8 8721 complex :: z = (1.0, 2.0) 8722 x = log(x) ! will yield (approximately) 1 8723 z = log(z) 8724end program test_log 8725@end smallexample 8726 8727@item @emph{Specific names}: 8728@multitable @columnfractions .20 .20 .20 .25 8729@item Name @tab Argument @tab Return type @tab Standard 8730@item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu 8731@item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu 8732@item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu 8733@item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 8734@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 8735@end multitable 8736@end table 8737 8738 8739 8740@node LOG10 8741@section @code{LOG10} --- Base 10 logarithm function 8742@fnindex LOG10 8743@fnindex ALOG10 8744@fnindex DLOG10 8745@cindex exponential function, inverse 8746@cindex logarithm function with base 10 8747@cindex base 10 logarithm function 8748 8749@table @asis 8750@item @emph{Description}: 8751@code{LOG10(X)} computes the base 10 logarithm of @var{X}. 8752 8753@item @emph{Standard}: 8754Fortran 77 and later 8755 8756@item @emph{Class}: 8757Elemental function 8758 8759@item @emph{Syntax}: 8760@code{RESULT = LOG10(X)} 8761 8762@item @emph{Arguments}: 8763@multitable @columnfractions .15 .70 8764@item @var{X} @tab The type shall be @code{REAL}. 8765@end multitable 8766 8767@item @emph{Return value}: 8768The return value is of type @code{REAL} or @code{COMPLEX}. 8769The kind type parameter is the same as @var{X}. 8770 8771@item @emph{Example}: 8772@smallexample 8773program test_log10 8774 real(8) :: x = 10.0_8 8775 x = log10(x) 8776end program test_log10 8777@end smallexample 8778 8779@item @emph{Specific names}: 8780@multitable @columnfractions .20 .20 .20 .25 8781@item Name @tab Argument @tab Return type @tab Standard 8782@item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 8783@item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 8784@end multitable 8785@end table 8786 8787 8788 8789@node LOG_GAMMA 8790@section @code{LOG_GAMMA} --- Logarithm of the Gamma function 8791@fnindex LOG_GAMMA 8792@fnindex LGAMMA 8793@fnindex ALGAMA 8794@fnindex DLGAMA 8795@cindex Gamma function, logarithm of 8796 8797@table @asis 8798@item @emph{Description}: 8799@code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value 8800of the Gamma (@math{\Gamma}) function. 8801 8802@item @emph{Standard}: 8803Fortran 2008 and later 8804 8805@item @emph{Class}: 8806Elemental function 8807 8808@item @emph{Syntax}: 8809@code{X = LOG_GAMMA(X)} 8810 8811@item @emph{Arguments}: 8812@multitable @columnfractions .15 .70 8813@item @var{X} @tab Shall be of type @code{REAL} and neither zero 8814nor a negative integer. 8815@end multitable 8816 8817@item @emph{Return value}: 8818The return value is of type @code{REAL} of the same kind as @var{X}. 8819 8820@item @emph{Example}: 8821@smallexample 8822program test_log_gamma 8823 real :: x = 1.0 8824 x = lgamma(x) ! returns 0.0 8825end program test_log_gamma 8826@end smallexample 8827 8828@item @emph{Specific names}: 8829@multitable @columnfractions .20 .20 .20 .25 8830@item Name @tab Argument @tab Return type @tab Standard 8831@item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 8832@item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension 8833@item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension 8834@end multitable 8835 8836@item @emph{See also}: 8837Gamma function: @ref{GAMMA} 8838 8839@end table 8840 8841 8842 8843@node LOGICAL 8844@section @code{LOGICAL} --- Convert to logical type 8845@fnindex LOGICAL 8846@cindex conversion, to logical 8847 8848@table @asis 8849@item @emph{Description}: 8850Converts one kind of @code{LOGICAL} variable to another. 8851 8852@item @emph{Standard}: 8853Fortran 95 and later 8854 8855@item @emph{Class}: 8856Elemental function 8857 8858@item @emph{Syntax}: 8859@code{RESULT = LOGICAL(L [, KIND])} 8860 8861@item @emph{Arguments}: 8862@multitable @columnfractions .15 .70 8863@item @var{L} @tab The type shall be @code{LOGICAL}. 8864@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 8865expression indicating the kind parameter of the result. 8866@end multitable 8867 8868@item @emph{Return value}: 8869The return value is a @code{LOGICAL} value equal to @var{L}, with a 8870kind corresponding to @var{KIND}, or of the default logical kind if 8871@var{KIND} is not given. 8872 8873@item @emph{See also}: 8874@ref{INT}, @ref{REAL}, @ref{CMPLX} 8875@end table 8876 8877 8878 8879@node LONG 8880@section @code{LONG} --- Convert to integer type 8881@fnindex LONG 8882@cindex conversion, to integer 8883 8884@table @asis 8885@item @emph{Description}: 8886Convert to a @code{KIND=4} integer type, which is the same size as a C 8887@code{long} integer. This is equivalent to the standard @code{INT} 8888intrinsic with an optional argument of @code{KIND=4}, and is only 8889included for backwards compatibility. 8890 8891@item @emph{Standard}: 8892GNU extension 8893 8894@item @emph{Class}: 8895Elemental function 8896 8897@item @emph{Syntax}: 8898@code{RESULT = LONG(A)} 8899 8900@item @emph{Arguments}: 8901@multitable @columnfractions .15 .70 8902@item @var{A} @tab Shall be of type @code{INTEGER}, 8903@code{REAL}, or @code{COMPLEX}. 8904@end multitable 8905 8906@item @emph{Return value}: 8907The return value is a @code{INTEGER(4)} variable. 8908 8909@item @emph{See also}: 8910@ref{INT}, @ref{INT2}, @ref{INT8} 8911@end table 8912 8913 8914 8915@node LSHIFT 8916@section @code{LSHIFT} --- Left shift bits 8917@fnindex LSHIFT 8918@cindex bits, shift left 8919 8920@table @asis 8921@item @emph{Description}: 8922@code{LSHIFT} returns a value corresponding to @var{I} with all of the 8923bits shifted left by @var{SHIFT} places. If the absolute value of 8924@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 8925Bits shifted out from the left end are lost; zeros are shifted in from 8926the opposite end. 8927 8928This function has been superseded by the @code{ISHFT} intrinsic, which 8929is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic, 8930which is standard in Fortran 2008 and later. 8931 8932@item @emph{Standard}: 8933GNU extension 8934 8935@item @emph{Class}: 8936Elemental function 8937 8938@item @emph{Syntax}: 8939@code{RESULT = LSHIFT(I, SHIFT)} 8940 8941@item @emph{Arguments}: 8942@multitable @columnfractions .15 .70 8943@item @var{I} @tab The type shall be @code{INTEGER}. 8944@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 8945@end multitable 8946 8947@item @emph{Return value}: 8948The return value is of type @code{INTEGER} and of the same kind as 8949@var{I}. 8950 8951@item @emph{See also}: 8952@ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL}, 8953@ref{SHIFTR} 8954 8955@end table 8956 8957 8958 8959@node LSTAT 8960@section @code{LSTAT} --- Get file status 8961@fnindex LSTAT 8962@cindex file system, file status 8963 8964@table @asis 8965@item @emph{Description}: 8966@code{LSTAT} is identical to @ref{STAT}, except that if path is a 8967symbolic link, then the link itself is statted, not the file that it 8968refers to. 8969 8970The elements in @code{VALUES} are the same as described by @ref{STAT}. 8971 8972This intrinsic is provided in both subroutine and function forms; 8973however, only one form can be used in any given program unit. 8974 8975@item @emph{Standard}: 8976GNU extension 8977 8978@item @emph{Class}: 8979Subroutine, function 8980 8981@item @emph{Syntax}: 8982@multitable @columnfractions .80 8983@item @code{CALL LSTAT(NAME, VALUES [, STATUS])} 8984@item @code{STATUS = LSTAT(NAME, VALUES)} 8985@end multitable 8986 8987@item @emph{Arguments}: 8988@multitable @columnfractions .15 .70 8989@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default 8990kind, a valid path within the file system. 8991@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 8992@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. 8993Returns 0 on success and a system specific error code otherwise. 8994@end multitable 8995 8996@item @emph{Example}: 8997See @ref{STAT} for an example. 8998 8999@item @emph{See also}: 9000To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT} 9001@end table 9002 9003 9004 9005@node LTIME 9006@section @code{LTIME} --- Convert time to local time info 9007@fnindex LTIME 9008@cindex time, conversion to local time info 9009 9010@table @asis 9011@item @emph{Description}: 9012Given a system time value @var{TIME} (as provided by the @code{TIME8} 9013intrinsic), fills @var{VALUES} with values extracted from it appropriate 9014to the local time zone using @code{localtime(3)}. 9015 9016@item @emph{Standard}: 9017GNU extension 9018 9019@item @emph{Class}: 9020Subroutine 9021 9022@item @emph{Syntax}: 9023@code{CALL LTIME(TIME, VALUES)} 9024 9025@item @emph{Arguments}: 9026@multitable @columnfractions .15 .70 9027@item @var{TIME} @tab An @code{INTEGER} scalar expression 9028corresponding to a system time, with @code{INTENT(IN)}. 9029@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, 9030with @code{INTENT(OUT)}. 9031@end multitable 9032 9033@item @emph{Return value}: 9034The elements of @var{VALUES} are assigned as follows: 9035@enumerate 9036@item Seconds after the minute, range 0--59 or 0--61 to allow for leap 9037seconds 9038@item Minutes after the hour, range 0--59 9039@item Hours past midnight, range 0--23 9040@item Day of month, range 0--31 9041@item Number of months since January, range 0--12 9042@item Years since 1900 9043@item Number of days since Sunday, range 0--6 9044@item Days since January 1 9045@item Daylight savings indicator: positive if daylight savings is in 9046effect, zero if not, and negative if the information is not available. 9047@end enumerate 9048 9049@item @emph{See also}: 9050@ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8} 9051 9052@end table 9053 9054 9055 9056@node MALLOC 9057@section @code{MALLOC} --- Allocate dynamic memory 9058@fnindex MALLOC 9059@cindex pointer, cray 9060 9061@table @asis 9062@item @emph{Description}: 9063@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and 9064returns the address of the allocated memory. The @code{MALLOC} intrinsic 9065is an extension intended to be used with Cray pointers, and is provided 9066in GNU Fortran to allow the user to compile legacy code. For new code 9067using Fortran 95 pointers, the memory allocation intrinsic is 9068@code{ALLOCATE}. 9069 9070@item @emph{Standard}: 9071GNU extension 9072 9073@item @emph{Class}: 9074Function 9075 9076@item @emph{Syntax}: 9077@code{PTR = MALLOC(SIZE)} 9078 9079@item @emph{Arguments}: 9080@multitable @columnfractions .15 .70 9081@item @var{SIZE} @tab The type shall be @code{INTEGER}. 9082@end multitable 9083 9084@item @emph{Return value}: 9085The return value is of type @code{INTEGER(K)}, with @var{K} such that 9086variables of type @code{INTEGER(K)} have the same size as 9087C pointers (@code{sizeof(void *)}). 9088 9089@item @emph{Example}: 9090The following example demonstrates the use of @code{MALLOC} and 9091@code{FREE} with Cray pointers. 9092 9093@smallexample 9094program test_malloc 9095 implicit none 9096 integer i 9097 real*8 x(*), z 9098 pointer(ptr_x,x) 9099 9100 ptr_x = malloc(20*8) 9101 do i = 1, 20 9102 x(i) = sqrt(1.0d0 / i) 9103 end do 9104 z = 0 9105 do i = 1, 20 9106 z = z + x(i) 9107 print *, z 9108 end do 9109 call free(ptr_x) 9110end program test_malloc 9111@end smallexample 9112 9113@item @emph{See also}: 9114@ref{FREE} 9115@end table 9116 9117 9118 9119@node MASKL 9120@section @code{MASKL} --- Left justified mask 9121@fnindex MASKL 9122@cindex mask, left justified 9123 9124@table @asis 9125@item @emph{Description}: 9126@code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the 9127remaining bits set to 0. 9128 9129@item @emph{Standard}: 9130Fortran 2008 and later 9131 9132@item @emph{Class}: 9133Elemental function 9134 9135@item @emph{Syntax}: 9136@code{RESULT = MASKL(I[, KIND])} 9137 9138@item @emph{Arguments}: 9139@multitable @columnfractions .15 .70 9140@item @var{I} @tab Shall be of type @code{INTEGER}. 9141@item @var{KIND} @tab Shall be a scalar constant expression of type 9142@code{INTEGER}. 9143@end multitable 9144 9145@item @emph{Return value}: 9146The return value is of type @code{INTEGER}. If @var{KIND} is present, it 9147specifies the kind value of the return type; otherwise, it is of the 9148default integer kind. 9149 9150@item @emph{See also}: 9151@ref{MASKR} 9152@end table 9153 9154 9155 9156@node MASKR 9157@section @code{MASKR} --- Right justified mask 9158@fnindex MASKR 9159@cindex mask, right justified 9160 9161@table @asis 9162@item @emph{Description}: 9163@code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the 9164remaining bits set to 0. 9165 9166@item @emph{Standard}: 9167Fortran 2008 and later 9168 9169@item @emph{Class}: 9170Elemental function 9171 9172@item @emph{Syntax}: 9173@code{RESULT = MASKR(I[, KIND])} 9174 9175@item @emph{Arguments}: 9176@multitable @columnfractions .15 .70 9177@item @var{I} @tab Shall be of type @code{INTEGER}. 9178@item @var{KIND} @tab Shall be a scalar constant expression of type 9179@code{INTEGER}. 9180@end multitable 9181 9182@item @emph{Return value}: 9183The return value is of type @code{INTEGER}. If @var{KIND} is present, it 9184specifies the kind value of the return type; otherwise, it is of the 9185default integer kind. 9186 9187@item @emph{See also}: 9188@ref{MASKL} 9189@end table 9190 9191 9192 9193@node MATMUL 9194@section @code{MATMUL} --- matrix multiplication 9195@fnindex MATMUL 9196@cindex matrix multiplication 9197@cindex product, matrix 9198 9199@table @asis 9200@item @emph{Description}: 9201Performs a matrix multiplication on numeric or logical arguments. 9202 9203@item @emph{Standard}: 9204Fortran 95 and later 9205 9206@item @emph{Class}: 9207Transformational function 9208 9209@item @emph{Syntax}: 9210@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)} 9211 9212@item @emph{Arguments}: 9213@multitable @columnfractions .15 .70 9214@item @var{MATRIX_A} @tab An array of @code{INTEGER}, 9215@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of 9216one or two. 9217@item @var{MATRIX_B} @tab An array of @code{INTEGER}, 9218@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric 9219type; otherwise, an array of @code{LOGICAL} type. The rank shall be one 9220or two, and the first (or only) dimension of @var{MATRIX_B} shall be 9221equal to the last (or only) dimension of @var{MATRIX_A}. 9222@end multitable 9223 9224@item @emph{Return value}: 9225The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and 9226kind of the result follow the usual type and kind promotion rules, as 9227for the @code{*} or @code{.AND.} operators. 9228 9229@item @emph{See also}: 9230@end table 9231 9232 9233 9234@node MAX 9235@section @code{MAX} --- Maximum value of an argument list 9236@fnindex MAX 9237@fnindex MAX0 9238@fnindex AMAX0 9239@fnindex MAX1 9240@fnindex AMAX1 9241@fnindex DMAX1 9242@cindex maximum value 9243 9244@table @asis 9245@item @emph{Description}: 9246Returns the argument with the largest (most positive) value. 9247 9248@item @emph{Standard}: 9249Fortran 77 and later 9250 9251@item @emph{Class}: 9252Elemental function 9253 9254@item @emph{Syntax}: 9255@code{RESULT = MAX(A1, A2 [, A3 [, ...]])} 9256 9257@item @emph{Arguments}: 9258@multitable @columnfractions .15 .70 9259@item @var{A1} @tab The type shall be @code{INTEGER} or 9260@code{REAL}. 9261@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 9262as @var{A1}. (As a GNU extension, arguments of different kinds are 9263permitted.) 9264@end multitable 9265 9266@item @emph{Return value}: 9267The return value corresponds to the maximum value among the arguments, 9268and has the same type and kind as the first argument. 9269 9270@item @emph{Specific names}: 9271@multitable @columnfractions .20 .20 .20 .25 9272@item Name @tab Argument @tab Return type @tab Standard 9273@item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 9274@item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later 9275@item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later 9276@item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 9277@item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 9278@end multitable 9279 9280@item @emph{See also}: 9281@ref{MAXLOC} @ref{MAXVAL}, @ref{MIN} 9282 9283@end table 9284 9285 9286 9287@node MAXEXPONENT 9288@section @code{MAXEXPONENT} --- Maximum exponent of a real kind 9289@fnindex MAXEXPONENT 9290@cindex model representation, maximum exponent 9291 9292@table @asis 9293@item @emph{Description}: 9294@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the 9295type of @code{X}. 9296 9297@item @emph{Standard}: 9298Fortran 95 and later 9299 9300@item @emph{Class}: 9301Inquiry function 9302 9303@item @emph{Syntax}: 9304@code{RESULT = MAXEXPONENT(X)} 9305 9306@item @emph{Arguments}: 9307@multitable @columnfractions .15 .70 9308@item @var{X} @tab Shall be of type @code{REAL}. 9309@end multitable 9310 9311@item @emph{Return value}: 9312The return value is of type @code{INTEGER} and of the default integer 9313kind. 9314 9315@item @emph{Example}: 9316@smallexample 9317program exponents 9318 real(kind=4) :: x 9319 real(kind=8) :: y 9320 9321 print *, minexponent(x), maxexponent(x) 9322 print *, minexponent(y), maxexponent(y) 9323end program exponents 9324@end smallexample 9325@end table 9326 9327 9328 9329@node MAXLOC 9330@section @code{MAXLOC} --- Location of the maximum value within an array 9331@fnindex MAXLOC 9332@cindex array, location of maximum element 9333 9334@table @asis 9335@item @emph{Description}: 9336Determines the location of the element in the array with the maximum 9337value, or, if the @var{DIM} argument is supplied, determines the 9338locations of the maximum element along each row of the array in the 9339@var{DIM} direction. If @var{MASK} is present, only the elements for 9340which @var{MASK} is @code{.TRUE.} are considered. If more than one 9341element in the array has the maximum value, the location returned is 9342that of the first such element in array element order. If the array has 9343zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 9344the result is an array of zeroes. Similarly, if @var{DIM} is supplied 9345and all of the elements of @var{MASK} along a given row are zero, the 9346result value for that row is zero. 9347 9348@item @emph{Standard}: 9349Fortran 95 and later 9350 9351@item @emph{Class}: 9352Transformational function 9353 9354@item @emph{Syntax}: 9355@multitable @columnfractions .80 9356@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])} 9357@item @code{RESULT = MAXLOC(ARRAY [, MASK])} 9358@end multitable 9359 9360@item @emph{Arguments}: 9361@multitable @columnfractions .15 .70 9362@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 9363@code{REAL}. 9364@item @var{DIM} @tab (Optional) Shall be a scalar of type 9365@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 9366inclusive. It may not be an optional dummy argument. 9367@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 9368and conformable with @var{ARRAY}. 9369@end multitable 9370 9371@item @emph{Return value}: 9372If @var{DIM} is absent, the result is a rank-one array with a length 9373equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 9374is an array with a rank one less than the rank of @var{ARRAY}, and a 9375size corresponding to the size of @var{ARRAY} with the @var{DIM} 9376dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 9377of one, the result is a scalar. In all cases, the result is of default 9378@code{INTEGER} type. 9379 9380@item @emph{See also}: 9381@ref{MAX}, @ref{MAXVAL} 9382 9383@end table 9384 9385 9386 9387@node MAXVAL 9388@section @code{MAXVAL} --- Maximum value of an array 9389@fnindex MAXVAL 9390@cindex array, maximum value 9391@cindex maximum value 9392 9393@table @asis 9394@item @emph{Description}: 9395Determines the maximum value of the elements in an array value, or, if 9396the @var{DIM} argument is supplied, determines the maximum value along 9397each row of the array in the @var{DIM} direction. If @var{MASK} is 9398present, only the elements for which @var{MASK} is @code{.TRUE.} are 9399considered. If the array has zero size, or all of the elements of 9400@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)} 9401if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character 9402type. 9403 9404@item @emph{Standard}: 9405Fortran 95 and later 9406 9407@item @emph{Class}: 9408Transformational function 9409 9410@item @emph{Syntax}: 9411@multitable @columnfractions .80 9412@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])} 9413@item @code{RESULT = MAXVAL(ARRAY [, MASK])} 9414@end multitable 9415 9416@item @emph{Arguments}: 9417@multitable @columnfractions .15 .70 9418@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 9419@code{REAL}. 9420@item @var{DIM} @tab (Optional) Shall be a scalar of type 9421@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 9422inclusive. It may not be an optional dummy argument. 9423@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 9424and conformable with @var{ARRAY}. 9425@end multitable 9426 9427@item @emph{Return value}: 9428If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 9429is a scalar. If @var{DIM} is present, the result is an array with a 9430rank one less than the rank of @var{ARRAY}, and a size corresponding to 9431the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 9432cases, the result is of the same type and kind as @var{ARRAY}. 9433 9434@item @emph{See also}: 9435@ref{MAX}, @ref{MAXLOC} 9436@end table 9437 9438 9439 9440@node MCLOCK 9441@section @code{MCLOCK} --- Time function 9442@fnindex MCLOCK 9443@cindex time, clock ticks 9444@cindex clock ticks 9445 9446@table @asis 9447@item @emph{Description}: 9448Returns the number of clock ticks since the start of the process, based 9449on the function @code{clock(3)} in the C standard library. 9450 9451This intrinsic is not fully portable, such as to systems with 32-bit 9452@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 9453the values returned by this intrinsic might be, or become, negative, or 9454numerically less than previous values, during a single run of the 9455compiled program. 9456 9457@item @emph{Standard}: 9458GNU extension 9459 9460@item @emph{Class}: 9461Function 9462 9463@item @emph{Syntax}: 9464@code{RESULT = MCLOCK()} 9465 9466@item @emph{Return value}: 9467The return value is a scalar of type @code{INTEGER(4)}, equal to the 9468number of clock ticks since the start of the process, or @code{-1} if 9469the system does not support @code{clock(3)}. 9470 9471@item @emph{See also}: 9472@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME} 9473 9474@end table 9475 9476 9477 9478@node MCLOCK8 9479@section @code{MCLOCK8} --- Time function (64-bit) 9480@fnindex MCLOCK8 9481@cindex time, clock ticks 9482@cindex clock ticks 9483 9484@table @asis 9485@item @emph{Description}: 9486Returns the number of clock ticks since the start of the process, based 9487on the function @code{clock(3)} in the C standard library. 9488 9489@emph{Warning:} this intrinsic does not increase the range of the timing 9490values over that returned by @code{clock(3)}. On a system with a 32-bit 9491@code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though 9492it is converted to a 64-bit @code{INTEGER(8)} value. That means 9493overflows of the 32-bit value can still occur. Therefore, the values 9494returned by this intrinsic might be or become negative or numerically 9495less than previous values during a single run of the compiled program. 9496 9497@item @emph{Standard}: 9498GNU extension 9499 9500@item @emph{Class}: 9501Function 9502 9503@item @emph{Syntax}: 9504@code{RESULT = MCLOCK8()} 9505 9506@item @emph{Return value}: 9507The return value is a scalar of type @code{INTEGER(8)}, equal to the 9508number of clock ticks since the start of the process, or @code{-1} if 9509the system does not support @code{clock(3)}. 9510 9511@item @emph{See also}: 9512@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} 9513 9514@end table 9515 9516 9517 9518@node MERGE 9519@section @code{MERGE} --- Merge variables 9520@fnindex MERGE 9521@cindex array, merge arrays 9522@cindex array, combine arrays 9523 9524@table @asis 9525@item @emph{Description}: 9526Select values from two arrays according to a logical mask. The result 9527is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to 9528@var{FSOURCE} if it is @code{.FALSE.}. 9529 9530@item @emph{Standard}: 9531Fortran 95 and later 9532 9533@item @emph{Class}: 9534Elemental function 9535 9536@item @emph{Syntax}: 9537@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)} 9538 9539@item @emph{Arguments}: 9540@multitable @columnfractions .15 .70 9541@item @var{TSOURCE} @tab May be of any type. 9542@item @var{FSOURCE} @tab Shall be of the same type and type parameters 9543as @var{TSOURCE}. 9544@item @var{MASK} @tab Shall be of type @code{LOGICAL}. 9545@end multitable 9546 9547@item @emph{Return value}: 9548The result is of the same type and type parameters as @var{TSOURCE}. 9549 9550@end table 9551 9552 9553 9554@node MERGE_BITS 9555@section @code{MERGE_BITS} --- Merge of bits under mask 9556@fnindex MERGE_BITS 9557@cindex bits, merge 9558 9559@table @asis 9560@item @emph{Description}: 9561@code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J} 9562as determined by the mask. The i-th bit of the result is equal to the 9563i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to 9564the i-th bit of @var{J} otherwise. 9565 9566@item @emph{Standard}: 9567Fortran 2008 and later 9568 9569@item @emph{Class}: 9570Elemental function 9571 9572@item @emph{Syntax}: 9573@code{RESULT = MERGE_BITS(I, J, MASK)} 9574 9575@item @emph{Arguments}: 9576@multitable @columnfractions .15 .70 9577@item @var{I} @tab Shall be of type @code{INTEGER}. 9578@item @var{J} @tab Shall be of type @code{INTEGER} and of the same 9579kind as @var{I}. 9580@item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same 9581kind as @var{I}. 9582@end multitable 9583 9584@item @emph{Return value}: 9585The result is of the same type and kind as @var{I}. 9586 9587@end table 9588 9589 9590 9591@node MIN 9592@section @code{MIN} --- Minimum value of an argument list 9593@fnindex MIN 9594@fnindex MIN0 9595@fnindex AMIN0 9596@fnindex MIN1 9597@fnindex AMIN1 9598@fnindex DMIN1 9599@cindex minimum value 9600 9601@table @asis 9602@item @emph{Description}: 9603Returns the argument with the smallest (most negative) value. 9604 9605@item @emph{Standard}: 9606Fortran 77 and later 9607 9608@item @emph{Class}: 9609Elemental function 9610 9611@item @emph{Syntax}: 9612@code{RESULT = MIN(A1, A2 [, A3, ...])} 9613 9614@item @emph{Arguments}: 9615@multitable @columnfractions .15 .70 9616@item @var{A1} @tab The type shall be @code{INTEGER} or 9617@code{REAL}. 9618@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind 9619as @var{A1}. (As a GNU extension, arguments of different kinds are 9620permitted.) 9621@end multitable 9622 9623@item @emph{Return value}: 9624The return value corresponds to the maximum value among the arguments, 9625and has the same type and kind as the first argument. 9626 9627@item @emph{Specific names}: 9628@multitable @columnfractions .20 .20 .20 .25 9629@item Name @tab Argument @tab Return type @tab Standard 9630@item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 9631@item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 9632@item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later 9633@item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later 9634@item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later 9635@end multitable 9636 9637@item @emph{See also}: 9638@ref{MAX}, @ref{MINLOC}, @ref{MINVAL} 9639@end table 9640 9641 9642 9643@node MINEXPONENT 9644@section @code{MINEXPONENT} --- Minimum exponent of a real kind 9645@fnindex MINEXPONENT 9646@cindex model representation, minimum exponent 9647 9648@table @asis 9649@item @emph{Description}: 9650@code{MINEXPONENT(X)} returns the minimum exponent in the model of the 9651type of @code{X}. 9652 9653@item @emph{Standard}: 9654Fortran 95 and later 9655 9656@item @emph{Class}: 9657Inquiry function 9658 9659@item @emph{Syntax}: 9660@code{RESULT = MINEXPONENT(X)} 9661 9662@item @emph{Arguments}: 9663@multitable @columnfractions .15 .70 9664@item @var{X} @tab Shall be of type @code{REAL}. 9665@end multitable 9666 9667@item @emph{Return value}: 9668The return value is of type @code{INTEGER} and of the default integer 9669kind. 9670 9671@item @emph{Example}: 9672See @code{MAXEXPONENT} for an example. 9673@end table 9674 9675 9676 9677@node MINLOC 9678@section @code{MINLOC} --- Location of the minimum value within an array 9679@fnindex MINLOC 9680@cindex array, location of minimum element 9681 9682@table @asis 9683@item @emph{Description}: 9684Determines the location of the element in the array with the minimum 9685value, or, if the @var{DIM} argument is supplied, determines the 9686locations of the minimum element along each row of the array in the 9687@var{DIM} direction. If @var{MASK} is present, only the elements for 9688which @var{MASK} is @code{.TRUE.} are considered. If more than one 9689element in the array has the minimum value, the location returned is 9690that of the first such element in array element order. If the array has 9691zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then 9692the result is an array of zeroes. Similarly, if @var{DIM} is supplied 9693and all of the elements of @var{MASK} along a given row are zero, the 9694result value for that row is zero. 9695 9696@item @emph{Standard}: 9697Fortran 95 and later 9698 9699@item @emph{Class}: 9700Transformational function 9701 9702@item @emph{Syntax}: 9703@multitable @columnfractions .80 9704@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])} 9705@item @code{RESULT = MINLOC(ARRAY [, MASK])} 9706@end multitable 9707 9708@item @emph{Arguments}: 9709@multitable @columnfractions .15 .70 9710@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 9711@code{REAL}. 9712@item @var{DIM} @tab (Optional) Shall be a scalar of type 9713@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 9714inclusive. It may not be an optional dummy argument. 9715@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 9716and conformable with @var{ARRAY}. 9717@end multitable 9718 9719@item @emph{Return value}: 9720If @var{DIM} is absent, the result is a rank-one array with a length 9721equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result 9722is an array with a rank one less than the rank of @var{ARRAY}, and a 9723size corresponding to the size of @var{ARRAY} with the @var{DIM} 9724dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank 9725of one, the result is a scalar. In all cases, the result is of default 9726@code{INTEGER} type. 9727 9728@item @emph{See also}: 9729@ref{MIN}, @ref{MINVAL} 9730 9731@end table 9732 9733 9734 9735@node MINVAL 9736@section @code{MINVAL} --- Minimum value of an array 9737@fnindex MINVAL 9738@cindex array, minimum value 9739@cindex minimum value 9740 9741@table @asis 9742@item @emph{Description}: 9743Determines the minimum value of the elements in an array value, or, if 9744the @var{DIM} argument is supplied, determines the minimum value along 9745each row of the array in the @var{DIM} direction. If @var{MASK} is 9746present, only the elements for which @var{MASK} is @code{.TRUE.} are 9747considered. If the array has zero size, or all of the elements of 9748@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if 9749@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if 9750@var{ARRAY} is of character type. 9751 9752@item @emph{Standard}: 9753Fortran 95 and later 9754 9755@item @emph{Class}: 9756Transformational function 9757 9758@item @emph{Syntax}: 9759@multitable @columnfractions .80 9760@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])} 9761@item @code{RESULT = MINVAL(ARRAY [, MASK])} 9762@end multitable 9763 9764@item @emph{Arguments}: 9765@multitable @columnfractions .15 .70 9766@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or 9767@code{REAL}. 9768@item @var{DIM} @tab (Optional) Shall be a scalar of type 9769@code{INTEGER}, with a value between one and the rank of @var{ARRAY}, 9770inclusive. It may not be an optional dummy argument. 9771@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, 9772and conformable with @var{ARRAY}. 9773@end multitable 9774 9775@item @emph{Return value}: 9776If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result 9777is a scalar. If @var{DIM} is present, the result is an array with a 9778rank one less than the rank of @var{ARRAY}, and a size corresponding to 9779the size of @var{ARRAY} with the @var{DIM} dimension removed. In all 9780cases, the result is of the same type and kind as @var{ARRAY}. 9781 9782@item @emph{See also}: 9783@ref{MIN}, @ref{MINLOC} 9784 9785@end table 9786 9787 9788 9789@node MOD 9790@section @code{MOD} --- Remainder function 9791@fnindex MOD 9792@fnindex AMOD 9793@fnindex DMOD 9794@cindex remainder 9795@cindex division, remainder 9796 9797@table @asis 9798@item @emph{Description}: 9799@code{MOD(A,P)} computes the remainder of the division of A by P@. 9800 9801@item @emph{Standard}: 9802Fortran 77 and later 9803 9804@item @emph{Class}: 9805Elemental function 9806 9807@item @emph{Syntax}: 9808@code{RESULT = MOD(A, P)} 9809 9810@item @emph{Arguments}: 9811@multitable @columnfractions .15 .70 9812@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 9813@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A} 9814and not equal to zero. 9815@end multitable 9816 9817@item @emph{Return value}: 9818The return value is the result of @code{A - (INT(A/P) * P)}. The type 9819and kind of the return value is the same as that of the arguments. The 9820returned value has the same sign as A and a magnitude less than the 9821magnitude of P. 9822 9823@item @emph{Example}: 9824@smallexample 9825program test_mod 9826 print *, mod(17,3) 9827 print *, mod(17.5,5.5) 9828 print *, mod(17.5d0,5.5) 9829 print *, mod(17.5,5.5d0) 9830 9831 print *, mod(-17,3) 9832 print *, mod(-17.5,5.5) 9833 print *, mod(-17.5d0,5.5) 9834 print *, mod(-17.5,5.5d0) 9835 9836 print *, mod(17,-3) 9837 print *, mod(17.5,-5.5) 9838 print *, mod(17.5d0,-5.5) 9839 print *, mod(17.5,-5.5d0) 9840end program test_mod 9841@end smallexample 9842 9843@item @emph{Specific names}: 9844@multitable @columnfractions .20 .20 .20 .25 9845@item Name @tab Arguments @tab Return type @tab Standard 9846@item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later 9847@item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later 9848@item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later 9849@end multitable 9850 9851@item @emph{See also}: 9852@ref{MODULO} 9853 9854@end table 9855 9856 9857 9858@node MODULO 9859@section @code{MODULO} --- Modulo function 9860@fnindex MODULO 9861@cindex modulo 9862@cindex division, modulo 9863 9864@table @asis 9865@item @emph{Description}: 9866@code{MODULO(A,P)} computes the @var{A} modulo @var{P}. 9867 9868@item @emph{Standard}: 9869Fortran 95 and later 9870 9871@item @emph{Class}: 9872Elemental function 9873 9874@item @emph{Syntax}: 9875@code{RESULT = MODULO(A, P)} 9876 9877@item @emph{Arguments}: 9878@multitable @columnfractions .15 .70 9879@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. 9880@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}. 9881It shall not be zero. 9882@end multitable 9883 9884@item @emph{Return value}: 9885The type and kind of the result are those of the arguments. 9886@table @asis 9887@item If @var{A} and @var{P} are of type @code{INTEGER}: 9888@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where 9889@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P} 9890(exclusive). 9891@item If @var{A} and @var{P} are of type @code{REAL}: 9892@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}. 9893@end table 9894The returned value has the same sign as P and a magnitude less than 9895the magnitude of P. 9896 9897@item @emph{Example}: 9898@smallexample 9899program test_modulo 9900 print *, modulo(17,3) 9901 print *, modulo(17.5,5.5) 9902 9903 print *, modulo(-17,3) 9904 print *, modulo(-17.5,5.5) 9905 9906 print *, modulo(17,-3) 9907 print *, modulo(17.5,-5.5) 9908end program 9909@end smallexample 9910 9911@item @emph{See also}: 9912@ref{MOD} 9913 9914@end table 9915 9916 9917 9918@node MOVE_ALLOC 9919@section @code{MOVE_ALLOC} --- Move allocation from one object to another 9920@fnindex MOVE_ALLOC 9921@cindex moving allocation 9922@cindex allocation, moving 9923 9924@table @asis 9925@item @emph{Description}: 9926@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to 9927@var{TO}. @var{FROM} will become deallocated in the process. 9928 9929@item @emph{Standard}: 9930Fortran 2003 and later 9931 9932@item @emph{Class}: 9933Pure subroutine 9934 9935@item @emph{Syntax}: 9936@code{CALL MOVE_ALLOC(FROM, TO)} 9937 9938@item @emph{Arguments}: 9939@multitable @columnfractions .15 .70 9940@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be 9941of any type and kind. 9942@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be 9943of the same type, kind and rank as @var{FROM}. 9944@end multitable 9945 9946@item @emph{Return value}: 9947None 9948 9949@item @emph{Example}: 9950@smallexample 9951program test_move_alloc 9952 integer, allocatable :: a(:), b(:) 9953 9954 allocate(a(3)) 9955 a = [ 1, 2, 3 ] 9956 call move_alloc(a, b) 9957 print *, allocated(a), allocated(b) 9958 print *, b 9959end program test_move_alloc 9960@end smallexample 9961@end table 9962 9963 9964 9965@node MVBITS 9966@section @code{MVBITS} --- Move bits from one integer to another 9967@fnindex MVBITS 9968@cindex bits, move 9969 9970@table @asis 9971@item @emph{Description}: 9972Moves @var{LEN} bits from positions @var{FROMPOS} through 9973@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through 9974@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not 9975affected by the movement of bits is unchanged. The values of 9976@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than 9977@code{BIT_SIZE(FROM)}. 9978 9979@item @emph{Standard}: 9980Fortran 95 and later 9981 9982@item @emph{Class}: 9983Elemental subroutine 9984 9985@item @emph{Syntax}: 9986@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)} 9987 9988@item @emph{Arguments}: 9989@multitable @columnfractions .15 .70 9990@item @var{FROM} @tab The type shall be @code{INTEGER}. 9991@item @var{FROMPOS} @tab The type shall be @code{INTEGER}. 9992@item @var{LEN} @tab The type shall be @code{INTEGER}. 9993@item @var{TO} @tab The type shall be @code{INTEGER}, of the 9994same kind as @var{FROM}. 9995@item @var{TOPOS} @tab The type shall be @code{INTEGER}. 9996@end multitable 9997 9998@item @emph{See also}: 9999@ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR} 10000@end table 10001 10002 10003 10004@node NEAREST 10005@section @code{NEAREST} --- Nearest representable number 10006@fnindex NEAREST 10007@cindex real number, nearest different 10008@cindex floating point, nearest different 10009 10010@table @asis 10011@item @emph{Description}: 10012@code{NEAREST(X, S)} returns the processor-representable number nearest 10013to @code{X} in the direction indicated by the sign of @code{S}. 10014 10015@item @emph{Standard}: 10016Fortran 95 and later 10017 10018@item @emph{Class}: 10019Elemental function 10020 10021@item @emph{Syntax}: 10022@code{RESULT = NEAREST(X, S)} 10023 10024@item @emph{Arguments}: 10025@multitable @columnfractions .15 .70 10026@item @var{X} @tab Shall be of type @code{REAL}. 10027@item @var{S} @tab Shall be of type @code{REAL} and 10028not equal to zero. 10029@end multitable 10030 10031@item @emph{Return value}: 10032The return value is of the same type as @code{X}. If @code{S} is 10033positive, @code{NEAREST} returns the processor-representable number 10034greater than @code{X} and nearest to it. If @code{S} is negative, 10035@code{NEAREST} returns the processor-representable number smaller than 10036@code{X} and nearest to it. 10037 10038@item @emph{Example}: 10039@smallexample 10040program test_nearest 10041 real :: x, y 10042 x = nearest(42.0, 1.0) 10043 y = nearest(42.0, -1.0) 10044 write (*,"(3(G20.15))") x, y, x - y 10045end program test_nearest 10046@end smallexample 10047@end table 10048 10049 10050 10051@node NEW_LINE 10052@section @code{NEW_LINE} --- New line character 10053@fnindex NEW_LINE 10054@cindex newline 10055@cindex output, newline 10056 10057@table @asis 10058@item @emph{Description}: 10059@code{NEW_LINE(C)} returns the new-line character. 10060 10061@item @emph{Standard}: 10062Fortran 2003 and later 10063 10064@item @emph{Class}: 10065Inquiry function 10066 10067@item @emph{Syntax}: 10068@code{RESULT = NEW_LINE(C)} 10069 10070@item @emph{Arguments}: 10071@multitable @columnfractions .15 .70 10072@item @var{C} @tab The argument shall be a scalar or array of the 10073type @code{CHARACTER}. 10074@end multitable 10075 10076@item @emph{Return value}: 10077Returns a @var{CHARACTER} scalar of length one with the new-line character of 10078the same kind as parameter @var{C}. 10079 10080@item @emph{Example}: 10081@smallexample 10082program newline 10083 implicit none 10084 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' 10085end program newline 10086@end smallexample 10087@end table 10088 10089 10090 10091@node NINT 10092@section @code{NINT} --- Nearest whole number 10093@fnindex NINT 10094@fnindex IDNINT 10095@cindex rounding, nearest whole number 10096 10097@table @asis 10098@item @emph{Description}: 10099@code{NINT(A)} rounds its argument to the nearest whole number. 10100 10101@item @emph{Standard}: 10102Fortran 77 and later, with @var{KIND} argument Fortran 90 and later 10103 10104@item @emph{Class}: 10105Elemental function 10106 10107@item @emph{Syntax}: 10108@code{RESULT = NINT(A [, KIND])} 10109 10110@item @emph{Arguments}: 10111@multitable @columnfractions .15 .70 10112@item @var{A} @tab The type of the argument shall be @code{REAL}. 10113@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 10114expression indicating the kind parameter of the result. 10115@end multitable 10116 10117@item @emph{Return value}: 10118Returns @var{A} with the fractional portion of its magnitude eliminated by 10119rounding to the nearest whole number and with its sign preserved, 10120converted to an @code{INTEGER} of the default kind. 10121 10122@item @emph{Example}: 10123@smallexample 10124program test_nint 10125 real(4) x4 10126 real(8) x8 10127 x4 = 1.234E0_4 10128 x8 = 4.321_8 10129 print *, nint(x4), idnint(x8) 10130end program test_nint 10131@end smallexample 10132 10133@item @emph{Specific names}: 10134@multitable @columnfractions .20 .20 .20 .25 10135@item Name @tab Argument @tab Return Type @tab Standard 10136@item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later 10137@item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later 10138@end multitable 10139 10140@item @emph{See also}: 10141@ref{CEILING}, @ref{FLOOR} 10142 10143@end table 10144 10145 10146 10147@node NORM2 10148@section @code{NORM2} --- Euclidean vector norms 10149@fnindex NORM2 10150@cindex Euclidean vector norm 10151@cindex L2 vector norm 10152@cindex norm, Euclidean 10153 10154@table @asis 10155@item @emph{Description}: 10156Calculates the Euclidean vector norm (@math{L_2} norm) of 10157of @var{ARRAY} along dimension @var{DIM}. 10158 10159@item @emph{Standard}: 10160Fortran 2008 and later 10161 10162@item @emph{Class}: 10163Transformational function 10164 10165@item @emph{Syntax}: 10166@multitable @columnfractions .80 10167@item @code{RESULT = NORM2(ARRAY[, DIM])} 10168@end multitable 10169 10170@item @emph{Arguments}: 10171@multitable @columnfractions .15 .70 10172@item @var{ARRAY} @tab Shall be an array of type @code{REAL} 10173@item @var{DIM} @tab (Optional) shall be a scalar of type 10174@code{INTEGER} with a value in the range from 1 to n, where n 10175equals the rank of @var{ARRAY}. 10176@end multitable 10177 10178@item @emph{Return value}: 10179The result is of the same type as @var{ARRAY}. 10180 10181If @var{DIM} is absent, a scalar with the square root of the sum of all 10182elements in @var{ARRAY} squared is returned. Otherwise, an array of 10183rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a 10184shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped 10185is returned. 10186 10187@item @emph{Example}: 10188@smallexample 10189PROGRAM test_sum 10190 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] 10191 print *, NORM2(x) ! = sqrt(55.) ~ 7.416 10192END PROGRAM 10193@end smallexample 10194@end table 10195 10196 10197 10198@node NOT 10199@section @code{NOT} --- Logical negation 10200@fnindex NOT 10201@cindex bits, negate 10202@cindex bitwise logical not 10203@cindex logical not, bitwise 10204 10205@table @asis 10206@item @emph{Description}: 10207@code{NOT} returns the bitwise Boolean inverse of @var{I}. 10208 10209@item @emph{Standard}: 10210Fortran 95 and later 10211 10212@item @emph{Class}: 10213Elemental function 10214 10215@item @emph{Syntax}: 10216@code{RESULT = NOT(I)} 10217 10218@item @emph{Arguments}: 10219@multitable @columnfractions .15 .70 10220@item @var{I} @tab The type shall be @code{INTEGER}. 10221@end multitable 10222 10223@item @emph{Return value}: 10224The return type is @code{INTEGER}, of the same kind as the 10225argument. 10226 10227@item @emph{See also}: 10228@ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR} 10229 10230@end table 10231 10232 10233 10234@node NULL 10235@section @code{NULL} --- Function that returns an disassociated pointer 10236@fnindex NULL 10237@cindex pointer, status 10238@cindex pointer, disassociated 10239 10240@table @asis 10241@item @emph{Description}: 10242Returns a disassociated pointer. 10243 10244If @var{MOLD} is present, a disassociated pointer of the same type is 10245returned, otherwise the type is determined by context. 10246 10247In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003 10248includes cases where it is required. 10249 10250@item @emph{Standard}: 10251Fortran 95 and later 10252 10253@item @emph{Class}: 10254Transformational function 10255 10256@item @emph{Syntax}: 10257@code{PTR => NULL([MOLD])} 10258 10259@item @emph{Arguments}: 10260@multitable @columnfractions .15 .70 10261@item @var{MOLD} @tab (Optional) shall be a pointer of any association 10262status and of any type. 10263@end multitable 10264 10265@item @emph{Return value}: 10266A disassociated pointer. 10267 10268@item @emph{Example}: 10269@smallexample 10270REAL, POINTER, DIMENSION(:) :: VEC => NULL () 10271@end smallexample 10272 10273@item @emph{See also}: 10274@ref{ASSOCIATED} 10275@end table 10276 10277 10278 10279@node NUM_IMAGES 10280@section @code{NUM_IMAGES} --- Function that returns the number of images 10281@fnindex NUM_IMAGES 10282@cindex coarray, @code{NUM_IMAGES} 10283@cindex images, number of 10284 10285@table @asis 10286@item @emph{Description}: 10287Returns the number of images. 10288 10289@item @emph{Standard}: 10290Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument, 10291Technical Specification (TS) 18508 or later 10292 10293 10294@item @emph{Class}: 10295Transformational function 10296 10297@item @emph{Syntax}: 10298@code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} 10299 10300@item @emph{Arguments}: 10301@multitable @columnfractions .15 .70 10302@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 10303@item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression 10304@end multitable 10305 10306@item @emph{Return value}: 10307Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, 10308the number of images in the current team is returned. For values smaller or 10309equal distance to the initial team, it returns the number of images index 10310on the ancestor team which has a distance of @var{DISTANCE} from the invoking 10311team. If @var{DISTANCE} is larger than the distance to the initial team, the 10312number of images of the initial team is returned. If @var{FAILED} is not present 10313the total number of images is returned; if it has the value @code{.TRUE.}, 10314the number of failed images is returned, otherwise, the number of images which 10315do have not the failed status. 10316 10317@item @emph{Example}: 10318@smallexample 10319INTEGER :: value[*] 10320INTEGER :: i 10321value = THIS_IMAGE() 10322SYNC ALL 10323IF (THIS_IMAGE() == 1) THEN 10324 DO i = 1, NUM_IMAGES() 10325 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 10326 END DO 10327END IF 10328@end smallexample 10329 10330@item @emph{See also}: 10331@ref{THIS_IMAGE}, @ref{IMAGE_INDEX} 10332@end table 10333 10334 10335 10336@node OR 10337@section @code{OR} --- Bitwise logical OR 10338@fnindex OR 10339@cindex bitwise logical or 10340@cindex logical or, bitwise 10341 10342@table @asis 10343@item @emph{Description}: 10344Bitwise logical @code{OR}. 10345 10346This intrinsic routine is provided for backwards compatibility with 10347GNU Fortran 77. For integer arguments, programmers should consider 10348the use of the @ref{IOR} intrinsic defined by the Fortran standard. 10349 10350@item @emph{Standard}: 10351GNU extension 10352 10353@item @emph{Class}: 10354Function 10355 10356@item @emph{Syntax}: 10357@code{RESULT = OR(I, J)} 10358 10359@item @emph{Arguments}: 10360@multitable @columnfractions .15 .70 10361@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 10362type or a scalar @code{LOGICAL} type. 10363@item @var{J} @tab The type shall be the same as the type of @var{J}. 10364@end multitable 10365 10366@item @emph{Return value}: 10367The return type is either a scalar @code{INTEGER} or a scalar 10368@code{LOGICAL}. If the kind type parameters differ, then the 10369smaller kind type is implicitly converted to larger kind, and the 10370return has the larger kind. 10371 10372@item @emph{Example}: 10373@smallexample 10374PROGRAM test_or 10375 LOGICAL :: T = .TRUE., F = .FALSE. 10376 INTEGER :: a, b 10377 DATA a / Z'F' /, b / Z'3' / 10378 10379 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F) 10380 WRITE (*,*) OR(a, b) 10381END PROGRAM 10382@end smallexample 10383 10384@item @emph{See also}: 10385Fortran 95 elemental function: @ref{IOR} 10386@end table 10387 10388 10389 10390@node PACK 10391@section @code{PACK} --- Pack an array into an array of rank one 10392@fnindex PACK 10393@cindex array, packing 10394@cindex array, reduce dimension 10395@cindex array, gather elements 10396 10397@table @asis 10398@item @emph{Description}: 10399Stores the elements of @var{ARRAY} in an array of rank one. 10400 10401The beginning of the resulting array is made up of elements whose @var{MASK} 10402equals @code{TRUE}. Afterwards, positions are filled with elements taken from 10403@var{VECTOR}. 10404 10405@item @emph{Standard}: 10406Fortran 95 and later 10407 10408@item @emph{Class}: 10409Transformational function 10410 10411@item @emph{Syntax}: 10412@code{RESULT = PACK(ARRAY, MASK[,VECTOR])} 10413 10414@item @emph{Arguments}: 10415@multitable @columnfractions .15 .70 10416@item @var{ARRAY} @tab Shall be an array of any type. 10417@item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and 10418of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} 10419scalar. 10420@item @var{VECTOR} @tab (Optional) shall be an array of the same type 10421as @var{ARRAY} and of rank one. If present, the number of elements in 10422@var{VECTOR} shall be equal to or greater than the number of true elements 10423in @var{MASK}. If @var{MASK} is scalar, the number of elements in 10424@var{VECTOR} shall be equal to or greater than the number of elements in 10425@var{ARRAY}. 10426@end multitable 10427 10428@item @emph{Return value}: 10429The result is an array of rank one and the same type as that of @var{ARRAY}. 10430If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the 10431number of @code{TRUE} values in @var{MASK} otherwise. 10432 10433@item @emph{Example}: 10434Gathering nonzero elements from an array: 10435@smallexample 10436PROGRAM test_pack_1 10437 INTEGER :: m(6) 10438 m = (/ 1, 0, 0, 0, 5, 0 /) 10439 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5" 10440END PROGRAM 10441@end smallexample 10442 10443Gathering nonzero elements from an array and appending elements from @var{VECTOR}: 10444@smallexample 10445PROGRAM test_pack_2 10446 INTEGER :: m(4) 10447 m = (/ 1, 0, 0, 2 /) 10448 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4" 10449END PROGRAM 10450@end smallexample 10451 10452@item @emph{See also}: 10453@ref{UNPACK} 10454@end table 10455 10456 10457 10458@node PARITY 10459@section @code{PARITY} --- Reduction with exclusive OR 10460@fnindex PARITY 10461@cindex Parity 10462@cindex Reduction, XOR 10463@cindex XOR reduction 10464 10465@table @asis 10466@item @emph{Description}: 10467Calculates the parity, i.e. the reduction using @code{.XOR.}, 10468of @var{MASK} along dimension @var{DIM}. 10469 10470@item @emph{Standard}: 10471Fortran 2008 and later 10472 10473@item @emph{Class}: 10474Transformational function 10475 10476@item @emph{Syntax}: 10477@multitable @columnfractions .80 10478@item @code{RESULT = PARITY(MASK[, DIM])} 10479@end multitable 10480 10481@item @emph{Arguments}: 10482@multitable @columnfractions .15 .70 10483@item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL} 10484@item @var{DIM} @tab (Optional) shall be a scalar of type 10485@code{INTEGER} with a value in the range from 1 to n, where n 10486equals the rank of @var{MASK}. 10487@end multitable 10488 10489@item @emph{Return value}: 10490The result is of the same type as @var{MASK}. 10491 10492If @var{DIM} is absent, a scalar with the parity of all elements in 10493@var{MASK} is returned, i.e. true if an odd number of elements is 10494@code{.true.} and false otherwise. If @var{DIM} is present, an array 10495of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, 10496and a shape similar to that of @var{MASK} with dimension @var{DIM} 10497dropped is returned. 10498 10499@item @emph{Example}: 10500@smallexample 10501PROGRAM test_sum 10502 LOGICAL :: x(2) = [ .true., .false. ] 10503 print *, PARITY(x) ! prints "T" (true). 10504END PROGRAM 10505@end smallexample 10506@end table 10507 10508 10509 10510@node PERROR 10511@section @code{PERROR} --- Print system error message 10512@fnindex PERROR 10513@cindex system, error handling 10514 10515@table @asis 10516@item @emph{Description}: 10517Prints (on the C @code{stderr} stream) a newline-terminated error 10518message corresponding to the last system error. This is prefixed by 10519@var{STRING}, a colon and a space. See @code{perror(3)}. 10520 10521@item @emph{Standard}: 10522GNU extension 10523 10524@item @emph{Class}: 10525Subroutine 10526 10527@item @emph{Syntax}: 10528@code{CALL PERROR(STRING)} 10529 10530@item @emph{Arguments}: 10531@multitable @columnfractions .15 .70 10532@item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the 10533default kind. 10534@end multitable 10535 10536@item @emph{See also}: 10537@ref{IERRNO} 10538@end table 10539 10540 10541 10542@node POPCNT 10543@section @code{POPCNT} --- Number of bits set 10544@fnindex POPCNT 10545@cindex binary representation 10546@cindex bits set 10547 10548@table @asis 10549@item @emph{Description}: 10550@code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary 10551representation of @code{I}. 10552 10553@item @emph{Standard}: 10554Fortran 2008 and later 10555 10556@item @emph{Class}: 10557Elemental function 10558 10559@item @emph{Syntax}: 10560@code{RESULT = POPCNT(I)} 10561 10562@item @emph{Arguments}: 10563@multitable @columnfractions .15 .70 10564@item @var{I} @tab Shall be of type @code{INTEGER}. 10565@end multitable 10566 10567@item @emph{Return value}: 10568The return value is of type @code{INTEGER} and of the default integer 10569kind. 10570 10571@item @emph{See also}: 10572@ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ} 10573 10574@item @emph{Example}: 10575@smallexample 10576program test_population 10577 print *, popcnt(127), poppar(127) 10578 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 10579 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 10580end program test_population 10581@end smallexample 10582@end table 10583 10584 10585@node POPPAR 10586@section @code{POPPAR} --- Parity of the number of bits set 10587@fnindex POPPAR 10588@cindex binary representation 10589@cindex parity 10590 10591@table @asis 10592@item @emph{Description}: 10593@code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity 10594of the number of bits set ('1' bits) in the binary representation of 10595@code{I}. It is equal to 0 if @code{I} has an even number of bits set, 10596and 1 for an odd number of '1' bits. 10597 10598@item @emph{Standard}: 10599Fortran 2008 and later 10600 10601@item @emph{Class}: 10602Elemental function 10603 10604@item @emph{Syntax}: 10605@code{RESULT = POPPAR(I)} 10606 10607@item @emph{Arguments}: 10608@multitable @columnfractions .15 .70 10609@item @var{I} @tab Shall be of type @code{INTEGER}. 10610@end multitable 10611 10612@item @emph{Return value}: 10613The return value is of type @code{INTEGER} and of the default integer 10614kind. 10615 10616@item @emph{See also}: 10617@ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ} 10618 10619@item @emph{Example}: 10620@smallexample 10621program test_population 10622 print *, popcnt(127), poppar(127) 10623 print *, popcnt(huge(0_4)), poppar(huge(0_4)) 10624 print *, popcnt(huge(0_8)), poppar(huge(0_8)) 10625end program test_population 10626@end smallexample 10627@end table 10628 10629 10630 10631@node PRECISION 10632@section @code{PRECISION} --- Decimal precision of a real kind 10633@fnindex PRECISION 10634@cindex model representation, precision 10635 10636@table @asis 10637@item @emph{Description}: 10638@code{PRECISION(X)} returns the decimal precision in the model of the 10639type of @code{X}. 10640 10641@item @emph{Standard}: 10642Fortran 95 and later 10643 10644@item @emph{Class}: 10645Inquiry function 10646 10647@item @emph{Syntax}: 10648@code{RESULT = PRECISION(X)} 10649 10650@item @emph{Arguments}: 10651@multitable @columnfractions .15 .70 10652@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. 10653@end multitable 10654 10655@item @emph{Return value}: 10656The return value is of type @code{INTEGER} and of the default integer 10657kind. 10658 10659@item @emph{See also}: 10660@ref{SELECTED_REAL_KIND}, @ref{RANGE} 10661 10662@item @emph{Example}: 10663@smallexample 10664program prec_and_range 10665 real(kind=4) :: x(2) 10666 complex(kind=8) :: y 10667 10668 print *, precision(x), range(x) 10669 print *, precision(y), range(y) 10670end program prec_and_range 10671@end smallexample 10672@end table 10673 10674 10675 10676@node PRESENT 10677@section @code{PRESENT} --- Determine whether an optional dummy argument is specified 10678@fnindex PRESENT 10679 10680@table @asis 10681@item @emph{Description}: 10682Determines whether an optional dummy argument is present. 10683 10684@item @emph{Standard}: 10685Fortran 95 and later 10686 10687@item @emph{Class}: 10688Inquiry function 10689 10690@item @emph{Syntax}: 10691@code{RESULT = PRESENT(A)} 10692 10693@item @emph{Arguments}: 10694@multitable @columnfractions .15 .70 10695@item @var{A} @tab May be of any type and may be a pointer, scalar or array 10696value, or a dummy procedure. It shall be the name of an optional dummy argument 10697accessible within the current subroutine or function. 10698@end multitable 10699 10700@item @emph{Return value}: 10701Returns either @code{TRUE} if the optional argument @var{A} is present, or 10702@code{FALSE} otherwise. 10703 10704@item @emph{Example}: 10705@smallexample 10706PROGRAM test_present 10707 WRITE(*,*) f(), f(42) ! "F T" 10708CONTAINS 10709 LOGICAL FUNCTION f(x) 10710 INTEGER, INTENT(IN), OPTIONAL :: x 10711 f = PRESENT(x) 10712 END FUNCTION 10713END PROGRAM 10714@end smallexample 10715@end table 10716 10717 10718 10719@node PRODUCT 10720@section @code{PRODUCT} --- Product of array elements 10721@fnindex PRODUCT 10722@cindex array, product 10723@cindex array, multiply elements 10724@cindex array, conditionally multiply elements 10725@cindex multiply array elements 10726 10727@table @asis 10728@item @emph{Description}: 10729Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if 10730the corresponding element in @var{MASK} is @code{TRUE}. 10731 10732@item @emph{Standard}: 10733Fortran 95 and later 10734 10735@item @emph{Class}: 10736Transformational function 10737 10738@item @emph{Syntax}: 10739@multitable @columnfractions .80 10740@item @code{RESULT = PRODUCT(ARRAY[, MASK])} 10741@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])} 10742@end multitable 10743 10744@item @emph{Arguments}: 10745@multitable @columnfractions .15 .70 10746@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 10747@code{REAL} or @code{COMPLEX}. 10748@item @var{DIM} @tab (Optional) shall be a scalar of type 10749@code{INTEGER} with a value in the range from 1 to n, where n 10750equals the rank of @var{ARRAY}. 10751@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 10752and either be a scalar or an array of the same shape as @var{ARRAY}. 10753@end multitable 10754 10755@item @emph{Return value}: 10756The result is of the same type as @var{ARRAY}. 10757 10758If @var{DIM} is absent, a scalar with the product of all elements in 10759@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 10760the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 10761dimension @var{DIM} dropped is returned. 10762 10763 10764@item @emph{Example}: 10765@smallexample 10766PROGRAM test_product 10767 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 10768 print *, PRODUCT(x) ! all elements, product = 120 10769 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15 10770END PROGRAM 10771@end smallexample 10772 10773@item @emph{See also}: 10774@ref{SUM} 10775@end table 10776 10777 10778 10779@node RADIX 10780@section @code{RADIX} --- Base of a model number 10781@fnindex RADIX 10782@cindex model representation, base 10783@cindex model representation, radix 10784 10785@table @asis 10786@item @emph{Description}: 10787@code{RADIX(X)} returns the base of the model representing the entity @var{X}. 10788 10789@item @emph{Standard}: 10790Fortran 95 and later 10791 10792@item @emph{Class}: 10793Inquiry function 10794 10795@item @emph{Syntax}: 10796@code{RESULT = RADIX(X)} 10797 10798@item @emph{Arguments}: 10799@multitable @columnfractions .15 .70 10800@item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL} 10801@end multitable 10802 10803@item @emph{Return value}: 10804The return value is a scalar of type @code{INTEGER} and of the default 10805integer kind. 10806 10807@item @emph{See also}: 10808@ref{SELECTED_REAL_KIND} 10809 10810@item @emph{Example}: 10811@smallexample 10812program test_radix 10813 print *, "The radix for the default integer kind is", radix(0) 10814 print *, "The radix for the default real kind is", radix(0.0) 10815end program test_radix 10816@end smallexample 10817 10818@end table 10819 10820 10821 10822@node RAN 10823@section @code{RAN} --- Real pseudo-random number 10824@fnindex RAN 10825@cindex random number generation 10826 10827@table @asis 10828@item @emph{Description}: 10829For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is 10830provided as an alias for @code{RAND}. See @ref{RAND} for complete 10831documentation. 10832 10833@item @emph{Standard}: 10834GNU extension 10835 10836@item @emph{Class}: 10837Function 10838 10839@item @emph{See also}: 10840@ref{RAND}, @ref{RANDOM_NUMBER} 10841@end table 10842 10843 10844 10845@node RAND 10846@section @code{RAND} --- Real pseudo-random number 10847@fnindex RAND 10848@cindex random number generation 10849 10850@table @asis 10851@item @emph{Description}: 10852@code{RAND(FLAG)} returns a pseudo-random number from a uniform 10853distribution between 0 and 1. If @var{FLAG} is 0, the next number 10854in the current sequence is returned; if @var{FLAG} is 1, the generator 10855is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, 10856it is used as a new seed with @code{SRAND}. 10857 10858This intrinsic routine is provided for backwards compatibility with 10859GNU Fortran 77. It implements a simple modulo generator as provided 10860by @command{g77}. For new code, one should consider the use of 10861@ref{RANDOM_NUMBER} as it implements a superior algorithm. 10862 10863@item @emph{Standard}: 10864GNU extension 10865 10866@item @emph{Class}: 10867Function 10868 10869@item @emph{Syntax}: 10870@code{RESULT = RAND(I)} 10871 10872@item @emph{Arguments}: 10873@multitable @columnfractions .15 .70 10874@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. 10875@end multitable 10876 10877@item @emph{Return value}: 10878The return value is of @code{REAL} type and the default kind. 10879 10880@item @emph{Example}: 10881@smallexample 10882program test_rand 10883 integer,parameter :: seed = 86456 10884 10885 call srand(seed) 10886 print *, rand(), rand(), rand(), rand() 10887 print *, rand(seed), rand(), rand(), rand() 10888end program test_rand 10889@end smallexample 10890 10891@item @emph{See also}: 10892@ref{SRAND}, @ref{RANDOM_NUMBER} 10893 10894@end table 10895 10896 10897 10898@node RANDOM_NUMBER 10899@section @code{RANDOM_NUMBER} --- Pseudo-random number 10900@fnindex RANDOM_NUMBER 10901@cindex random number generation 10902 10903@table @asis 10904@item @emph{Description}: 10905Returns a single pseudorandom number or an array of pseudorandom numbers 10906from the uniform distribution over the range @math{ 0 \leq x < 1}. 10907 10908The runtime-library implements George Marsaglia's KISS (Keep It Simple 10909Stupid) random number generator (RNG). This RNG combines: 10910@enumerate 10911@item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885} 10912with a period of @math{2^{32}}, 10913@item A 3-shift shift-register generator with a period of @math{2^{32} - 1}, 10914@item Two 16-bit multiply-with-carry generators with a period of 10915@math{597273182964842497 > 2^{59}}. 10916@end enumerate 10917The overall period exceeds @math{2^{123}}. 10918 10919Please note, this RNG is thread safe if used within OpenMP directives, 10920i.e., its state will be consistent while called from multiple threads. 10921However, the KISS generator does not create random numbers in parallel 10922from multiple sources, but in sequence from a single source. If an 10923OpenMP-enabled application heavily relies on random numbers, one should 10924consider employing a dedicated parallel random number generator instead. 10925 10926@item @emph{Standard}: 10927Fortran 95 and later 10928 10929@item @emph{Class}: 10930Subroutine 10931 10932@item @emph{Syntax}: 10933@code{RANDOM_NUMBER(HARVEST)} 10934 10935@item @emph{Arguments}: 10936@multitable @columnfractions .15 .70 10937@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}. 10938@end multitable 10939 10940@item @emph{Example}: 10941@smallexample 10942program test_random_number 10943 REAL :: r(5,5) 10944 CALL init_random_seed() ! see example of RANDOM_SEED 10945 CALL RANDOM_NUMBER(r) 10946end program 10947@end smallexample 10948 10949@item @emph{See also}: 10950@ref{RANDOM_SEED} 10951@end table 10952 10953 10954 10955@node RANDOM_SEED 10956@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence 10957@fnindex RANDOM_SEED 10958@cindex random number generation, seeding 10959@cindex seeding a random number generator 10960 10961@table @asis 10962@item @emph{Description}: 10963Restarts or queries the state of the pseudorandom number generator used by 10964@code{RANDOM_NUMBER}. 10965 10966If @code{RANDOM_SEED} is called without arguments, it is initialized 10967to a default state. The example below shows how to initialize the 10968random seed with a varying seed in order to ensure a different random 10969number sequence for each invocation of the program. Note that setting 10970any of the seed values to zero should be avoided as it can result in 10971poor quality random numbers being generated. 10972 10973@item @emph{Standard}: 10974Fortran 95 and later 10975 10976@item @emph{Class}: 10977Subroutine 10978 10979@item @emph{Syntax}: 10980@code{CALL RANDOM_SEED([SIZE, PUT, GET])} 10981 10982@item @emph{Arguments}: 10983@multitable @columnfractions .15 .70 10984@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default 10985@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size 10986of the arrays used with the @var{PUT} and @var{GET} arguments. 10987@item @var{PUT} @tab (Optional) Shall be an array of type default 10988@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of 10989the array must be larger than or equal to the number returned by the 10990@var{SIZE} argument. 10991@item @var{GET} @tab (Optional) Shall be an array of type default 10992@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size 10993of the array must be larger than or equal to the number returned by 10994the @var{SIZE} argument. 10995@end multitable 10996 10997@item @emph{Example}: 10998@smallexample 10999subroutine init_random_seed() 11000 use iso_fortran_env, only: int64 11001 implicit none 11002 integer, allocatable :: seed(:) 11003 integer :: i, n, un, istat, dt(8), pid 11004 integer(int64) :: t 11005 11006 call random_seed(size = n) 11007 allocate(seed(n)) 11008 ! First try if the OS provides a random number generator 11009 open(newunit=un, file="/dev/urandom", access="stream", & 11010 form="unformatted", action="read", status="old", iostat=istat) 11011 if (istat == 0) then 11012 read(un) seed 11013 close(un) 11014 else 11015 ! Fallback to XOR:ing the current time and pid. The PID is 11016 ! useful in case one launches multiple instances of the same 11017 ! program in parallel. 11018 call system_clock(t) 11019 if (t == 0) then 11020 call date_and_time(values=dt) 11021 t = (dt(1) - 1970) * 365_int64 * 24 * 60 * 60 * 1000 & 11022 + dt(2) * 31_int64 * 24 * 60 * 60 * 1000 & 11023 + dt(3) * 24_int64 * 60 * 60 * 1000 & 11024 + dt(5) * 60 * 60 * 1000 & 11025 + dt(6) * 60 * 1000 + dt(7) * 1000 & 11026 + dt(8) 11027 end if 11028 pid = getpid() 11029 t = ieor(t, int(pid, kind(t))) 11030 do i = 1, n 11031 seed(i) = lcg(t) 11032 end do 11033 end if 11034 call random_seed(put=seed) 11035contains 11036 ! This simple PRNG might not be good enough for real work, but is 11037 ! sufficient for seeding a better PRNG. 11038 function lcg(s) 11039 integer :: lcg 11040 integer(int64) :: s 11041 if (s == 0) then 11042 s = 104729 11043 else 11044 s = mod(s, 4294967296_int64) 11045 end if 11046 s = mod(s * 279470273_int64, 4294967291_int64) 11047 lcg = int(mod(s, int(huge(0), int64)), kind(0)) 11048 end function lcg 11049end subroutine init_random_seed 11050@end smallexample 11051 11052@item @emph{See also}: 11053@ref{RANDOM_NUMBER} 11054@end table 11055 11056 11057 11058@node RANGE 11059@section @code{RANGE} --- Decimal exponent range 11060@fnindex RANGE 11061@cindex model representation, range 11062 11063@table @asis 11064@item @emph{Description}: 11065@code{RANGE(X)} returns the decimal exponent range in the model of the 11066type of @code{X}. 11067 11068@item @emph{Standard}: 11069Fortran 95 and later 11070 11071@item @emph{Class}: 11072Inquiry function 11073 11074@item @emph{Syntax}: 11075@code{RESULT = RANGE(X)} 11076 11077@item @emph{Arguments}: 11078@multitable @columnfractions .15 .70 11079@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL} 11080or @code{COMPLEX}. 11081@end multitable 11082 11083@item @emph{Return value}: 11084The return value is of type @code{INTEGER} and of the default integer 11085kind. 11086 11087@item @emph{See also}: 11088@ref{SELECTED_REAL_KIND}, @ref{PRECISION} 11089 11090@item @emph{Example}: 11091See @code{PRECISION} for an example. 11092@end table 11093 11094 11095 11096@node RANK 11097@section @code{RANK} --- Rank of a data object 11098@fnindex RANK 11099@cindex rank 11100 11101@table @asis 11102@item @emph{Description}: 11103@code{RANK(A)} returns the rank of a scalar or array data object. 11104 11105@item @emph{Standard}: 11106Technical Specification (TS) 29113 11107 11108@item @emph{Class}: 11109Inquiry function 11110 11111@item @emph{Syntax}: 11112@code{RESULT = RANK(A)} 11113 11114@item @emph{Arguments}: 11115@multitable @columnfractions .15 .70 11116@item @var{A} @tab can be of any type 11117@end multitable 11118 11119@item @emph{Return value}: 11120The return value is of type @code{INTEGER} and of the default integer 11121kind. For arrays, their rank is returned; for scalars zero is returned. 11122 11123@item @emph{Example}: 11124@smallexample 11125program test_rank 11126 integer :: a 11127 real, allocatable :: b(:,:) 11128 11129 print *, rank(a), rank(b) ! Prints: 0 2 11130end program test_rank 11131@end smallexample 11132 11133@end table 11134 11135 11136 11137@node REAL 11138@section @code{REAL} --- Convert to real type 11139@fnindex REAL 11140@fnindex REALPART 11141@fnindex FLOAT 11142@fnindex DFLOAT 11143@fnindex SNGL 11144@cindex conversion, to real 11145@cindex complex numbers, real part 11146 11147@table @asis 11148@item @emph{Description}: 11149@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The 11150@code{REALPART} function is provided for compatibility with @command{g77}, 11151and its use is strongly discouraged. 11152 11153@item @emph{Standard}: 11154Fortran 77 and later 11155 11156@item @emph{Class}: 11157Elemental function 11158 11159@item @emph{Syntax}: 11160@multitable @columnfractions .80 11161@item @code{RESULT = REAL(A [, KIND])} 11162@item @code{RESULT = REALPART(Z)} 11163@end multitable 11164 11165@item @emph{Arguments}: 11166@multitable @columnfractions .15 .70 11167@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or 11168@code{COMPLEX}. 11169@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 11170expression indicating the kind parameter of the result. 11171@end multitable 11172 11173@item @emph{Return value}: 11174These functions return a @code{REAL} variable or array under 11175the following rules: 11176 11177@table @asis 11178@item (A) 11179@code{REAL(A)} is converted to a default real type if @var{A} is an 11180integer or real variable. 11181@item (B) 11182@code{REAL(A)} is converted to a real type with the kind type parameter 11183of @var{A} if @var{A} is a complex variable. 11184@item (C) 11185@code{REAL(A, KIND)} is converted to a real type with kind type 11186parameter @var{KIND} if @var{A} is a complex, integer, or real 11187variable. 11188@end table 11189 11190@item @emph{Example}: 11191@smallexample 11192program test_real 11193 complex :: x = (1.0, 2.0) 11194 print *, real(x), real(x,8), realpart(x) 11195end program test_real 11196@end smallexample 11197 11198@item @emph{Specific names}: 11199@multitable @columnfractions .20 .20 .20 .25 11200@item Name @tab Argument @tab Return type @tab Standard 11201@item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later 11202@item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension 11203@item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later 11204@end multitable 11205 11206 11207@item @emph{See also}: 11208@ref{DBLE} 11209 11210@end table 11211 11212 11213 11214@node RENAME 11215@section @code{RENAME} --- Rename a file 11216@fnindex RENAME 11217@cindex file system, rename file 11218 11219@table @asis 11220@item @emph{Description}: 11221Renames a file from file @var{PATH1} to @var{PATH2}. A null 11222character (@code{CHAR(0)}) can be used to mark the end of the names in 11223@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 11224names are ignored. If the @var{STATUS} argument is supplied, it 11225contains 0 on success or a nonzero error code upon return; see 11226@code{rename(2)}. 11227 11228This intrinsic is provided in both subroutine and function forms; 11229however, only one form can be used in any given program unit. 11230 11231@item @emph{Standard}: 11232GNU extension 11233 11234@item @emph{Class}: 11235Subroutine, function 11236 11237@item @emph{Syntax}: 11238@multitable @columnfractions .80 11239@item @code{CALL RENAME(PATH1, PATH2 [, STATUS])} 11240@item @code{STATUS = RENAME(PATH1, PATH2)} 11241@end multitable 11242 11243@item @emph{Arguments}: 11244@multitable @columnfractions .15 .70 11245@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 11246@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 11247@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 11248@end multitable 11249 11250@item @emph{See also}: 11251@ref{LINK} 11252 11253@end table 11254 11255 11256 11257@node REPEAT 11258@section @code{REPEAT} --- Repeated string concatenation 11259@fnindex REPEAT 11260@cindex string, repeat 11261@cindex string, concatenate 11262 11263@table @asis 11264@item @emph{Description}: 11265Concatenates @var{NCOPIES} copies of a string. 11266 11267@item @emph{Standard}: 11268Fortran 95 and later 11269 11270@item @emph{Class}: 11271Transformational function 11272 11273@item @emph{Syntax}: 11274@code{RESULT = REPEAT(STRING, NCOPIES)} 11275 11276@item @emph{Arguments}: 11277@multitable @columnfractions .15 .70 11278@item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}. 11279@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}. 11280@end multitable 11281 11282@item @emph{Return value}: 11283A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies 11284of @var{STRING}. 11285 11286@item @emph{Example}: 11287@smallexample 11288program test_repeat 11289 write(*,*) repeat("x", 5) ! "xxxxx" 11290end program 11291@end smallexample 11292@end table 11293 11294 11295 11296@node RESHAPE 11297@section @code{RESHAPE} --- Function to reshape an array 11298@fnindex RESHAPE 11299@cindex array, change dimensions 11300@cindex array, transmogrify 11301 11302@table @asis 11303@item @emph{Description}: 11304Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary, 11305the new array may be padded with elements from @var{PAD} or permuted 11306as defined by @var{ORDER}. 11307 11308@item @emph{Standard}: 11309Fortran 95 and later 11310 11311@item @emph{Class}: 11312Transformational function 11313 11314@item @emph{Syntax}: 11315@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])} 11316 11317@item @emph{Arguments}: 11318@multitable @columnfractions .15 .70 11319@item @var{SOURCE} @tab Shall be an array of any type. 11320@item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an 11321array of rank one. Its values must be positive or zero. 11322@item @var{PAD} @tab (Optional) shall be an array of the same 11323type as @var{SOURCE}. 11324@item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER} 11325and an array of the same shape as @var{SHAPE}. Its values shall 11326be a permutation of the numbers from 1 to n, where n is the size of 11327@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall 11328be assumed. 11329@end multitable 11330 11331@item @emph{Return value}: 11332The result is an array of shape @var{SHAPE} with the same type as 11333@var{SOURCE}. 11334 11335@item @emph{Example}: 11336@smallexample 11337PROGRAM test_reshape 11338 INTEGER, DIMENSION(4) :: x 11339 WRITE(*,*) SHAPE(x) ! prints "4" 11340 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" 11341END PROGRAM 11342@end smallexample 11343 11344@item @emph{See also}: 11345@ref{SHAPE} 11346@end table 11347 11348 11349 11350@node RRSPACING 11351@section @code{RRSPACING} --- Reciprocal of the relative spacing 11352@fnindex RRSPACING 11353@cindex real number, relative spacing 11354@cindex floating point, relative spacing 11355 11356 11357@table @asis 11358@item @emph{Description}: 11359@code{RRSPACING(X)} returns the reciprocal of the relative spacing of 11360model numbers near @var{X}. 11361 11362@item @emph{Standard}: 11363Fortran 95 and later 11364 11365@item @emph{Class}: 11366Elemental function 11367 11368@item @emph{Syntax}: 11369@code{RESULT = RRSPACING(X)} 11370 11371@item @emph{Arguments}: 11372@multitable @columnfractions .15 .70 11373@item @var{X} @tab Shall be of type @code{REAL}. 11374@end multitable 11375 11376@item @emph{Return value}: 11377The return value is of the same type and kind as @var{X}. 11378The value returned is equal to 11379@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}. 11380 11381@item @emph{See also}: 11382@ref{SPACING} 11383@end table 11384 11385 11386 11387@node RSHIFT 11388@section @code{RSHIFT} --- Right shift bits 11389@fnindex RSHIFT 11390@cindex bits, shift right 11391 11392@table @asis 11393@item @emph{Description}: 11394@code{RSHIFT} returns a value corresponding to @var{I} with all of the 11395bits shifted right by @var{SHIFT} places. If the absolute value of 11396@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 11397Bits shifted out from the right end are lost. The fill is arithmetic: the 11398bits shifted in from the left end are equal to the leftmost bit, which in 11399two's complement representation is the sign bit. 11400 11401This function has been superseded by the @code{SHIFTA} intrinsic, which 11402is standard in Fortran 2008 and later. 11403 11404@item @emph{Standard}: 11405GNU extension 11406 11407@item @emph{Class}: 11408Elemental function 11409 11410@item @emph{Syntax}: 11411@code{RESULT = RSHIFT(I, SHIFT)} 11412 11413@item @emph{Arguments}: 11414@multitable @columnfractions .15 .70 11415@item @var{I} @tab The type shall be @code{INTEGER}. 11416@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 11417@end multitable 11418 11419@item @emph{Return value}: 11420The return value is of type @code{INTEGER} and of the same kind as 11421@var{I}. 11422 11423@item @emph{See also}: 11424@ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR}, 11425@ref{SHIFTL} 11426 11427@end table 11428 11429 11430 11431@node SAME_TYPE_AS 11432@section @code{SAME_TYPE_AS} --- Query dynamic types for equality 11433@fnindex SAME_TYPE_AS 11434 11435@table @asis 11436@item @emph{Description}: 11437Query dynamic types for equality. 11438 11439@item @emph{Standard}: 11440Fortran 2003 and later 11441 11442@item @emph{Class}: 11443Inquiry function 11444 11445@item @emph{Syntax}: 11446@code{RESULT = SAME_TYPE_AS(A, B)} 11447 11448@item @emph{Arguments}: 11449@multitable @columnfractions .15 .70 11450@item @var{A} @tab Shall be an object of extensible declared type or 11451unlimited polymorphic. 11452@item @var{B} @tab Shall be an object of extensible declared type or 11453unlimited polymorphic. 11454@end multitable 11455 11456@item @emph{Return value}: 11457The return value is a scalar of type default logical. It is true if and 11458only if the dynamic type of A is the same as the dynamic type of B. 11459 11460@item @emph{See also}: 11461@ref{EXTENDS_TYPE_OF} 11462 11463@end table 11464 11465 11466 11467@node SCALE 11468@section @code{SCALE} --- Scale a real value 11469@fnindex SCALE 11470@cindex real number, scale 11471@cindex floating point, scale 11472 11473@table @asis 11474@item @emph{Description}: 11475@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}. 11476 11477@item @emph{Standard}: 11478Fortran 95 and later 11479 11480@item @emph{Class}: 11481Elemental function 11482 11483@item @emph{Syntax}: 11484@code{RESULT = SCALE(X, I)} 11485 11486@item @emph{Arguments}: 11487@multitable @columnfractions .15 .70 11488@item @var{X} @tab The type of the argument shall be a @code{REAL}. 11489@item @var{I} @tab The type of the argument shall be a @code{INTEGER}. 11490@end multitable 11491 11492@item @emph{Return value}: 11493The return value is of the same type and kind as @var{X}. 11494Its value is @code{X * RADIX(X)**I}. 11495 11496@item @emph{Example}: 11497@smallexample 11498program test_scale 11499 real :: x = 178.1387e-4 11500 integer :: i = 5 11501 print *, scale(x,i), x*radix(x)**i 11502end program test_scale 11503@end smallexample 11504 11505@end table 11506 11507 11508 11509@node SCAN 11510@section @code{SCAN} --- Scan a string for the presence of a set of characters 11511@fnindex SCAN 11512@cindex string, find subset 11513 11514@table @asis 11515@item @emph{Description}: 11516Scans a @var{STRING} for any of the characters in a @var{SET} 11517of characters. 11518 11519If @var{BACK} is either absent or equals @code{FALSE}, this function 11520returns the position of the leftmost character of @var{STRING} that is 11521in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position 11522is returned. If no character of @var{SET} is found in @var{STRING}, the 11523result is zero. 11524 11525@item @emph{Standard}: 11526Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 11527 11528@item @emph{Class}: 11529Elemental function 11530 11531@item @emph{Syntax}: 11532@code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])} 11533 11534@item @emph{Arguments}: 11535@multitable @columnfractions .15 .70 11536@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 11537@item @var{SET} @tab Shall be of type @code{CHARACTER}. 11538@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 11539@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 11540expression indicating the kind parameter of the result. 11541@end multitable 11542 11543@item @emph{Return value}: 11544The return value is of type @code{INTEGER} and of kind @var{KIND}. If 11545@var{KIND} is absent, the return value is of default integer kind. 11546 11547@item @emph{Example}: 11548@smallexample 11549PROGRAM test_scan 11550 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O' 11551 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A' 11552 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none 11553END PROGRAM 11554@end smallexample 11555 11556@item @emph{See also}: 11557@ref{INDEX intrinsic}, @ref{VERIFY} 11558@end table 11559 11560 11561 11562@node SECNDS 11563@section @code{SECNDS} --- Time function 11564@fnindex SECNDS 11565@cindex time, elapsed 11566@cindex elapsed time 11567 11568@table @asis 11569@item @emph{Description}: 11570@code{SECNDS(X)} gets the time in seconds from the real-time system clock. 11571@var{X} is a reference time, also in seconds. If this is zero, the time in 11572seconds from midnight is returned. This function is non-standard and its 11573use is discouraged. 11574 11575@item @emph{Standard}: 11576GNU extension 11577 11578@item @emph{Class}: 11579Function 11580 11581@item @emph{Syntax}: 11582@code{RESULT = SECNDS (X)} 11583 11584@item @emph{Arguments}: 11585@multitable @columnfractions .15 .70 11586@item @var{T} @tab Shall be of type @code{REAL(4)}. 11587@item @var{X} @tab Shall be of type @code{REAL(4)}. 11588@end multitable 11589 11590@item @emph{Return value}: 11591None 11592 11593@item @emph{Example}: 11594@smallexample 11595program test_secnds 11596 integer :: i 11597 real(4) :: t1, t2 11598 print *, secnds (0.0) ! seconds since midnight 11599 t1 = secnds (0.0) ! reference time 11600 do i = 1, 10000000 ! do something 11601 end do 11602 t2 = secnds (t1) ! elapsed time 11603 print *, "Something took ", t2, " seconds." 11604end program test_secnds 11605@end smallexample 11606@end table 11607 11608 11609 11610@node SECOND 11611@section @code{SECOND} --- CPU time function 11612@fnindex SECOND 11613@cindex time, elapsed 11614@cindex elapsed time 11615 11616@table @asis 11617@item @emph{Description}: 11618Returns a @code{REAL(4)} value representing the elapsed CPU time in 11619seconds. This provides the same functionality as the standard 11620@code{CPU_TIME} intrinsic, and is only included for backwards 11621compatibility. 11622 11623This intrinsic is provided in both subroutine and function forms; 11624however, only one form can be used in any given program unit. 11625 11626@item @emph{Standard}: 11627GNU extension 11628 11629@item @emph{Class}: 11630Subroutine, function 11631 11632@item @emph{Syntax}: 11633@multitable @columnfractions .80 11634@item @code{CALL SECOND(TIME)} 11635@item @code{TIME = SECOND()} 11636@end multitable 11637 11638@item @emph{Arguments}: 11639@multitable @columnfractions .15 .70 11640@item @var{TIME} @tab Shall be of type @code{REAL(4)}. 11641@end multitable 11642 11643@item @emph{Return value}: 11644In either syntax, @var{TIME} is set to the process's current runtime in 11645seconds. 11646 11647@item @emph{See also}: 11648@ref{CPU_TIME} 11649 11650@end table 11651 11652 11653 11654@node SELECTED_CHAR_KIND 11655@section @code{SELECTED_CHAR_KIND} --- Choose character kind 11656@fnindex SELECTED_CHAR_KIND 11657@cindex character kind 11658@cindex kind, character 11659 11660@table @asis 11661@item @emph{Description}: 11662 11663@code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character 11664set named @var{NAME}, if a character set with such a name is supported, 11665or @math{-1} otherwise. Currently, supported character sets include 11666``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646'' 11667(Universal Character Set, UCS-4) which is commonly known as Unicode. 11668 11669@item @emph{Standard}: 11670Fortran 2003 and later 11671 11672@item @emph{Class}: 11673Transformational function 11674 11675@item @emph{Syntax}: 11676@code{RESULT = SELECTED_CHAR_KIND(NAME)} 11677 11678@item @emph{Arguments}: 11679@multitable @columnfractions .15 .70 11680@item @var{NAME} @tab Shall be a scalar and of the default character type. 11681@end multitable 11682 11683@item @emph{Example}: 11684@smallexample 11685program character_kind 11686 use iso_fortran_env 11687 implicit none 11688 integer, parameter :: ascii = selected_char_kind ("ascii") 11689 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646') 11690 11691 character(kind=ascii, len=26) :: alphabet 11692 character(kind=ucs4, len=30) :: hello_world 11693 11694 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz" 11695 hello_world = ucs4_'Hello World and Ni Hao -- ' & 11696 // char (int (z'4F60'), ucs4) & 11697 // char (int (z'597D'), ucs4) 11698 11699 write (*,*) alphabet 11700 11701 open (output_unit, encoding='UTF-8') 11702 write (*,*) trim (hello_world) 11703end program character_kind 11704@end smallexample 11705@end table 11706 11707 11708 11709@node SELECTED_INT_KIND 11710@section @code{SELECTED_INT_KIND} --- Choose integer kind 11711@fnindex SELECTED_INT_KIND 11712@cindex integer kind 11713@cindex kind, integer 11714 11715@table @asis 11716@item @emph{Description}: 11717@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer 11718type that can represent all values ranging from @math{-10^R} (exclusive) 11719to @math{10^R} (exclusive). If there is no integer kind that accommodates 11720this range, @code{SELECTED_INT_KIND} returns @math{-1}. 11721 11722@item @emph{Standard}: 11723Fortran 95 and later 11724 11725@item @emph{Class}: 11726Transformational function 11727 11728@item @emph{Syntax}: 11729@code{RESULT = SELECTED_INT_KIND(R)} 11730 11731@item @emph{Arguments}: 11732@multitable @columnfractions .15 .70 11733@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}. 11734@end multitable 11735 11736@item @emph{Example}: 11737@smallexample 11738program large_integers 11739 integer,parameter :: k5 = selected_int_kind(5) 11740 integer,parameter :: k15 = selected_int_kind(15) 11741 integer(kind=k5) :: i5 11742 integer(kind=k15) :: i15 11743 11744 print *, huge(i5), huge(i15) 11745 11746 ! The following inequalities are always true 11747 print *, huge(i5) >= 10_k5**5-1 11748 print *, huge(i15) >= 10_k15**15-1 11749end program large_integers 11750@end smallexample 11751@end table 11752 11753 11754 11755@node SELECTED_REAL_KIND 11756@section @code{SELECTED_REAL_KIND} --- Choose real kind 11757@fnindex SELECTED_REAL_KIND 11758@cindex real kind 11759@cindex kind, real 11760@cindex radix, real 11761 11762@table @asis 11763@item @emph{Description}: 11764@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type 11765with decimal precision of at least @code{P} digits, exponent range of 11766at least @code{R}, and with a radix of @code{RADIX}. 11767 11768@item @emph{Standard}: 11769Fortran 95 and later, with @code{RADIX} Fortran 2008 or later 11770 11771@item @emph{Class}: 11772Transformational function 11773 11774@item @emph{Syntax}: 11775@code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])} 11776 11777@item @emph{Arguments}: 11778@multitable @columnfractions .15 .70 11779@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 11780@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 11781@item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}. 11782@end multitable 11783Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall 11784be present; since Fortran 2008, they are assumed to be zero if absent. 11785 11786@item @emph{Return value}: 11787 11788@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of 11789a real data type with decimal precision of at least @code{P} digits, a 11790decimal exponent range of at least @code{R}, and with the requested 11791@code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with 11792any radix can be returned. If more than one real data type meet the 11793criteria, the kind of the data type with the smallest decimal precision 11794is returned. If no real data type matches the criteria, the result is 11795@table @asis 11796@item -1 if the processor does not support a real data type with a 11797precision greater than or equal to @code{P}, but the @code{R} and 11798@code{RADIX} requirements can be fulfilled 11799@item -2 if the processor does not support a real type with an exponent 11800range greater than or equal to @code{R}, but @code{P} and @code{RADIX} 11801are fulfillable 11802@item -3 if @code{RADIX} but not @code{P} and @code{R} requirements 11803are fulfillable 11804@item -4 if @code{RADIX} and either @code{P} or @code{R} requirements 11805are fulfillable 11806@item -5 if there is no real type with the given @code{RADIX} 11807@end table 11808 11809@item @emph{See also}: 11810@ref{PRECISION}, @ref{RANGE}, @ref{RADIX} 11811 11812@item @emph{Example}: 11813@smallexample 11814program real_kinds 11815 integer,parameter :: p6 = selected_real_kind(6) 11816 integer,parameter :: p10r100 = selected_real_kind(10,100) 11817 integer,parameter :: r400 = selected_real_kind(r=400) 11818 real(kind=p6) :: x 11819 real(kind=p10r100) :: y 11820 real(kind=r400) :: z 11821 11822 print *, precision(x), range(x) 11823 print *, precision(y), range(y) 11824 print *, precision(z), range(z) 11825end program real_kinds 11826@end smallexample 11827@end table 11828 11829 11830 11831@node SET_EXPONENT 11832@section @code{SET_EXPONENT} --- Set the exponent of the model 11833@fnindex SET_EXPONENT 11834@cindex real number, set exponent 11835@cindex floating point, set exponent 11836 11837@table @asis 11838@item @emph{Description}: 11839@code{SET_EXPONENT(X, I)} returns the real number whose fractional part 11840is that that of @var{X} and whose exponent part is @var{I}. 11841 11842@item @emph{Standard}: 11843Fortran 95 and later 11844 11845@item @emph{Class}: 11846Elemental function 11847 11848@item @emph{Syntax}: 11849@code{RESULT = SET_EXPONENT(X, I)} 11850 11851@item @emph{Arguments}: 11852@multitable @columnfractions .15 .70 11853@item @var{X} @tab Shall be of type @code{REAL}. 11854@item @var{I} @tab Shall be of type @code{INTEGER}. 11855@end multitable 11856 11857@item @emph{Return value}: 11858The return value is of the same type and kind as @var{X}. 11859The real number whose fractional part 11860is that that of @var{X} and whose exponent part if @var{I} is returned; 11861it is @code{FRACTION(X) * RADIX(X)**I}. 11862 11863@item @emph{Example}: 11864@smallexample 11865PROGRAM test_setexp 11866 REAL :: x = 178.1387e-4 11867 INTEGER :: i = 17 11868 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i 11869END PROGRAM 11870@end smallexample 11871 11872@end table 11873 11874 11875 11876@node SHAPE 11877@section @code{SHAPE} --- Determine the shape of an array 11878@fnindex SHAPE 11879@cindex array, shape 11880 11881@table @asis 11882@item @emph{Description}: 11883Determines the shape of an array. 11884 11885@item @emph{Standard}: 11886Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 11887 11888@item @emph{Class}: 11889Inquiry function 11890 11891@item @emph{Syntax}: 11892@code{RESULT = SHAPE(SOURCE [, KIND])} 11893 11894@item @emph{Arguments}: 11895@multitable @columnfractions .15 .70 11896@item @var{SOURCE} @tab Shall be an array or scalar of any type. 11897If @var{SOURCE} is a pointer it must be associated and allocatable 11898arrays must be allocated. 11899@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 11900expression indicating the kind parameter of the result. 11901@end multitable 11902 11903@item @emph{Return value}: 11904An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 11905has dimensions. The elements of the resulting array correspond to the extend 11906of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar, 11907the result is the rank one array of size zero. If @var{KIND} is absent, the 11908return value has the default integer kind otherwise the specified kind. 11909 11910@item @emph{Example}: 11911@smallexample 11912PROGRAM test_shape 11913 INTEGER, DIMENSION(-1:1, -1:2) :: A 11914 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) 11915 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) 11916END PROGRAM 11917@end smallexample 11918 11919@item @emph{See also}: 11920@ref{RESHAPE}, @ref{SIZE} 11921@end table 11922 11923 11924 11925@node SHIFTA 11926@section @code{SHIFTA} --- Right shift with fill 11927@fnindex SHIFTA 11928@cindex bits, shift right 11929@cindex shift, right with fill 11930 11931@table @asis 11932@item @emph{Description}: 11933@code{SHIFTA} returns a value corresponding to @var{I} with all of the 11934bits shifted right by @var{SHIFT} places. If the absolute value of 11935@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 11936Bits shifted out from the right end are lost. The fill is arithmetic: the 11937bits shifted in from the left end are equal to the leftmost bit, which in 11938two's complement representation is the sign bit. 11939 11940@item @emph{Standard}: 11941Fortran 2008 and later 11942 11943@item @emph{Class}: 11944Elemental function 11945 11946@item @emph{Syntax}: 11947@code{RESULT = SHIFTA(I, SHIFT)} 11948 11949@item @emph{Arguments}: 11950@multitable @columnfractions .15 .70 11951@item @var{I} @tab The type shall be @code{INTEGER}. 11952@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 11953@end multitable 11954 11955@item @emph{Return value}: 11956The return value is of type @code{INTEGER} and of the same kind as 11957@var{I}. 11958 11959@item @emph{See also}: 11960@ref{SHIFTL}, @ref{SHIFTR} 11961@end table 11962 11963 11964 11965@node SHIFTL 11966@section @code{SHIFTL} --- Left shift 11967@fnindex SHIFTL 11968@cindex bits, shift left 11969@cindex shift, left 11970 11971@table @asis 11972@item @emph{Description}: 11973@code{SHIFTL} returns a value corresponding to @var{I} with all of the 11974bits shifted left by @var{SHIFT} places. If the absolute value of 11975@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 11976Bits shifted out from the left end are lost, and bits shifted in from 11977the right end are set to 0. 11978 11979@item @emph{Standard}: 11980Fortran 2008 and later 11981 11982@item @emph{Class}: 11983Elemental function 11984 11985@item @emph{Syntax}: 11986@code{RESULT = SHIFTL(I, SHIFT)} 11987 11988@item @emph{Arguments}: 11989@multitable @columnfractions .15 .70 11990@item @var{I} @tab The type shall be @code{INTEGER}. 11991@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 11992@end multitable 11993 11994@item @emph{Return value}: 11995The return value is of type @code{INTEGER} and of the same kind as 11996@var{I}. 11997 11998@item @emph{See also}: 11999@ref{SHIFTA}, @ref{SHIFTR} 12000@end table 12001 12002 12003 12004@node SHIFTR 12005@section @code{SHIFTR} --- Right shift 12006@fnindex SHIFTR 12007@cindex bits, shift right 12008@cindex shift, right 12009 12010@table @asis 12011@item @emph{Description}: 12012@code{SHIFTR} returns a value corresponding to @var{I} with all of the 12013bits shifted right by @var{SHIFT} places. If the absolute value of 12014@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 12015Bits shifted out from the right end are lost, and bits shifted in from 12016the left end are set to 0. 12017 12018@item @emph{Standard}: 12019Fortran 2008 and later 12020 12021@item @emph{Class}: 12022Elemental function 12023 12024@item @emph{Syntax}: 12025@code{RESULT = SHIFTR(I, SHIFT)} 12026 12027@item @emph{Arguments}: 12028@multitable @columnfractions .15 .70 12029@item @var{I} @tab The type shall be @code{INTEGER}. 12030@item @var{SHIFT} @tab The type shall be @code{INTEGER}. 12031@end multitable 12032 12033@item @emph{Return value}: 12034The return value is of type @code{INTEGER} and of the same kind as 12035@var{I}. 12036 12037@item @emph{See also}: 12038@ref{SHIFTA}, @ref{SHIFTL} 12039@end table 12040 12041 12042 12043@node SIGN 12044@section @code{SIGN} --- Sign copying function 12045@fnindex SIGN 12046@fnindex ISIGN 12047@fnindex DSIGN 12048@cindex sign copying 12049 12050@table @asis 12051@item @emph{Description}: 12052@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}. 12053 12054@item @emph{Standard}: 12055Fortran 77 and later 12056 12057@item @emph{Class}: 12058Elemental function 12059 12060@item @emph{Syntax}: 12061@code{RESULT = SIGN(A, B)} 12062 12063@item @emph{Arguments}: 12064@multitable @columnfractions .15 .70 12065@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL} 12066@item @var{B} @tab Shall be of the same type and kind as @var{A} 12067@end multitable 12068 12069@item @emph{Return value}: 12070The kind of the return value is that of @var{A} and @var{B}. 12071If @math{B\ge 0} then the result is @code{ABS(A)}, else 12072it is @code{-ABS(A)}. 12073 12074@item @emph{Example}: 12075@smallexample 12076program test_sign 12077 print *, sign(-12,1) 12078 print *, sign(-12,0) 12079 print *, sign(-12,-1) 12080 12081 print *, sign(-12.,1.) 12082 print *, sign(-12.,0.) 12083 print *, sign(-12.,-1.) 12084end program test_sign 12085@end smallexample 12086 12087@item @emph{Specific names}: 12088@multitable @columnfractions .20 .20 .20 .25 12089@item Name @tab Arguments @tab Return type @tab Standard 12090@item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu 12091@item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu 12092@item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu 12093@end multitable 12094@end table 12095 12096 12097 12098@node SIGNAL 12099@section @code{SIGNAL} --- Signal handling subroutine (or function) 12100@fnindex SIGNAL 12101@cindex system, signal handling 12102 12103@table @asis 12104@item @emph{Description}: 12105@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine 12106@var{HANDLER} to be executed with a single integer argument when signal 12107@var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to 12108turn off handling of signal @var{NUMBER} or revert to its default 12109action. See @code{signal(2)}. 12110 12111If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument 12112is supplied, it is set to the value returned by @code{signal(2)}. 12113 12114@item @emph{Standard}: 12115GNU extension 12116 12117@item @emph{Class}: 12118Subroutine, function 12119 12120@item @emph{Syntax}: 12121@multitable @columnfractions .80 12122@item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])} 12123@item @code{STATUS = SIGNAL(NUMBER, HANDLER)} 12124@end multitable 12125 12126@item @emph{Arguments}: 12127@multitable @columnfractions .15 .70 12128@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)} 12129@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or 12130@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. 12131@code{INTEGER}. It is @code{INTENT(IN)}. 12132@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar 12133integer. It has @code{INTENT(OUT)}. 12134@end multitable 12135@c TODO: What should the interface of the handler be? Does it take arguments? 12136 12137@item @emph{Return value}: 12138The @code{SIGNAL} function returns the value returned by @code{signal(2)}. 12139 12140@item @emph{Example}: 12141@smallexample 12142program test_signal 12143 intrinsic signal 12144 external handler_print 12145 12146 call signal (12, handler_print) 12147 call signal (10, 1) 12148 12149 call sleep (30) 12150end program test_signal 12151@end smallexample 12152@end table 12153 12154 12155 12156@node SIN 12157@section @code{SIN} --- Sine function 12158@fnindex SIN 12159@fnindex DSIN 12160@fnindex CSIN 12161@fnindex ZSIN 12162@fnindex CDSIN 12163@cindex trigonometric function, sine 12164@cindex sine 12165 12166@table @asis 12167@item @emph{Description}: 12168@code{SIN(X)} computes the sine of @var{X}. 12169 12170@item @emph{Standard}: 12171Fortran 77 and later 12172 12173@item @emph{Class}: 12174Elemental function 12175 12176@item @emph{Syntax}: 12177@code{RESULT = SIN(X)} 12178 12179@item @emph{Arguments}: 12180@multitable @columnfractions .15 .70 12181@item @var{X} @tab The type shall be @code{REAL} or 12182@code{COMPLEX}. 12183@end multitable 12184 12185@item @emph{Return value}: 12186The return value has same type and kind as @var{X}. 12187 12188@item @emph{Example}: 12189@smallexample 12190program test_sin 12191 real :: x = 0.0 12192 x = sin(x) 12193end program test_sin 12194@end smallexample 12195 12196@item @emph{Specific names}: 12197@multitable @columnfractions .20 .20 .20 .25 12198@item Name @tab Argument @tab Return type @tab Standard 12199@item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu 12200@item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu 12201@item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu 12202@item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 12203@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu 12204@end multitable 12205 12206@item @emph{See also}: 12207@ref{ASIN} 12208@end table 12209 12210 12211 12212@node SINH 12213@section @code{SINH} --- Hyperbolic sine function 12214@fnindex SINH 12215@fnindex DSINH 12216@cindex hyperbolic sine 12217@cindex hyperbolic function, sine 12218@cindex sine, hyperbolic 12219 12220@table @asis 12221@item @emph{Description}: 12222@code{SINH(X)} computes the hyperbolic sine of @var{X}. 12223 12224@item @emph{Standard}: 12225Fortran 95 and later, for a complex argument Fortran 2008 or later 12226 12227@item @emph{Class}: 12228Elemental function 12229 12230@item @emph{Syntax}: 12231@code{RESULT = SINH(X)} 12232 12233@item @emph{Arguments}: 12234@multitable @columnfractions .15 .70 12235@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 12236@end multitable 12237 12238@item @emph{Return value}: 12239The return value has same type and kind as @var{X}. 12240 12241@item @emph{Example}: 12242@smallexample 12243program test_sinh 12244 real(8) :: x = - 1.0_8 12245 x = sinh(x) 12246end program test_sinh 12247@end smallexample 12248 12249@item @emph{Specific names}: 12250@multitable @columnfractions .20 .20 .20 .25 12251@item Name @tab Argument @tab Return type @tab Standard 12252@item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 12253@item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 12254@end multitable 12255 12256@item @emph{See also}: 12257@ref{ASINH} 12258@end table 12259 12260 12261 12262@node SIZE 12263@section @code{SIZE} --- Determine the size of an array 12264@fnindex SIZE 12265@cindex array, size 12266@cindex array, number of elements 12267@cindex array, count elements 12268 12269@table @asis 12270@item @emph{Description}: 12271Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}, 12272or the total number of elements in @var{ARRAY} if @var{DIM} is absent. 12273 12274@item @emph{Standard}: 12275Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 12276 12277@item @emph{Class}: 12278Inquiry function 12279 12280@item @emph{Syntax}: 12281@code{RESULT = SIZE(ARRAY[, DIM [, KIND]])} 12282 12283@item @emph{Arguments}: 12284@multitable @columnfractions .15 .70 12285@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is 12286a pointer it must be associated and allocatable arrays must be allocated. 12287@item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} 12288and its value shall be in the range from 1 to n, where n equals the rank 12289of @var{ARRAY}. 12290@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 12291expression indicating the kind parameter of the result. 12292@end multitable 12293 12294@item @emph{Return value}: 12295The return value is of type @code{INTEGER} and of kind @var{KIND}. If 12296@var{KIND} is absent, the return value is of default integer kind. 12297 12298@item @emph{Example}: 12299@smallexample 12300PROGRAM test_size 12301 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 12302END PROGRAM 12303@end smallexample 12304 12305@item @emph{See also}: 12306@ref{SHAPE}, @ref{RESHAPE} 12307@end table 12308 12309 12310@node SIZEOF 12311@section @code{SIZEOF} --- Size in bytes of an expression 12312@fnindex SIZEOF 12313@cindex expression size 12314@cindex size of an expression 12315 12316@table @asis 12317@item @emph{Description}: 12318@code{SIZEOF(X)} calculates the number of bytes of storage the 12319expression @code{X} occupies. 12320 12321@item @emph{Standard}: 12322GNU extension 12323 12324@item @emph{Class}: 12325Inquiry function 12326 12327@item @emph{Syntax}: 12328@code{N = SIZEOF(X)} 12329 12330@item @emph{Arguments}: 12331@multitable @columnfractions .15 .70 12332@item @var{X} @tab The argument shall be of any type, rank or shape. 12333@end multitable 12334 12335@item @emph{Return value}: 12336The return value is of type integer and of the system-dependent kind 12337@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the 12338number of bytes occupied by the argument. If the argument has the 12339@code{POINTER} attribute, the number of bytes of the storage area pointed 12340to is returned. If the argument is of a derived type with @code{POINTER} 12341or @code{ALLOCATABLE} components, the return value does not account for 12342the sizes of the data pointed to by these components. If the argument is 12343polymorphic, the size according to the dynamic type is returned. The argument 12344may not be a procedure or procedure pointer. Note that the code assumes for 12345arrays that those are contiguous; for contiguous arrays, it returns the 12346storage or an array element multiplied by the size of the array. 12347 12348@item @emph{Example}: 12349@smallexample 12350 integer :: i 12351 real :: r, s(5) 12352 print *, (sizeof(s)/sizeof(r) == 5) 12353 end 12354@end smallexample 12355The example will print @code{.TRUE.} unless you are using a platform 12356where default @code{REAL} variables are unusually padded. 12357 12358@item @emph{See also}: 12359@ref{C_SIZEOF}, @ref{STORAGE_SIZE} 12360@end table 12361 12362 12363@node SLEEP 12364@section @code{SLEEP} --- Sleep for the specified number of seconds 12365@fnindex SLEEP 12366@cindex delayed execution 12367 12368@table @asis 12369@item @emph{Description}: 12370Calling this subroutine causes the process to pause for @var{SECONDS} seconds. 12371 12372@item @emph{Standard}: 12373GNU extension 12374 12375@item @emph{Class}: 12376Subroutine 12377 12378@item @emph{Syntax}: 12379@code{CALL SLEEP(SECONDS)} 12380 12381@item @emph{Arguments}: 12382@multitable @columnfractions .15 .70 12383@item @var{SECONDS} @tab The type shall be of default @code{INTEGER}. 12384@end multitable 12385 12386@item @emph{Example}: 12387@smallexample 12388program test_sleep 12389 call sleep(5) 12390end 12391@end smallexample 12392@end table 12393 12394 12395 12396@node SPACING 12397@section @code{SPACING} --- Smallest distance between two numbers of a given type 12398@fnindex SPACING 12399@cindex real number, relative spacing 12400@cindex floating point, relative spacing 12401 12402@table @asis 12403@item @emph{Description}: 12404Determines the distance between the argument @var{X} and the nearest 12405adjacent number of the same type. 12406 12407@item @emph{Standard}: 12408Fortran 95 and later 12409 12410@item @emph{Class}: 12411Elemental function 12412 12413@item @emph{Syntax}: 12414@code{RESULT = SPACING(X)} 12415 12416@item @emph{Arguments}: 12417@multitable @columnfractions .15 .70 12418@item @var{X} @tab Shall be of type @code{REAL}. 12419@end multitable 12420 12421@item @emph{Return value}: 12422The result is of the same type as the input argument @var{X}. 12423 12424@item @emph{Example}: 12425@smallexample 12426PROGRAM test_spacing 12427 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37) 12428 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200) 12429 12430 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686 12431 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686 12432END PROGRAM 12433@end smallexample 12434 12435@item @emph{See also}: 12436@ref{RRSPACING} 12437@end table 12438 12439 12440 12441@node SPREAD 12442@section @code{SPREAD} --- Add a dimension to an array 12443@fnindex SPREAD 12444@cindex array, increase dimension 12445@cindex array, duplicate elements 12446@cindex array, duplicate dimensions 12447 12448@table @asis 12449@item @emph{Description}: 12450Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified 12451dimension @var{DIM}. 12452 12453@item @emph{Standard}: 12454Fortran 95 and later 12455 12456@item @emph{Class}: 12457Transformational function 12458 12459@item @emph{Syntax}: 12460@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)} 12461 12462@item @emph{Arguments}: 12463@multitable @columnfractions .15 .70 12464@item @var{SOURCE} @tab Shall be a scalar or an array of any type and 12465a rank less than seven. 12466@item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a 12467value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}. 12468@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}. 12469@end multitable 12470 12471@item @emph{Return value}: 12472The result is an array of the same type as @var{SOURCE} and has rank n+1 12473where n equals the rank of @var{SOURCE}. 12474 12475@item @emph{Example}: 12476@smallexample 12477PROGRAM test_spread 12478 INTEGER :: a = 1, b(2) = (/ 1, 2 /) 12479 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1" 12480 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2" 12481END PROGRAM 12482@end smallexample 12483 12484@item @emph{See also}: 12485@ref{UNPACK} 12486@end table 12487 12488 12489 12490@node SQRT 12491@section @code{SQRT} --- Square-root function 12492@fnindex SQRT 12493@fnindex DSQRT 12494@fnindex CSQRT 12495@fnindex ZSQRT 12496@fnindex CDSQRT 12497@cindex root 12498@cindex square-root 12499 12500@table @asis 12501@item @emph{Description}: 12502@code{SQRT(X)} computes the square root of @var{X}. 12503 12504@item @emph{Standard}: 12505Fortran 77 and later 12506 12507@item @emph{Class}: 12508Elemental function 12509 12510@item @emph{Syntax}: 12511@code{RESULT = SQRT(X)} 12512 12513@item @emph{Arguments}: 12514@multitable @columnfractions .15 .70 12515@item @var{X} @tab The type shall be @code{REAL} or 12516@code{COMPLEX}. 12517@end multitable 12518 12519@item @emph{Return value}: 12520The return value is of type @code{REAL} or @code{COMPLEX}. 12521The kind type parameter is the same as @var{X}. 12522 12523@item @emph{Example}: 12524@smallexample 12525program test_sqrt 12526 real(8) :: x = 2.0_8 12527 complex :: z = (1.0, 2.0) 12528 x = sqrt(x) 12529 z = sqrt(z) 12530end program test_sqrt 12531@end smallexample 12532 12533@item @emph{Specific names}: 12534@multitable @columnfractions .20 .20 .20 .25 12535@item Name @tab Argument @tab Return type @tab Standard 12536@item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 12537@item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 12538@item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later 12539@item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 12540@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension 12541@end multitable 12542@end table 12543 12544 12545 12546@node SRAND 12547@section @code{SRAND} --- Reinitialize the random number generator 12548@fnindex SRAND 12549@cindex random number generation, seeding 12550@cindex seeding a random number generator 12551 12552@table @asis 12553@item @emph{Description}: 12554@code{SRAND} reinitializes the pseudo-random number generator 12555called by @code{RAND} and @code{IRAND}. The new seed used by the 12556generator is specified by the required argument @var{SEED}. 12557 12558@item @emph{Standard}: 12559GNU extension 12560 12561@item @emph{Class}: 12562Subroutine 12563 12564@item @emph{Syntax}: 12565@code{CALL SRAND(SEED)} 12566 12567@item @emph{Arguments}: 12568@multitable @columnfractions .15 .70 12569@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}. 12570@end multitable 12571 12572@item @emph{Return value}: 12573Does not return anything. 12574 12575@item @emph{Example}: 12576See @code{RAND} and @code{IRAND} for examples. 12577 12578@item @emph{Notes}: 12579The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to 12580initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER} 12581to generate pseudo-random numbers. Please note that in 12582GNU Fortran, these two sets of intrinsics (@code{RAND}, 12583@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and 12584@code{RANDOM_SEED} on the other hand) access two independent 12585pseudo-random number generators. 12586 12587@item @emph{See also}: 12588@ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER} 12589 12590@end table 12591 12592 12593 12594@node STAT 12595@section @code{STAT} --- Get file status 12596@fnindex STAT 12597@cindex file system, file status 12598 12599@table @asis 12600@item @emph{Description}: 12601This function returns information about a file. No permissions are required on 12602the file itself, but execute (search) permission is required on all of the 12603directories in path that lead to the file. 12604 12605The elements that are obtained and stored in the array @code{VALUES}: 12606@multitable @columnfractions .15 .70 12607@item @code{VALUES(1)} @tab Device ID 12608@item @code{VALUES(2)} @tab Inode number 12609@item @code{VALUES(3)} @tab File mode 12610@item @code{VALUES(4)} @tab Number of links 12611@item @code{VALUES(5)} @tab Owner's uid 12612@item @code{VALUES(6)} @tab Owner's gid 12613@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available) 12614@item @code{VALUES(8)} @tab File size (bytes) 12615@item @code{VALUES(9)} @tab Last access time 12616@item @code{VALUES(10)} @tab Last modification time 12617@item @code{VALUES(11)} @tab Last file status change time 12618@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available) 12619@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available) 12620@end multitable 12621 12622Not all these elements are relevant on all systems. 12623If an element is not relevant, it is returned as 0. 12624 12625This intrinsic is provided in both subroutine and function forms; however, 12626only one form can be used in any given program unit. 12627 12628@item @emph{Standard}: 12629GNU extension 12630 12631@item @emph{Class}: 12632Subroutine, function 12633 12634@item @emph{Syntax}: 12635@multitable @columnfractions .80 12636@item @code{CALL STAT(NAME, VALUES [, STATUS])} 12637@item @code{STATUS = STAT(NAME, VALUES)} 12638@end multitable 12639 12640@item @emph{Arguments}: 12641@multitable @columnfractions .15 .70 12642@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the 12643default kind and a valid path within the file system. 12644@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. 12645@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 12646on success and a system specific error code otherwise. 12647@end multitable 12648 12649@item @emph{Example}: 12650@smallexample 12651PROGRAM test_stat 12652 INTEGER, DIMENSION(13) :: buff 12653 INTEGER :: status 12654 12655 CALL STAT("/etc/passwd", buff, status) 12656 12657 IF (status == 0) THEN 12658 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1) 12659 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2) 12660 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3) 12661 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4) 12662 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5) 12663 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6) 12664 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7) 12665 WRITE (*, FMT="('File size:', T30, I19)") buff(8) 12666 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9)) 12667 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10)) 12668 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11)) 12669 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12) 12670 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13) 12671 END IF 12672END PROGRAM 12673@end smallexample 12674 12675@item @emph{See also}: 12676To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT} 12677@end table 12678 12679 12680 12681@node STORAGE_SIZE 12682@section @code{STORAGE_SIZE} --- Storage size in bits 12683@fnindex STORAGE_SIZE 12684@cindex storage size 12685 12686@table @asis 12687@item @emph{Description}: 12688Returns the storage size of argument @var{A} in bits. 12689@item @emph{Standard}: 12690Fortran 2008 and later 12691@item @emph{Class}: 12692Inquiry function 12693@item @emph{Syntax}: 12694@code{RESULT = STORAGE_SIZE(A [, KIND])} 12695 12696@item @emph{Arguments}: 12697@multitable @columnfractions .15 .70 12698@item @var{A} @tab Shall be a scalar or array of any type. 12699@item @var{KIND} @tab (Optional) shall be a scalar integer constant expression. 12700@end multitable 12701 12702@item @emph{Return Value}: 12703The result is a scalar integer with the kind type parameter specified by KIND 12704(or default integer type if KIND is missing). The result value is the size 12705expressed in bits for an element of an array that has the dynamic type and type 12706parameters of A. 12707 12708@item @emph{See also}: 12709@ref{C_SIZEOF}, @ref{SIZEOF} 12710@end table 12711 12712 12713 12714@node SUM 12715@section @code{SUM} --- Sum of array elements 12716@fnindex SUM 12717@cindex array, sum 12718@cindex array, add elements 12719@cindex array, conditionally add elements 12720@cindex sum array elements 12721 12722@table @asis 12723@item @emph{Description}: 12724Adds the elements of @var{ARRAY} along dimension @var{DIM} if 12725the corresponding element in @var{MASK} is @code{TRUE}. 12726 12727@item @emph{Standard}: 12728Fortran 95 and later 12729 12730@item @emph{Class}: 12731Transformational function 12732 12733@item @emph{Syntax}: 12734@multitable @columnfractions .80 12735@item @code{RESULT = SUM(ARRAY[, MASK])} 12736@item @code{RESULT = SUM(ARRAY, DIM[, MASK])} 12737@end multitable 12738 12739@item @emph{Arguments}: 12740@multitable @columnfractions .15 .70 12741@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, 12742@code{REAL} or @code{COMPLEX}. 12743@item @var{DIM} @tab (Optional) shall be a scalar of type 12744@code{INTEGER} with a value in the range from 1 to n, where n 12745equals the rank of @var{ARRAY}. 12746@item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} 12747and either be a scalar or an array of the same shape as @var{ARRAY}. 12748@end multitable 12749 12750@item @emph{Return value}: 12751The result is of the same type as @var{ARRAY}. 12752 12753If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY} 12754is returned. Otherwise, an array of rank n-1, where n equals the rank of 12755@var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} 12756dropped is returned. 12757 12758@item @emph{Example}: 12759@smallexample 12760PROGRAM test_sum 12761 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) 12762 print *, SUM(x) ! all elements, sum = 15 12763 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9 12764END PROGRAM 12765@end smallexample 12766 12767@item @emph{See also}: 12768@ref{PRODUCT} 12769@end table 12770 12771 12772 12773@node SYMLNK 12774@section @code{SYMLNK} --- Create a symbolic link 12775@fnindex SYMLNK 12776@cindex file system, create link 12777@cindex file system, soft link 12778 12779@table @asis 12780@item @emph{Description}: 12781Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null 12782character (@code{CHAR(0)}) can be used to mark the end of the names in 12783@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file 12784names are ignored. If the @var{STATUS} argument is supplied, it 12785contains 0 on success or a nonzero error code upon return; see 12786@code{symlink(2)}. If the system does not supply @code{symlink(2)}, 12787@code{ENOSYS} is returned. 12788 12789This intrinsic is provided in both subroutine and function forms; 12790however, only one form can be used in any given program unit. 12791 12792@item @emph{Standard}: 12793GNU extension 12794 12795@item @emph{Class}: 12796Subroutine, function 12797 12798@item @emph{Syntax}: 12799@multitable @columnfractions .80 12800@item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])} 12801@item @code{STATUS = SYMLNK(PATH1, PATH2)} 12802@end multitable 12803 12804@item @emph{Arguments}: 12805@multitable @columnfractions .15 .70 12806@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. 12807@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. 12808@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 12809@end multitable 12810 12811@item @emph{See also}: 12812@ref{LINK}, @ref{UNLINK} 12813 12814@end table 12815 12816 12817 12818@node SYSTEM 12819@section @code{SYSTEM} --- Execute a shell command 12820@fnindex SYSTEM 12821@cindex system, system call 12822 12823@table @asis 12824@item @emph{Description}: 12825Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If 12826argument @var{STATUS} is present, it contains the value returned by 12827@code{system(3)}, which is presumably 0 if the shell command succeeded. 12828Note that which shell is used to invoke the command is system-dependent 12829and environment-dependent. 12830 12831This intrinsic is provided in both subroutine and function forms; 12832however, only one form can be used in any given program unit. 12833 12834Note that the @code{system} function need not be thread-safe. It is 12835the responsibility of the user to ensure that @code{system} is not 12836called concurrently. 12837 12838@item @emph{Standard}: 12839GNU extension 12840 12841@item @emph{Class}: 12842Subroutine, function 12843 12844@item @emph{Syntax}: 12845@multitable @columnfractions .80 12846@item @code{CALL SYSTEM(COMMAND [, STATUS])} 12847@item @code{STATUS = SYSTEM(COMMAND)} 12848@end multitable 12849 12850@item @emph{Arguments}: 12851@multitable @columnfractions .15 .70 12852@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type. 12853@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 12854@end multitable 12855 12856@item @emph{See also}: 12857@ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard 12858and should considered in new code for future portability. 12859@end table 12860 12861 12862 12863@node SYSTEM_CLOCK 12864@section @code{SYSTEM_CLOCK} --- Time function 12865@fnindex SYSTEM_CLOCK 12866@cindex time, clock ticks 12867@cindex clock ticks 12868 12869@table @asis 12870@item @emph{Description}: 12871Determines the @var{COUNT} of a processor clock since an unspecified 12872time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines 12873the number of clock ticks per second. If the platform supports a 12874monotonic clock, that clock is used and can, depending on the platform 12875clock implementation, provide up to nanosecond resolution. If a 12876monotonic clock is not available, the implementation falls back to a 12877realtime clock. 12878 12879@var{COUNT_RATE} is system dependent and can vary depending on the kind of 12880the arguments. For @var{kind=4} arguments (and smaller integer kinds), 12881@var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and 12882larger integer kinds), @var{COUNT} typically represents micro- or 12883nanoseconds depending on resolution of the underlying platform clock. 12884@var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the 12885millisecond resolution of the @var{kind=4} version implies that the 12886@var{COUNT} will wrap around in roughly 25 days. In order to avoid issues 12887with the wrap around and for more precise timing, please use the 12888@var{kind=8} version. 12889 12890If there is no clock, or querying the clock fails, @var{COUNT} is set 12891to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are 12892set to zero. 12893 12894When running on a platform using the GNU C library (glibc) version 128952.16 or older, or a derivative thereof, the high resolution monotonic 12896clock is available only when linking with the @var{rt} library. This 12897can be done explicitly by adding the @code{-lrt} flag when linking the 12898application, but is also done implicitly when using OpenMP. 12899 12900On the Windows platform, the version with @var{kind=4} arguments uses 12901the @code{GetTickCount} function, whereas the @var{kind=8} version 12902uses @code{QueryPerformanceCounter} and 12903@code{QueryPerformanceCounterFrequency}. For more information, and 12904potential caveats, please see the platform documentation. 12905 12906@item @emph{Standard}: 12907Fortran 95 and later 12908 12909@item @emph{Class}: 12910Subroutine 12911 12912@item @emph{Syntax}: 12913@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} 12914 12915@item @emph{Arguments}: 12916@multitable @columnfractions .15 .70 12917@item @var{COUNT} @tab (Optional) shall be a scalar of type 12918@code{INTEGER} with @code{INTENT(OUT)}. 12919@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type 12920@code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}. 12921@item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type 12922@code{INTEGER} with @code{INTENT(OUT)}. 12923@end multitable 12924 12925@item @emph{Example}: 12926@smallexample 12927PROGRAM test_system_clock 12928 INTEGER :: count, count_rate, count_max 12929 CALL SYSTEM_CLOCK(count, count_rate, count_max) 12930 WRITE(*,*) count, count_rate, count_max 12931END PROGRAM 12932@end smallexample 12933 12934@item @emph{See also}: 12935@ref{DATE_AND_TIME}, @ref{CPU_TIME} 12936@end table 12937 12938 12939 12940@node TAN 12941@section @code{TAN} --- Tangent function 12942@fnindex TAN 12943@fnindex DTAN 12944@cindex trigonometric function, tangent 12945@cindex tangent 12946 12947@table @asis 12948@item @emph{Description}: 12949@code{TAN(X)} computes the tangent of @var{X}. 12950 12951@item @emph{Standard}: 12952Fortran 77 and later, for a complex argument Fortran 2008 or later 12953 12954@item @emph{Class}: 12955Elemental function 12956 12957@item @emph{Syntax}: 12958@code{RESULT = TAN(X)} 12959 12960@item @emph{Arguments}: 12961@multitable @columnfractions .15 .70 12962@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 12963@end multitable 12964 12965@item @emph{Return value}: 12966The return value has same type and kind as @var{X}. 12967 12968@item @emph{Example}: 12969@smallexample 12970program test_tan 12971 real(8) :: x = 0.165_8 12972 x = tan(x) 12973end program test_tan 12974@end smallexample 12975 12976@item @emph{Specific names}: 12977@multitable @columnfractions .20 .20 .20 .25 12978@item Name @tab Argument @tab Return type @tab Standard 12979@item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 12980@item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 12981@end multitable 12982 12983@item @emph{See also}: 12984@ref{ATAN} 12985@end table 12986 12987 12988 12989@node TANH 12990@section @code{TANH} --- Hyperbolic tangent function 12991@fnindex TANH 12992@fnindex DTANH 12993@cindex hyperbolic tangent 12994@cindex hyperbolic function, tangent 12995@cindex tangent, hyperbolic 12996 12997@table @asis 12998@item @emph{Description}: 12999@code{TANH(X)} computes the hyperbolic tangent of @var{X}. 13000 13001@item @emph{Standard}: 13002Fortran 77 and later, for a complex argument Fortran 2008 or later 13003 13004@item @emph{Class}: 13005Elemental function 13006 13007@item @emph{Syntax}: 13008@code{X = TANH(X)} 13009 13010@item @emph{Arguments}: 13011@multitable @columnfractions .15 .70 13012@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. 13013@end multitable 13014 13015@item @emph{Return value}: 13016The return value has same type and kind as @var{X}. If @var{X} is 13017complex, the imaginary part of the result is in radians. If @var{X} 13018is @code{REAL}, the return value lies in the range 13019@math{ - 1 \leq tanh(x) \leq 1 }. 13020 13021@item @emph{Example}: 13022@smallexample 13023program test_tanh 13024 real(8) :: x = 2.1_8 13025 x = tanh(x) 13026end program test_tanh 13027@end smallexample 13028 13029@item @emph{Specific names}: 13030@multitable @columnfractions .20 .20 .20 .25 13031@item Name @tab Argument @tab Return type @tab Standard 13032@item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later 13033@item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later 13034@end multitable 13035 13036@item @emph{See also}: 13037@ref{ATANH} 13038@end table 13039 13040 13041 13042@node THIS_IMAGE 13043@section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image 13044@fnindex THIS_IMAGE 13045@cindex coarray, @code{THIS_IMAGE} 13046@cindex images, index of this image 13047 13048@table @asis 13049@item @emph{Description}: 13050Returns the cosubscript for this image. 13051 13052@item @emph{Standard}: 13053Fortran 2008 and later. With @var{DISTANCE} argument, 13054Technical Specification (TS) 18508 or later 13055 13056@item @emph{Class}: 13057Transformational function 13058 13059@item @emph{Syntax}: 13060@multitable @columnfractions .80 13061@item @code{RESULT = THIS_IMAGE()} 13062@item @code{RESULT = THIS_IMAGE(DISTANCE)} 13063@item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} 13064@end multitable 13065 13066@item @emph{Arguments}: 13067@multitable @columnfractions .15 .70 13068@item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer 13069(not permitted together with @var{COARRAY}). 13070@item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} 13071present, required). 13072@item @var{DIM} @tab default integer scalar (optional). If present, 13073@var{DIM} shall be between one and the corank of @var{COARRAY}. 13074@end multitable 13075 13076 13077@item @emph{Return value}: 13078Default integer. If @var{COARRAY} is not present, it is scalar; if 13079@var{DISTANCE} is not present or has value 0, its value is the image index on 13080the invoking image for the current team, for values smaller or equal 13081distance to the initial team, it returns the image index on the ancestor team 13082which has a distance of @var{DISTANCE} from the invoking team. If 13083@var{DISTANCE} is larger than the distance to the initial team, the image 13084index of the initial team is returned. Otherwise when the @var{COARRAY} is 13085present, if @var{DIM} is not present, a rank-1 array with corank elements is 13086returned, containing the cosubscripts for @var{COARRAY} specifying the invoking 13087image. If @var{DIM} is present, a scalar is returned, with the value of 13088the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}. 13089 13090@item @emph{Example}: 13091@smallexample 13092INTEGER :: value[*] 13093INTEGER :: i 13094value = THIS_IMAGE() 13095SYNC ALL 13096IF (THIS_IMAGE() == 1) THEN 13097 DO i = 1, NUM_IMAGES() 13098 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] 13099 END DO 13100END IF 13101 13102! Check whether the current image is the initial image 13103IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) 13104 error stop "something is rotten here" 13105@end smallexample 13106 13107@item @emph{See also}: 13108@ref{NUM_IMAGES}, @ref{IMAGE_INDEX} 13109@end table 13110 13111 13112 13113@node TIME 13114@section @code{TIME} --- Time function 13115@fnindex TIME 13116@cindex time, current 13117@cindex current time 13118 13119@table @asis 13120@item @emph{Description}: 13121Returns the current time encoded as an integer (in the manner of the 13122function @code{time(3)} in the C standard library). This value is 13123suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}. 13124 13125This intrinsic is not fully portable, such as to systems with 32-bit 13126@code{INTEGER} types but supporting times wider than 32 bits. Therefore, 13127the values returned by this intrinsic might be, or become, negative, or 13128numerically less than previous values, during a single run of the 13129compiled program. 13130 13131See @ref{TIME8}, for information on a similar intrinsic that might be 13132portable to more GNU Fortran implementations, though to fewer Fortran 13133compilers. 13134 13135@item @emph{Standard}: 13136GNU extension 13137 13138@item @emph{Class}: 13139Function 13140 13141@item @emph{Syntax}: 13142@code{RESULT = TIME()} 13143 13144@item @emph{Return value}: 13145The return value is a scalar of type @code{INTEGER(4)}. 13146 13147@item @emph{See also}: 13148@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} 13149 13150@end table 13151 13152 13153 13154@node TIME8 13155@section @code{TIME8} --- Time function (64-bit) 13156@fnindex TIME8 13157@cindex time, current 13158@cindex current time 13159 13160@table @asis 13161@item @emph{Description}: 13162Returns the current time encoded as an integer (in the manner of the 13163function @code{time(3)} in the C standard library). This value is 13164suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}. 13165 13166@emph{Warning:} this intrinsic does not increase the range of the timing 13167values over that returned by @code{time(3)}. On a system with a 32-bit 13168@code{time(3)}, @code{TIME8} will return a 32-bit value, even though 13169it is converted to a 64-bit @code{INTEGER(8)} value. That means 13170overflows of the 32-bit value can still occur. Therefore, the values 13171returned by this intrinsic might be or become negative or numerically 13172less than previous values during a single run of the compiled program. 13173 13174@item @emph{Standard}: 13175GNU extension 13176 13177@item @emph{Class}: 13178Function 13179 13180@item @emph{Syntax}: 13181@code{RESULT = TIME8()} 13182 13183@item @emph{Return value}: 13184The return value is a scalar of type @code{INTEGER(8)}. 13185 13186@item @emph{See also}: 13187@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME} 13188 13189@end table 13190 13191 13192 13193@node TINY 13194@section @code{TINY} --- Smallest positive number of a real kind 13195@fnindex TINY 13196@cindex limits, smallest number 13197@cindex model representation, smallest number 13198 13199@table @asis 13200@item @emph{Description}: 13201@code{TINY(X)} returns the smallest positive (non zero) number 13202in the model of the type of @code{X}. 13203 13204@item @emph{Standard}: 13205Fortran 95 and later 13206 13207@item @emph{Class}: 13208Inquiry function 13209 13210@item @emph{Syntax}: 13211@code{RESULT = TINY(X)} 13212 13213@item @emph{Arguments}: 13214@multitable @columnfractions .15 .70 13215@item @var{X} @tab Shall be of type @code{REAL}. 13216@end multitable 13217 13218@item @emph{Return value}: 13219The return value is of the same type and kind as @var{X} 13220 13221@item @emph{Example}: 13222See @code{HUGE} for an example. 13223@end table 13224 13225 13226 13227@node TRAILZ 13228@section @code{TRAILZ} --- Number of trailing zero bits of an integer 13229@fnindex TRAILZ 13230@cindex zero bits 13231 13232@table @asis 13233@item @emph{Description}: 13234@code{TRAILZ} returns the number of trailing zero bits of an integer. 13235 13236@item @emph{Standard}: 13237Fortran 2008 and later 13238 13239@item @emph{Class}: 13240Elemental function 13241 13242@item @emph{Syntax}: 13243@code{RESULT = TRAILZ(I)} 13244 13245@item @emph{Arguments}: 13246@multitable @columnfractions .15 .70 13247@item @var{I} @tab Shall be of type @code{INTEGER}. 13248@end multitable 13249 13250@item @emph{Return value}: 13251The type of the return value is the default @code{INTEGER}. 13252If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. 13253 13254@item @emph{Example}: 13255@smallexample 13256PROGRAM test_trailz 13257 WRITE (*,*) TRAILZ(8) ! prints 3 13258END PROGRAM 13259@end smallexample 13260 13261@item @emph{See also}: 13262@ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT} 13263@end table 13264 13265 13266 13267@node TRANSFER 13268@section @code{TRANSFER} --- Transfer bit patterns 13269@fnindex TRANSFER 13270@cindex bits, move 13271@cindex type cast 13272 13273@table @asis 13274@item @emph{Description}: 13275Interprets the bitwise representation of @var{SOURCE} in memory as if it 13276is the representation of a variable or array of the same type and type 13277parameters as @var{MOLD}. 13278 13279This is approximately equivalent to the C concept of @emph{casting} one 13280type to another. 13281 13282@item @emph{Standard}: 13283Fortran 95 and later 13284 13285@item @emph{Class}: 13286Transformational function 13287 13288@item @emph{Syntax}: 13289@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])} 13290 13291@item @emph{Arguments}: 13292@multitable @columnfractions .15 .70 13293@item @var{SOURCE} @tab Shall be a scalar or an array of any type. 13294@item @var{MOLD} @tab Shall be a scalar or an array of any type. 13295@item @var{SIZE} @tab (Optional) shall be a scalar of type 13296@code{INTEGER}. 13297@end multitable 13298 13299@item @emph{Return value}: 13300The result has the same type as @var{MOLD}, with the bit level 13301representation of @var{SOURCE}. If @var{SIZE} is present, the result is 13302a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent 13303but @var{MOLD} is an array (of any size or shape), the result is a one- 13304dimensional array of the minimum length needed to contain the entirety 13305of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent 13306and @var{MOLD} is a scalar, the result is a scalar. 13307 13308If the bitwise representation of the result is longer than that of 13309@var{SOURCE}, then the leading bits of the result correspond to those of 13310@var{SOURCE} and any trailing bits are filled arbitrarily. 13311 13312When the resulting bit representation does not correspond to a valid 13313representation of a variable of the same type as @var{MOLD}, the results 13314are undefined, and subsequent operations on the result cannot be 13315guaranteed to produce sensible behavior. For example, it is possible to 13316create @code{LOGICAL} variables for which @code{@var{VAR}} and 13317@code{.NOT.@var{VAR}} both appear to be true. 13318 13319@item @emph{Example}: 13320@smallexample 13321PROGRAM test_transfer 13322 integer :: x = 2143289344 13323 print *, transfer(x, 1.0) ! prints "NaN" on i686 13324END PROGRAM 13325@end smallexample 13326@end table 13327 13328 13329 13330@node TRANSPOSE 13331@section @code{TRANSPOSE} --- Transpose an array of rank two 13332@fnindex TRANSPOSE 13333@cindex array, transpose 13334@cindex matrix, transpose 13335@cindex transpose 13336 13337@table @asis 13338@item @emph{Description}: 13339Transpose an array of rank two. Element (i, j) of the result has the value 13340@code{MATRIX(j, i)}, for all i, j. 13341 13342@item @emph{Standard}: 13343Fortran 95 and later 13344 13345@item @emph{Class}: 13346Transformational function 13347 13348@item @emph{Syntax}: 13349@code{RESULT = TRANSPOSE(MATRIX)} 13350 13351@item @emph{Arguments}: 13352@multitable @columnfractions .15 .70 13353@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two. 13354@end multitable 13355 13356@item @emph{Return value}: 13357The result has the same type as @var{MATRIX}, and has shape 13358@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}. 13359@end table 13360 13361 13362 13363@node TRIM 13364@section @code{TRIM} --- Remove trailing blank characters of a string 13365@fnindex TRIM 13366@cindex string, remove trailing whitespace 13367 13368@table @asis 13369@item @emph{Description}: 13370Removes trailing blank characters of a string. 13371 13372@item @emph{Standard}: 13373Fortran 95 and later 13374 13375@item @emph{Class}: 13376Transformational function 13377 13378@item @emph{Syntax}: 13379@code{RESULT = TRIM(STRING)} 13380 13381@item @emph{Arguments}: 13382@multitable @columnfractions .15 .70 13383@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}. 13384@end multitable 13385 13386@item @emph{Return value}: 13387A scalar of type @code{CHARACTER} which length is that of @var{STRING} 13388less the number of trailing blanks. 13389 13390@item @emph{Example}: 13391@smallexample 13392PROGRAM test_trim 13393 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " 13394 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks 13395END PROGRAM 13396@end smallexample 13397 13398@item @emph{See also}: 13399@ref{ADJUSTL}, @ref{ADJUSTR} 13400@end table 13401 13402 13403 13404@node TTYNAM 13405@section @code{TTYNAM} --- Get the name of a terminal device. 13406@fnindex TTYNAM 13407@cindex system, terminal 13408 13409@table @asis 13410@item @emph{Description}: 13411Get the name of a terminal device. For more information, 13412see @code{ttyname(3)}. 13413 13414This intrinsic is provided in both subroutine and function forms; 13415however, only one form can be used in any given program unit. 13416 13417@item @emph{Standard}: 13418GNU extension 13419 13420@item @emph{Class}: 13421Subroutine, function 13422 13423@item @emph{Syntax}: 13424@multitable @columnfractions .80 13425@item @code{CALL TTYNAM(UNIT, NAME)} 13426@item @code{NAME = TTYNAM(UNIT)} 13427@end multitable 13428 13429@item @emph{Arguments}: 13430@multitable @columnfractions .15 .70 13431@item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. 13432@item @var{NAME} @tab Shall be of type @code{CHARACTER}. 13433@end multitable 13434 13435@item @emph{Example}: 13436@smallexample 13437PROGRAM test_ttynam 13438 INTEGER :: unit 13439 DO unit = 1, 10 13440 IF (isatty(unit=unit)) write(*,*) ttynam(unit) 13441 END DO 13442END PROGRAM 13443@end smallexample 13444 13445@item @emph{See also}: 13446@ref{ISATTY} 13447@end table 13448 13449 13450 13451@node UBOUND 13452@section @code{UBOUND} --- Upper dimension bounds of an array 13453@fnindex UBOUND 13454@cindex array, upper bound 13455 13456@table @asis 13457@item @emph{Description}: 13458Returns the upper bounds of an array, or a single upper bound 13459along the @var{DIM} dimension. 13460@item @emph{Standard}: 13461Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 13462 13463@item @emph{Class}: 13464Inquiry function 13465 13466@item @emph{Syntax}: 13467@code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])} 13468 13469@item @emph{Arguments}: 13470@multitable @columnfractions .15 .70 13471@item @var{ARRAY} @tab Shall be an array, of any type. 13472@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 13473@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization 13474expression indicating the kind parameter of the result. 13475@end multitable 13476 13477@item @emph{Return value}: 13478The return value is of type @code{INTEGER} and of kind @var{KIND}. If 13479@var{KIND} is absent, the return value is of default integer kind. 13480If @var{DIM} is absent, the result is an array of the upper bounds of 13481@var{ARRAY}. If @var{DIM} is present, the result is a scalar 13482corresponding to the upper bound of the array along that dimension. If 13483@var{ARRAY} is an expression rather than a whole array or array 13484structure component, or if it has a zero extent along the relevant 13485dimension, the upper bound is taken to be the number of elements along 13486the relevant dimension. 13487 13488@item @emph{See also}: 13489@ref{LBOUND}, @ref{LCOBOUND} 13490@end table 13491 13492 13493 13494@node UCOBOUND 13495@section @code{UCOBOUND} --- Upper codimension bounds of an array 13496@fnindex UCOBOUND 13497@cindex coarray, upper bound 13498 13499@table @asis 13500@item @emph{Description}: 13501Returns the upper cobounds of a coarray, or a single upper cobound 13502along the @var{DIM} codimension. 13503@item @emph{Standard}: 13504Fortran 2008 and later 13505 13506@item @emph{Class}: 13507Inquiry function 13508 13509@item @emph{Syntax}: 13510@code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])} 13511 13512@item @emph{Arguments}: 13513@multitable @columnfractions .15 .70 13514@item @var{ARRAY} @tab Shall be an coarray, of any type. 13515@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. 13516@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13517expression indicating the kind parameter of the result. 13518@end multitable 13519 13520@item @emph{Return value}: 13521The return value is of type @code{INTEGER} and of kind @var{KIND}. If 13522@var{KIND} is absent, the return value is of default integer kind. 13523If @var{DIM} is absent, the result is an array of the lower cobounds of 13524@var{COARRAY}. If @var{DIM} is present, the result is a scalar 13525corresponding to the lower cobound of the array along that codimension. 13526 13527@item @emph{See also}: 13528@ref{LCOBOUND}, @ref{LBOUND} 13529@end table 13530 13531 13532 13533@node UMASK 13534@section @code{UMASK} --- Set the file creation mask 13535@fnindex UMASK 13536@cindex file system, file creation mask 13537 13538@table @asis 13539@item @emph{Description}: 13540Sets the file creation mask to @var{MASK}. If called as a function, it 13541returns the old value. If called as a subroutine and argument @var{OLD} 13542if it is supplied, it is set to the old value. See @code{umask(2)}. 13543 13544@item @emph{Standard}: 13545GNU extension 13546 13547@item @emph{Class}: 13548Subroutine, function 13549 13550@item @emph{Syntax}: 13551@multitable @columnfractions .80 13552@item @code{CALL UMASK(MASK [, OLD])} 13553@item @code{OLD = UMASK(MASK)} 13554@end multitable 13555 13556@item @emph{Arguments}: 13557@multitable @columnfractions .15 .70 13558@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}. 13559@item @var{OLD} @tab (Optional) Shall be a scalar of type 13560@code{INTEGER}. 13561@end multitable 13562 13563@end table 13564 13565 13566 13567@node UNLINK 13568@section @code{UNLINK} --- Remove a file from the file system 13569@fnindex UNLINK 13570@cindex file system, remove file 13571 13572@table @asis 13573@item @emph{Description}: 13574Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be 13575used to mark the end of the name in @var{PATH}; otherwise, trailing 13576blanks in the file name are ignored. If the @var{STATUS} argument is 13577supplied, it contains 0 on success or a nonzero error code upon return; 13578see @code{unlink(2)}. 13579 13580This intrinsic is provided in both subroutine and function forms; 13581however, only one form can be used in any given program unit. 13582 13583@item @emph{Standard}: 13584GNU extension 13585 13586@item @emph{Class}: 13587Subroutine, function 13588 13589@item @emph{Syntax}: 13590@multitable @columnfractions .80 13591@item @code{CALL UNLINK(PATH [, STATUS])} 13592@item @code{STATUS = UNLINK(PATH)} 13593@end multitable 13594 13595@item @emph{Arguments}: 13596@multitable @columnfractions .15 .70 13597@item @var{PATH} @tab Shall be of default @code{CHARACTER} type. 13598@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. 13599@end multitable 13600 13601@item @emph{See also}: 13602@ref{LINK}, @ref{SYMLNK} 13603@end table 13604 13605 13606 13607@node UNPACK 13608@section @code{UNPACK} --- Unpack an array of rank one into an array 13609@fnindex UNPACK 13610@cindex array, unpacking 13611@cindex array, increase dimension 13612@cindex array, scatter elements 13613 13614@table @asis 13615@item @emph{Description}: 13616Store the elements of @var{VECTOR} in an array of higher rank. 13617 13618@item @emph{Standard}: 13619Fortran 95 and later 13620 13621@item @emph{Class}: 13622Transformational function 13623 13624@item @emph{Syntax}: 13625@code{RESULT = UNPACK(VECTOR, MASK, FIELD)} 13626 13627@item @emph{Arguments}: 13628@multitable @columnfractions .15 .70 13629@item @var{VECTOR} @tab Shall be an array of any type and rank one. It 13630shall have at least as many elements as @var{MASK} has @code{TRUE} values. 13631@item @var{MASK} @tab Shall be an array of type @code{LOGICAL}. 13632@item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have 13633the same shape as @var{MASK}. 13634@end multitable 13635 13636@item @emph{Return value}: 13637The resulting array corresponds to @var{FIELD} with @code{TRUE} elements 13638of @var{MASK} replaced by values from @var{VECTOR} in array element order. 13639 13640@item @emph{Example}: 13641@smallexample 13642PROGRAM test_unpack 13643 integer :: vector(2) = (/1,1/) 13644 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /) 13645 integer :: field(2,2) = 0, unity(2,2) 13646 13647 ! result: unity matrix 13648 unity = unpack(vector, reshape(mask, (/2,2/)), field) 13649END PROGRAM 13650@end smallexample 13651 13652@item @emph{See also}: 13653@ref{PACK}, @ref{SPREAD} 13654@end table 13655 13656 13657 13658@node VERIFY 13659@section @code{VERIFY} --- Scan a string for characters not a given set 13660@fnindex VERIFY 13661@cindex string, find missing set 13662 13663@table @asis 13664@item @emph{Description}: 13665Verifies that all the characters in @var{STRING} belong to the set of 13666characters in @var{SET}. 13667 13668If @var{BACK} is either absent or equals @code{FALSE}, this function 13669returns the position of the leftmost character of @var{STRING} that is 13670not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost 13671position is returned. If all characters of @var{STRING} are found in 13672@var{SET}, the result is zero. 13673 13674@item @emph{Standard}: 13675Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later 13676 13677@item @emph{Class}: 13678Elemental function 13679 13680@item @emph{Syntax}: 13681@code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])} 13682 13683@item @emph{Arguments}: 13684@multitable @columnfractions .15 .70 13685@item @var{STRING} @tab Shall be of type @code{CHARACTER}. 13686@item @var{SET} @tab Shall be of type @code{CHARACTER}. 13687@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. 13688@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization 13689expression indicating the kind parameter of the result. 13690@end multitable 13691 13692@item @emph{Return value}: 13693The return value is of type @code{INTEGER} and of kind @var{KIND}. If 13694@var{KIND} is absent, the return value is of default integer kind. 13695 13696@item @emph{Example}: 13697@smallexample 13698PROGRAM test_verify 13699 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F' 13700 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R' 13701 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F' 13702 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N' 13703 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none 13704END PROGRAM 13705@end smallexample 13706 13707@item @emph{See also}: 13708@ref{SCAN}, @ref{INDEX intrinsic} 13709@end table 13710 13711 13712 13713@node XOR 13714@section @code{XOR} --- Bitwise logical exclusive OR 13715@fnindex XOR 13716@cindex bitwise logical exclusive or 13717@cindex logical exclusive or, bitwise 13718 13719@table @asis 13720@item @emph{Description}: 13721Bitwise logical exclusive or. 13722 13723This intrinsic routine is provided for backwards compatibility with 13724GNU Fortran 77. For integer arguments, programmers should consider 13725the use of the @ref{IEOR} intrinsic and for logical arguments the 13726@code{.NEQV.} operator, which are both defined by the Fortran standard. 13727 13728@item @emph{Standard}: 13729GNU extension 13730 13731@item @emph{Class}: 13732Function 13733 13734@item @emph{Syntax}: 13735@code{RESULT = XOR(I, J)} 13736 13737@item @emph{Arguments}: 13738@multitable @columnfractions .15 .70 13739@item @var{I} @tab The type shall be either a scalar @code{INTEGER} 13740type or a scalar @code{LOGICAL} type. 13741@item @var{J} @tab The type shall be the same as the type of @var{I}. 13742@end multitable 13743 13744@item @emph{Return value}: 13745The return type is either a scalar @code{INTEGER} or a scalar 13746@code{LOGICAL}. If the kind type parameters differ, then the 13747smaller kind type is implicitly converted to larger kind, and the 13748return has the larger kind. 13749 13750@item @emph{Example}: 13751@smallexample 13752PROGRAM test_xor 13753 LOGICAL :: T = .TRUE., F = .FALSE. 13754 INTEGER :: a, b 13755 DATA a / Z'F' /, b / Z'3' / 13756 13757 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F) 13758 WRITE (*,*) XOR(a, b) 13759END PROGRAM 13760@end smallexample 13761 13762@item @emph{See also}: 13763Fortran 95 elemental function: @ref{IEOR} 13764@end table 13765 13766 13767 13768@node Intrinsic Modules 13769@chapter Intrinsic Modules 13770@cindex intrinsic Modules 13771 13772@menu 13773* ISO_FORTRAN_ENV:: 13774* ISO_C_BINDING:: 13775* IEEE modules:: 13776* OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: 13777* OpenACC Module OPENACC:: 13778@end menu 13779 13780@node ISO_FORTRAN_ENV 13781@section @code{ISO_FORTRAN_ENV} 13782@table @asis 13783@item @emph{Standard}: 13784Fortran 2003 and later, except when otherwise noted 13785@end table 13786 13787The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer 13788named constants: 13789 13790@table @asis 13791@item @code{ATOMIC_INT_KIND}: 13792Default-kind integer constant to be used as kind parameter when defining 13793integer variables used in atomic operations. (Fortran 2008 or later.) 13794 13795@item @code{ATOMIC_LOGICAL_KIND}: 13796Default-kind integer constant to be used as kind parameter when defining 13797logical variables used in atomic operations. (Fortran 2008 or later.) 13798 13799@item @code{CHARACTER_KINDS}: 13800Default-kind integer constant array of rank one containing the supported kind 13801parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) 13802 13803@item @code{CHARACTER_STORAGE_SIZE}: 13804Size in bits of the character storage unit. 13805 13806@item @code{ERROR_UNIT}: 13807Identifies the preconnected unit used for error reporting. 13808 13809@item @code{FILE_STORAGE_SIZE}: 13810Size in bits of the file-storage unit. 13811 13812@item @code{INPUT_UNIT}: 13813Identifies the preconnected unit identified by the asterisk 13814(@code{*}) in @code{READ} statement. 13815 13816@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}: 13817Kind type parameters to specify an INTEGER type with a storage 13818size of 16, 32, and 64 bits. It is negative if a target platform 13819does not support the particular kind. (Fortran 2008 or later.) 13820 13821@item @code{INTEGER_KINDS}: 13822Default-kind integer constant array of rank one containing the supported kind 13823parameters of the @code{INTEGER} type. (Fortran 2008 or later.) 13824 13825@item @code{IOSTAT_END}: 13826The value assigned to the variable passed to the @code{IOSTAT=} specifier of 13827an input/output statement if an end-of-file condition occurred. 13828 13829@item @code{IOSTAT_EOR}: 13830The value assigned to the variable passed to the @code{IOSTAT=} specifier of 13831an input/output statement if an end-of-record condition occurred. 13832 13833@item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}: 13834Scalar default-integer constant, used by @code{INQUIRE} for the 13835@code{IOSTAT=} specifier to denote an that a unit number identifies an 13836internal unit. (Fortran 2008 or later.) 13837 13838@item @code{NUMERIC_STORAGE_SIZE}: 13839The size in bits of the numeric storage unit. 13840 13841@item @code{LOGICAL_KINDS}: 13842Default-kind integer constant array of rank one containing the supported kind 13843parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) 13844 13845@item @code{OUTPUT_UNIT}: 13846Identifies the preconnected unit identified by the asterisk 13847(@code{*}) in @code{WRITE} statement. 13848 13849@item @code{REAL32}, @code{REAL64}, @code{REAL128}: 13850Kind type parameters to specify a REAL type with a storage 13851size of 32, 64, and 128 bits. It is negative if a target platform 13852does not support the particular kind. (Fortran 2008 or later.) 13853 13854@item @code{REAL_KINDS}: 13855Default-kind integer constant array of rank one containing the supported kind 13856parameters of the @code{REAL} type. (Fortran 2008 or later.) 13857 13858@item @code{STAT_LOCKED}: 13859Scalar default-integer constant used as STAT= return value by @code{LOCK} to 13860denote that the lock variable is locked by the executing image. (Fortran 2008 13861or later.) 13862 13863@item @code{STAT_LOCKED_OTHER_IMAGE}: 13864Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 13865denote that the lock variable is locked by another image. (Fortran 2008 or 13866later.) 13867 13868@item @code{STAT_STOPPED_IMAGE}: 13869Positive, scalar default-integer constant used as STAT= return value if the 13870argument in the statement requires synchronisation with an image, which has 13871initiated the termination of the execution. (Fortran 2008 or later.) 13872 13873@item @code{STAT_FAILED_IMAGE}: 13874Positive, scalar default-integer constant used as STAT= return value if the 13875argument in the statement requires communication with an image, which has 13876is in the failed state. (TS 18508 or later.) 13877 13878@item @code{STAT_UNLOCKED}: 13879Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to 13880denote that the lock variable is unlocked. (Fortran 2008 or later.) 13881@end table 13882 13883The module provides the following derived type: 13884 13885@table @asis 13886@item @code{LOCK_TYPE}: 13887Derived type with private components to be use with the @code{LOCK} and 13888@code{UNLOCK} statement. A variable of its type has to be always declared 13889as coarray and may not appear in a variable-definition context. 13890(Fortran 2008 or later.) 13891@end table 13892 13893The module also provides the following intrinsic procedures: 13894@ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}. 13895 13896 13897 13898@node ISO_C_BINDING 13899@section @code{ISO_C_BINDING} 13900@table @asis 13901@item @emph{Standard}: 13902Fortran 2003 and later, GNU extensions 13903@end table 13904 13905The following intrinsic procedures are provided by the module; their 13906definition can be found in the section Intrinsic Procedures of this 13907manual. 13908 13909@table @asis 13910@item @code{C_ASSOCIATED} 13911@item @code{C_F_POINTER} 13912@item @code{C_F_PROCPOINTER} 13913@item @code{C_FUNLOC} 13914@item @code{C_LOC} 13915@item @code{C_SIZEOF} 13916@end table 13917@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF, 13918@c don't really know why. 13919 13920The @code{ISO_C_BINDING} module provides the following named constants of 13921type default integer, which can be used as KIND type parameters. 13922 13923In addition to the integer named constants required by the Fortran 2003 13924standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an 13925extension named constants for the 128-bit integer types supported by the 13926C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}. 13927Furthermore, if @code{__float128} is supported in C, the named constants 13928@code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined. 13929 13930@multitable @columnfractions .15 .35 .35 .35 13931@item Fortran Type @tab Named constant @tab C type @tab Extension 13932@item @code{INTEGER}@tab @code{C_INT} @tab @code{int} 13933@item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int} 13934@item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int} 13935@item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int} 13936@item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char} 13937@item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t} 13938@item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t} 13939@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t} 13940@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t} 13941@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t} 13942@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext. 13943@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t} 13944@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t} 13945@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t} 13946@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t} 13947@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext. 13948@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t} 13949@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t} 13950@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t} 13951@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t} 13952@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext. 13953@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t} 13954@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t} 13955@item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113 13956@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float} 13957@item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double} 13958@item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double} 13959@item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext. 13960@item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex} 13961@item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex} 13962@item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex} 13963@item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext. 13964@item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool} 13965@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char} 13966@end multitable 13967 13968Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)} 13969are defined. 13970 13971@multitable @columnfractions .20 .45 .15 13972@item Name @tab C definition @tab Value 13973@item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'} 13974@item @code{C_ALERT} @tab alert @tab @code{'\a'} 13975@item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'} 13976@item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'} 13977@item @code{C_NEW_LINE} @tab new line @tab @code{'\n'} 13978@item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'} 13979@item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'} 13980@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'} 13981@end multitable 13982 13983Moreover, the following two named constants are defined: 13984 13985@multitable @columnfractions .20 .80 13986@item Name @tab Type 13987@item @code{C_NULL_PTR} @tab @code{C_PTR} 13988@item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR} 13989@end multitable 13990 13991Both are equivalent to the value @code{NULL} in C. 13992 13993 13994 13995@node IEEE modules 13996@section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 13997@table @asis 13998@item @emph{Standard}: 13999Fortran 2003 and later 14000@end table 14001 14002The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} 14003intrinsic modules provide support for exceptions and IEEE arithmetic, as 14004defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard 14005(@emph{Binary floating-point arithmetic for microprocessor systems}). These 14006modules are only provided on the following supported platforms: 14007 14008@itemize @bullet 14009@item i386 and x86_64 processors 14010@item platforms which use the GNU C Library (glibc) 14011@item platforms with support for SysV/386 routines for floating point 14012interface (including Solaris and BSDs) 14013@item platforms with the AIX OS 14014@end itemize 14015 14016For full compliance with the Fortran standards, code using the 14017@code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled 14018with the following options: @code{-fno-unsafe-math-optimizations 14019-frounding-math -fsignaling-nans}. 14020 14021 14022 14023@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS 14024@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS} 14025@table @asis 14026@item @emph{Standard}: 14027OpenMP Application Program Interface v4.0 14028@end table 14029 14030 14031The OpenMP Fortran runtime library routines are provided both in 14032a form of two Fortran 90 modules, named @code{OMP_LIB} and 14033@code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named 14034@file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found 14035in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi 14036Processing Runtime Library} manual, 14037the named constants defined in the modules are listed 14038below. 14039 14040For details refer to the actual 14041@uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf, 14042OpenMP Application Program Interface v4.0}. 14043 14044@code{OMP_LIB_KINDS} provides the following scalar default-integer 14045named constants: 14046 14047@table @asis 14048@item @code{omp_lock_kind} 14049@item @code{omp_nest_lock_kind} 14050@item @code{omp_proc_bind_kind} 14051@item @code{omp_sched_kind} 14052@end table 14053 14054@code{OMP_LIB} provides the scalar default-integer 14055named constant @code{openmp_version} with a value of the form 14056@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 14057of the OpenMP version; for OpenMP v4.0 the value is @code{201307}. 14058 14059The following scalar integer named constants of the 14060kind @code{omp_sched_kind}: 14061 14062@table @asis 14063@item @code{omp_sched_static} 14064@item @code{omp_sched_dynamic} 14065@item @code{omp_sched_guided} 14066@item @code{omp_sched_auto} 14067@end table 14068 14069And the following scalar integer named constants of the 14070kind @code{omp_proc_bind_kind}: 14071 14072@table @asis 14073@item @code{omp_proc_bind_false} 14074@item @code{omp_proc_bind_true} 14075@item @code{omp_proc_bind_master} 14076@item @code{omp_proc_bind_close} 14077@item @code{omp_proc_bind_spread} 14078@end table 14079 14080 14081 14082@node OpenACC Module OPENACC 14083@section OpenACC Module @code{OPENACC} 14084@table @asis 14085@item @emph{Standard}: 14086OpenACC Application Programming Interface v2.0 14087@end table 14088 14089 14090The OpenACC Fortran runtime library routines are provided both in a 14091form of a Fortran 90 module, named @code{OPENACC}, and in form of a 14092Fortran @code{include} file named @file{openacc_lib.h}. The 14093procedures provided by @code{OPENACC} can be found in the 14094@ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing 14095Runtime Library} manual, the named constants defined in the modules 14096are listed below. 14097 14098For details refer to the actual 14099@uref{http://www.openacc.org/, 14100OpenACC Application Programming Interface v2.0}. 14101 14102@code{OPENACC} provides the scalar default-integer 14103named constant @code{openacc_version} with a value of the form 14104@var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month 14105of the OpenACC version; for OpenACC v2.0 the value is @code{201306}. 14106