@ignore Copyright (C) 2005-2016 Free Software Foundation, Inc. This is part of the GNU Fortran manual. For copying conditions, see the file gfortran.texi. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being ``Funding Free Software'', the Front-Cover Texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the gfdl(7) man page. Some basic guidelines for editing this document: (1) The intrinsic procedures are to be listed in alphabetical order. (2) The generic name is to be used. (3) The specific names are included in the function index and in a table at the end of the node (See ABS entry). (4) Try to maintain the same style for each entry. @end ignore @tex \gdef\acos{\mathop{\rm acos}\nolimits} \gdef\asin{\mathop{\rm asin}\nolimits} \gdef\atan{\mathop{\rm atan}\nolimits} \gdef\acosh{\mathop{\rm acosh}\nolimits} \gdef\asinh{\mathop{\rm asinh}\nolimits} \gdef\atanh{\mathop{\rm atanh}\nolimits} @end tex @node Intrinsic Procedures @chapter Intrinsic Procedures @cindex intrinsic procedures @menu * Introduction: Introduction to Intrinsics * @code{ABORT}: ABORT, Abort the program * @code{ABS}: ABS, Absolute value * @code{ACCESS}: ACCESS, Checks file access modes * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence * @code{ACOS}: ACOS, Arccosine function * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function * @code{ADJUSTL}: ADJUSTL, Left adjust a string * @code{ADJUSTR}: ADJUSTR, Right adjust a string * @code{AIMAG}: AIMAG, Imaginary part of complex number * @code{AINT}: AINT, Truncate to a whole number * @code{ALARM}: ALARM, Set an alarm clock * @code{ALL}: ALL, Determine if all values are true * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity * @code{AND}: AND, Bitwise logical AND * @code{ANINT}: ANINT, Nearest whole number * @code{ANY}: ANY, Determine if any values are true * @code{ASIN}: ASIN, Arcsine function * @code{ASINH}: ASINH, Inverse hyperbolic sine function * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair * @code{ATAN}: ATAN, Arctangent function * @code{ATAN2}: ATAN2, Arctangent function * @code{ATANH}: ATANH, Inverse hyperbolic tangent function * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation * @code{BACKTRACE}: BACKTRACE, Show a backtrace * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind * @code{BGE}: BGE, Bitwise greater than or equal to * @code{BGT}: BGT, Bitwise greater than * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function * @code{BLE}: BLE, Bitwise less than or equal to * @code{BLT}: BLT, Bitwise less than * @code{BTEST}: BTEST, Bit test function * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure * @code{C_LOC}: C_LOC, Obtain the C address of an object * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression * @code{CEILING}: CEILING, Integer ceiling function * @code{CHAR}: CHAR, Integer-to-character conversion function * @code{CHDIR}: CHDIR, Change working directory * @code{CHMOD}: CHMOD, Change access permissions of files * @code{CMPLX}: CMPLX, Complex conversion function * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string * @code{COMPLEX}: COMPLEX, Complex conversion function * @code{CONJG}: CONJG, Complex conjugate function * @code{COS}: COS, Cosine function * @code{COSH}: COSH, Hyperbolic cosine function * @code{COUNT}: COUNT, Count occurrences of TRUE in an array * @code{CPU_TIME}: CPU_TIME, CPU time subroutine * @code{CSHIFT}: CSHIFT, Circular shift elements of an array * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine * @code{DBLE}: DBLE, Double precision conversion function * @code{DCMPLX}: DCMPLX, Double complex conversion function * @code{DIGITS}: DIGITS, Significant digits function * @code{DIM}: DIM, Positive difference * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function * @code{DPROD}: DPROD, Double product function * @code{DREAL}: DREAL, Double real part function * @code{DSHIFTL}: DSHIFTL, Combined left shift * @code{DSHIFTR}: DSHIFTR, Combined right shift * @code{DTIME}: DTIME, Execution time subroutine (or function) * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array * @code{EPSILON}: EPSILON, Epsilon function * @code{ERF}: ERF, Error function * @code{ERFC}: ERFC, Complementary error function * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function * @code{ETIME}: ETIME, Execution time subroutine (or function) * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command * @code{EXIT}: EXIT, Exit the program with status. * @code{EXP}: EXP, Exponential function * @code{EXPONENT}: EXPONENT, Exponent function * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string * @code{FGET}: FGET, Read a single character in stream mode from stdin * @code{FGETC}: FGETC, Read a single character in stream mode * @code{FLOOR}: FLOOR, Integer floor function * @code{FLUSH}: FLUSH, Flush I/O unit(s) * @code{FNUM}: FNUM, File number function * @code{FPUT}: FPUT, Write a single character in stream mode to stdout * @code{FPUTC}: FPUTC, Write a single character in stream mode * @code{FRACTION}: FRACTION, Fractional part of the model representation * @code{FREE}: FREE, Memory de-allocation subroutine * @code{FSEEK}: FSEEK, Low level file positioning subroutine * @code{FSTAT}: FSTAT, Get file status * @code{FTELL}: FTELL, Current stream position * @code{GAMMA}: GAMMA, Gamma function * @code{GERROR}: GERROR, Get last system error message * @code{GETARG}: GETARG, Get command line arguments * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments * @code{GETCWD}: GETCWD, Get current working directory * @code{GETENV}: GETENV, Get an environmental variable * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable * @code{GETGID}: GETGID, Group ID function * @code{GETLOG}: GETLOG, Get login name * @code{GETPID}: GETPID, Process ID function * @code{GETUID}: GETUID, User ID function * @code{GMTIME}: GMTIME, Convert time to GMT info * @code{HOSTNM}: HOSTNM, Get system host name * @code{HUGE}: HUGE, Largest number of a kind * @code{HYPOT}: HYPOT, Euclidean distance function * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence * @code{IALL}: IALL, Bitwise AND of array elements * @code{IAND}: IAND, Bitwise logical and * @code{IANY}: IANY, Bitwise OR of array elements * @code{IARGC}: IARGC, Get the number of command line arguments * @code{IBCLR}: IBCLR, Clear bit * @code{IBITS}: IBITS, Bit extraction * @code{IBSET}: IBSET, Set bit * @code{ICHAR}: ICHAR, Character-to-integer conversion function * @code{IDATE}: IDATE, Current local time (day/month/year) * @code{IEOR}: IEOR, Bitwise logical exclusive or * @code{IERRNO}: IERRNO, Function to get the last system error number * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion * @code{INDEX}: INDEX intrinsic, Position of a substring within a string * @code{INT}: INT, Convert to integer type * @code{INT2}: INT2, Convert to 16-bit integer type * @code{INT8}: INT8, Convert to 64-bit integer type * @code{IOR}: IOR, Bitwise logical or * @code{IPARITY}: IPARITY, Bitwise XOR of array elements * @code{IRAND}: IRAND, Integer pseudo-random number * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value * @code{ISATTY}: ISATTY, Whether a unit is a terminal device * @code{ISHFT}: ISHFT, Shift bits * @code{ISHFTC}: ISHFTC, Shift bits circularly * @code{ISNAN}: ISNAN, Tests for a NaN * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds) * @code{KILL}: KILL, Send a signal to a process * @code{KIND}: KIND, Kind of an entity * @code{LBOUND}: LBOUND, Lower dimension bounds of an array * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer * @code{LEN}: LEN, Length of a character entity * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters * @code{LGE}: LGE, Lexical greater than or equal * @code{LGT}: LGT, Lexical greater than * @code{LINK}: LINK, Create a hard link * @code{LLE}: LLE, Lexical less than or equal * @code{LLT}: LLT, Lexical less than * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string * @code{LOC}: LOC, Returns the address of a variable * @code{LOG}: LOG, Logarithm function * @code{LOG10}: LOG10, Base 10 logarithm function * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function * @code{LOGICAL}: LOGICAL, Convert to logical type * @code{LONG}: LONG, Convert to integer type * @code{LSHIFT}: LSHIFT, Left shift bits * @code{LSTAT}: LSTAT, Get file status * @code{LTIME}: LTIME, Convert time to local time info * @code{MALLOC}: MALLOC, Dynamic memory allocation function * @code{MASKL}: MASKL, Left justified mask * @code{MASKR}: MASKR, Right justified mask * @code{MATMUL}: MATMUL, matrix multiplication * @code{MAX}: MAX, Maximum value of an argument list * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array * @code{MAXVAL}: MAXVAL, Maximum value of an array * @code{MCLOCK}: MCLOCK, Time function * @code{MCLOCK8}: MCLOCK8, Time function (64-bit) * @code{MERGE}: MERGE, Merge arrays * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask * @code{MIN}: MIN, Minimum value of an argument list * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind * @code{MINLOC}: MINLOC, Location of the minimum value within an array * @code{MINVAL}: MINVAL, Minimum value of an array * @code{MOD}: MOD, Remainder function * @code{MODULO}: MODULO, Modulo function * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another * @code{MVBITS}: MVBITS, Move bits from one integer to another * @code{NEAREST}: NEAREST, Nearest representable number * @code{NEW_LINE}: NEW_LINE, New line character * @code{NINT}: NINT, Nearest whole number * @code{NORM2}: NORM2, Euclidean vector norm * @code{NOT}: NOT, Logical negation * @code{NULL}: NULL, Function that returns an disassociated pointer * @code{NUM_IMAGES}: NUM_IMAGES, Number of images * @code{OR}: OR, Bitwise logical OR * @code{PACK}: PACK, Pack an array into an array of rank one * @code{PARITY}: PARITY, Reduction with exclusive OR * @code{PERROR}: PERROR, Print system error message * @code{POPCNT}: POPCNT, Number of bits set * @code{POPPAR}: POPPAR, Parity of the number of bits set * @code{PRECISION}: PRECISION, Decimal precision of a real kind * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified * @code{PRODUCT}: PRODUCT, Product of array elements * @code{RADIX}: RADIX, Base of a data model * @code{RAN}: RAN, Real pseudo-random number * @code{RAND}: RAND, Real pseudo-random number * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence * @code{RANGE}: RANGE, Decimal exponent range * @code{RANK} : RANK, Rank of a data object * @code{REAL}: REAL, Convert to real type * @code{RENAME}: RENAME, Rename a file * @code{REPEAT}: REPEAT, Repeated string concatenation * @code{RESHAPE}: RESHAPE, Function to reshape an array * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing * @code{RSHIFT}: RSHIFT, Right shift bits * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality * @code{SCALE}: SCALE, Scale a real value * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters * @code{SECNDS}: SECNDS, Time function * @code{SECOND}: SECOND, CPU time function * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model * @code{SHAPE}: SHAPE, Determine the shape of an array * @code{SHIFTA}: SHIFTA, Right shift with fill * @code{SHIFTL}: SHIFTL, Left shift * @code{SHIFTR}: SHIFTR, Right shift * @code{SIGN}: SIGN, Sign copying function * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function) * @code{SIN}: SIN, Sine function * @code{SINH}: SINH, Hyperbolic sine function * @code{SIZE}: SIZE, Function to determine the size of an array * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type * @code{SPREAD}: SPREAD, Add a dimension to an array * @code{SQRT}: SQRT, Square-root function * @code{SRAND}: SRAND, Reinitialize the random number generator * @code{STAT}: STAT, Get file status * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits * @code{SUM}: SUM, Sum of array elements * @code{SYMLNK}: SYMLNK, Create a symbolic link * @code{SYSTEM}: SYSTEM, Execute a shell command * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function * @code{TAN}: TAN, Tangent function * @code{TANH}: TANH, Hyperbolic tangent function * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image * @code{TIME}: TIME, Time function * @code{TIME8}: TIME8, Time function (64-bit) * @code{TINY}: TINY, Smallest positive number of a real kind * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer * @code{TRANSFER}: TRANSFER, Transfer bit patterns * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two * @code{TRIM}: TRIM, Remove trailing blank characters of a string * @code{TTYNAM}: TTYNAM, Get the name of a terminal device. * @code{UBOUND}: UBOUND, Upper dimension bounds of an array * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array * @code{UMASK}: UMASK, Set the file creation mask * @code{UNLINK}: UNLINK, Remove a file from the file system * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters * @code{XOR}: XOR, Bitwise logical exclusive or @end menu @node Introduction to Intrinsics @section Introduction to intrinsic procedures The intrinsic procedures provided by GNU Fortran include all of the intrinsic procedures required by the Fortran 95 standard, a set of intrinsic procedures for backwards compatibility with G77, and a selection of intrinsic procedures from the Fortran 2003 and Fortran 2008 standards. Any conflict between a description here and a description in either the Fortran 95 standard, the Fortran 2003 standard or the Fortran 2008 standard is unintentional, and the standard(s) should be considered authoritative. The enumeration of the @code{KIND} type parameter is processor defined in the Fortran 95 standard. GNU Fortran defines the default integer type and default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)}, respectively. The standard mandates that both data types shall have another kind, which have more precision. On typical target architectures supported by @command{gfortran}, this kind type parameter is @code{KIND=8}. Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent. In the description of generic intrinsic procedures, the kind type parameter will be specified by @code{KIND=*}, and in the description of specific names for an intrinsic procedure the kind type parameter will be explicitly given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for brevity the optional @code{KIND=} syntax will be omitted. Many of the intrinsic procedures take one or more optional arguments. This document follows the convention used in the Fortran 95 standard, and denotes such arguments by square brackets. GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options, which can be used to restrict the set of intrinsic procedures to a given standard. By default, @command{gfortran} sets the @option{-std=gnu} option, and so all intrinsic procedures described here are accepted. There is one caveat. For a select group of intrinsic procedures, @command{g77} implemented both a function and a subroutine. Both classes have been implemented in @command{gfortran} for backwards compatibility with @command{g77}. It is noted here that these functions and subroutines cannot be intermixed in a given subprogram. In the descriptions that follow, the applicable standard for each intrinsic procedure is noted. @node ABORT @section @code{ABORT} --- Abort the program @fnindex ABORT @cindex program termination, with core dump @cindex terminate program, with core dump @cindex core, dump @table @asis @item @emph{Description}: @code{ABORT} causes immediate termination of the program. On operating systems that support a core dump, @code{ABORT} will produce a core dump. It will also print a backtrace, unless @code{-fno-backtrace} is given. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL ABORT} @item @emph{Return value}: Does not return. @item @emph{Example}: @smallexample program test_abort integer :: i = 1, j = 2 if (i /= j) call abort end program test_abort @end smallexample @item @emph{See also}: @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE} @end table @node ABS @section @code{ABS} --- Absolute value @fnindex ABS @fnindex CABS @fnindex DABS @fnindex IABS @fnindex ZABS @fnindex CDABS @cindex absolute value @table @asis @item @emph{Description}: @code{ABS(A)} computes the absolute value of @code{A}. @item @emph{Standard}: Fortran 77 and later, has overloads that are GNU extensions @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ABS(A)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab The type of the argument shall be an @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as the argument except the return value is @code{REAL} for a @code{COMPLEX} argument. @item @emph{Example}: @smallexample program test_abs integer :: i = -1 real :: x = -1.e0 complex :: z = (-1.e0,0.e0) i = abs(i) x = abs(x) x = abs(z) end program test_abs @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension @end multitable @end table @node ACCESS @section @code{ACCESS} --- Checks file access modes @fnindex ACCESS @cindex file system, access mode @table @asis @item @emph{Description}: @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} exists, is readable, writable or executable. Except for the executable check, @code{ACCESS} can be replaced by Fortran 95's @code{INQUIRE}. @item @emph{Standard}: GNU extension @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = ACCESS(NAME, MODE)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the file name. Tailing blank are ignored unless the character @code{achar(0)} is present, then all characters up to and excluding @code{achar(0)} are used as file name. @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the file access mode, may be any concatenation of @code{"r"} (readable), @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check for existence. @end multitable @item @emph{Return value}: Returns a scalar @code{INTEGER}, which is @code{0} if the file is accessible in the given mode; otherwise or if an invalid argument has been given for @code{MODE} the value @code{1} is returned. @item @emph{Example}: @smallexample program access_test implicit none character(len=*), parameter :: file = 'test.dat' character(len=*), parameter :: file2 = 'test.dat '//achar(0) if(access(file,' ') == 0) print *, trim(file),' is exists' if(access(file,'r') == 0) print *, trim(file),' is readable' if(access(file,'w') == 0) print *, trim(file),' is writable' if(access(file,'x') == 0) print *, trim(file),' is executable' if(access(file2,'rwx') == 0) & print *, trim(file2),' is readable, writable and executable' end program access_test @end smallexample @item @emph{Specific names}: @item @emph{See also}: @end table @node ACHAR @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence @fnindex ACHAR @cindex @acronym{ASCII} collating sequence @cindex collating sequence, @acronym{ASCII} @table @asis @item @emph{Description}: @code{ACHAR(I)} returns the character located at position @code{I} in the @acronym{ASCII} collating sequence. @item @emph{Standard}: Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ACHAR(I [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{CHARACTER} with a length of one. If the @var{KIND} argument is present, the return value is of the specified kind and of the default kind otherwise. @item @emph{Example}: @smallexample program test_achar character c c = achar(32) end program test_achar @end smallexample @item @emph{Note}: See @ref{ICHAR} for a discussion of converting between numerical values and formatted string representations. @item @emph{See also}: @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR} @end table @node ACOS @section @code{ACOS} --- Arccosine function @fnindex ACOS @fnindex DACOS @cindex trigonometric function, cosine, inverse @cindex cosine, inverse @table @asis @item @emph{Description}: @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}). @item @emph{Standard}: Fortran 77 and later, for a complex argument Fortran 2008 or later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ACOS(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is less than or equal to one - or the type shall be @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X}. The real part of the result is in radians and lies in the range @math{0 \leq \Re \acos(x) \leq \pi}. @item @emph{Example}: @smallexample program test_acos real(8) :: x = 0.866_8 x = acos(x) end program test_acos @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @item @emph{See also}: Inverse function: @ref{COS} @end table @node ACOSH @section @code{ACOSH} --- Inverse hyperbolic cosine function @fnindex ACOSH @fnindex DACOSH @cindex area hyperbolic cosine @cindex inverse hyperbolic cosine @cindex hyperbolic function, cosine, inverse @cindex cosine, hyperbolic, inverse @table @asis @item @emph{Description}: @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ACOSH(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value has the same type and kind as @var{X}. If @var{X} is complex, the imaginary part of the result is in radians and lies between @math{ 0 \leq \Im \acosh(x) \leq \pi}. @item @emph{Example}: @smallexample PROGRAM test_acosh REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /) WRITE (*,*) ACOSH(x) END PROGRAM @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension @end multitable @item @emph{See also}: Inverse function: @ref{COSH} @end table @node ADJUSTL @section @code{ADJUSTL} --- Left adjust a string @fnindex ADJUSTL @cindex string, adjust left @cindex adjust string @table @asis @item @emph{Description}: @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces. Spaces are inserted at the end of the string as needed. @item @emph{Standard}: Fortran 90 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ADJUSTL(STRING)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab The type shall be @code{CHARACTER}. @end multitable @item @emph{Return value}: The return value is of type @code{CHARACTER} and of the same kind as @var{STRING} where leading spaces are removed and the same number of spaces are inserted on the end of @var{STRING}. @item @emph{Example}: @smallexample program test_adjustl character(len=20) :: str = ' gfortran' str = adjustl(str) print *, str end program test_adjustl @end smallexample @item @emph{See also}: @ref{ADJUSTR}, @ref{TRIM} @end table @node ADJUSTR @section @code{ADJUSTR} --- Right adjust a string @fnindex ADJUSTR @cindex string, adjust right @cindex adjust string @table @asis @item @emph{Description}: @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces. Spaces are inserted at the start of the string as needed. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ADJUSTR(STRING)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STR} @tab The type shall be @code{CHARACTER}. @end multitable @item @emph{Return value}: The return value is of type @code{CHARACTER} and of the same kind as @var{STRING} where trailing spaces are removed and the same number of spaces are inserted at the start of @var{STRING}. @item @emph{Example}: @smallexample program test_adjustr character(len=20) :: str = 'gfortran' str = adjustr(str) print *, str end program test_adjustr @end smallexample @item @emph{See also}: @ref{ADJUSTL}, @ref{TRIM} @end table @node AIMAG @section @code{AIMAG} --- Imaginary part of complex number @fnindex AIMAG @fnindex DIMAG @fnindex IMAG @fnindex IMAGPART @cindex complex numbers, imaginary part @table @asis @item @emph{Description}: @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}. The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided for compatibility with @command{g77}, and their use in new code is strongly discouraged. @item @emph{Standard}: Fortran 77 and later, has overloads that are GNU extensions @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = AIMAG(Z)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} with the kind type parameter of the argument. @item @emph{Example}: @smallexample program test_aimag complex(4) z4 complex(8) z8 z4 = cmplx(1.e0_4, 0.e0_4) z8 = cmplx(0.e0_8, 1.e0_8) print *, aimag(z4), dimag(z8) end program test_aimag @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension @end multitable @end table @node AINT @section @code{AINT} --- Truncate to a whole number @fnindex AINT @fnindex DINT @cindex floor @cindex rounding, floor @table @asis @item @emph{Description}: @code{AINT(A [, KIND])} truncates its argument to a whole number. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = AINT(A [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab The type of the argument shall be @code{REAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} with the kind type parameter of the argument if the optional @var{KIND} is absent; otherwise, the kind type parameter will be given by @var{KIND}. If the magnitude of @var{X} is less than one, @code{AINT(X)} returns zero. If the magnitude is equal to or greater than one then it returns the largest whole number that does not exceed its magnitude. The sign is the same as the sign of @var{X}. @item @emph{Example}: @smallexample program test_aint real(4) x4 real(8) x8 x4 = 1.234E0_4 x8 = 4.321_8 print *, aint(x4), dint(x8) x8 = aint(x4,8) end program test_aint @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @end table @node ALARM @section @code{ALARM} --- Execute a routine after a given delay @fnindex ALARM @cindex delayed execution @table @asis @item @emph{Description}: @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is supplied, it will be returned with the number of seconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL ALARM(SECONDS, HANDLER [, STATUS])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SECONDS} @tab The type of the argument shall be a scalar @code{INTEGER}. It is @code{INTENT(IN)}. @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar values may be either @code{SIG_IGN=1} to ignore the alarm generated or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}. @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}. @end multitable @item @emph{Example}: @smallexample program test_alarm external handler_print integer i call alarm (3, handler_print, i) print *, i call sleep(10) end program test_alarm @end smallexample This will cause the external routine @var{handler_print} to be called after 3 seconds. @end table @node ALL @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true @fnindex ALL @cindex array, apply condition @cindex array, condition testing @table @asis @item @emph{Description}: @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK} in the array along dimension @var{DIM}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = ALL(MASK [, DIM])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and it shall not be scalar. @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer with a value that lies between one and the rank of @var{MASK}. @end multitable @item @emph{Return value}: @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where the kind type parameter is the same as the kind type parameter of @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns an array with the rank of @var{MASK} minus 1. The shape is determined from the shape of @var{MASK} where the @var{DIM} dimension is elided. @table @asis @item (A) @code{ALL(MASK)} is true if all elements of @var{MASK} are true. It also is true if @var{MASK} has zero size; otherwise, it is false. @item (B) If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)} is determined by applying @code{ALL} to the array sections. @end table @item @emph{Example}: @smallexample program test_all logical l l = all((/.true., .true., .true./)) print *, l call section contains subroutine section integer a(2,3), b(2,3) a = 1 b = 1 b(2,2) = 2 print *, all(a .eq. b, 1) print *, all(a .eq. b, 2) end subroutine section end program test_all @end smallexample @end table @node ALLOCATED @section @code{ALLOCATED} --- Status of an allocatable entity @fnindex ALLOCATED @cindex allocation, status @table @asis @item @emph{Description}: @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation status of @var{ARRAY} and @var{SCALAR}, respectively. @item @emph{Standard}: Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable scalar entities are available in Fortran 2003 and later. @item @emph{Class}: Inquiry function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = ALLOCATED(ARRAY)} @item @code{RESULT = ALLOCATED(SCALAR)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array. @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar. @end multitable @item @emph{Return value}: The return value is a scalar @code{LOGICAL} with the default logical kind type parameter. If the argument is allocated, then the result is @code{.TRUE.}; otherwise, it returns @code{.FALSE.} @item @emph{Example}: @smallexample program test_allocated integer :: i = 4 real(4), allocatable :: x(:) if (.not. allocated(x)) allocate(x(i)) end program test_allocated @end smallexample @end table @node AND @section @code{AND} --- Bitwise logical AND @fnindex AND @cindex bitwise logical and @cindex logical and, bitwise @table @asis @item @emph{Description}: Bitwise logical @code{AND}. This intrinsic routine is provided for backwards compatibility with GNU Fortran 77. For integer arguments, programmers should consider the use of the @ref{IAND} intrinsic defined by the Fortran standard. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = AND(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be either a scalar @code{INTEGER} type or a scalar @code{LOGICAL} type. @item @var{J} @tab The type shall be the same as the type of @var{I}. @end multitable @item @emph{Return value}: The return type is either a scalar @code{INTEGER} or a scalar @code{LOGICAL}. If the kind type parameters differ, then the smaller kind type is implicitly converted to larger kind, and the return has the larger kind. @item @emph{Example}: @smallexample PROGRAM test_and LOGICAL :: T = .TRUE., F = .FALSE. INTEGER :: a, b DATA a / Z'F' /, b / Z'3' / WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F) WRITE (*,*) AND(a, b) END PROGRAM @end smallexample @item @emph{See also}: Fortran 95 elemental function: @ref{IAND} @end table @node ANINT @section @code{ANINT} --- Nearest whole number @fnindex ANINT @fnindex DNINT @cindex ceiling @cindex rounding, ceiling @table @asis @item @emph{Description}: @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ANINT(A [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab The type of the argument shall be @code{REAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type real with the kind type parameter of the argument if the optional @var{KIND} is absent; otherwise, the kind type parameter will be given by @var{KIND}. If @var{A} is greater than zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is less than or equal to zero then it returns @code{AINT(X-0.5)}. @item @emph{Example}: @smallexample program test_anint real(4) x4 real(8) x8 x4 = 1.234E0_4 x8 = 4.321_8 print *, anint(x4), dnint(x8) x8 = anint(x4,8) end program test_anint @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @end table @node ANY @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true @fnindex ANY @cindex array, apply condition @cindex array, condition testing @table @asis @item @emph{Description}: @code{ANY(MASK [, DIM])} determines if any of the values in the logical array @var{MASK} along dimension @var{DIM} are @code{.TRUE.}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = ANY(MASK [, DIM])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and it shall not be scalar. @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer with a value that lies between one and the rank of @var{MASK}. @end multitable @item @emph{Return value}: @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where the kind type parameter is the same as the kind type parameter of @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns an array with the rank of @var{MASK} minus 1. The shape is determined from the shape of @var{MASK} where the @var{DIM} dimension is elided. @table @asis @item (A) @code{ANY(MASK)} is true if any element of @var{MASK} is true; otherwise, it is false. It also is false if @var{MASK} has zero size. @item (B) If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)} is determined by applying @code{ANY} to the array sections. @end table @item @emph{Example}: @smallexample program test_any logical l l = any((/.true., .true., .true./)) print *, l call section contains subroutine section integer a(2,3), b(2,3) a = 1 b = 1 b(2,2) = 2 print *, any(a .eq. b, 1) print *, any(a .eq. b, 2) end subroutine section end program test_any @end smallexample @end table @node ASIN @section @code{ASIN} --- Arcsine function @fnindex ASIN @fnindex DASIN @cindex trigonometric function, sine, inverse @cindex sine, inverse @table @asis @item @emph{Description}: @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}). @item @emph{Standard}: Fortran 77 and later, for a complex argument Fortran 2008 or later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ASIN(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is less than or equal to one - or be @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X}. The real part of the result is in radians and lies in the range @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}. @item @emph{Example}: @smallexample program test_asin real(8) :: x = 0.866_8 x = asin(x) end program test_asin @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @item @emph{See also}: Inverse function: @ref{SIN} @end table @node ASINH @section @code{ASINH} --- Inverse hyperbolic sine function @fnindex ASINH @fnindex DASINH @cindex area hyperbolic sine @cindex inverse hyperbolic sine @cindex hyperbolic function, sine, inverse @cindex sine, hyperbolic, inverse @table @asis @item @emph{Description}: @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ASINH(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X}. If @var{X} is complex, the imaginary part of the result is in radians and lies between @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}. @item @emph{Example}: @smallexample PROGRAM test_asinh REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) WRITE (*,*) ASINH(x) END PROGRAM @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension. @end multitable @item @emph{See also}: Inverse function: @ref{SINH} @end table @node ASSOCIATED @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair @fnindex ASSOCIATED @cindex pointer, status @cindex association status @table @asis @item @emph{Description}: @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = ASSOCIATED(POINTER [, TARGET])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute and it can be of any type. @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or a target. It must have the same type, kind type parameter, and array rank as @var{POINTER}. @end multitable The association status of neither @var{POINTER} nor @var{TARGET} shall be undefined. @item @emph{Return value}: @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}. There are several cases: @table @asis @item (A) When the optional @var{TARGET} is not present then @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false. @item (B) If @var{TARGET} is present and a scalar target, the result is true if @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 disassociated, the result is false. @item (C) If @var{TARGET} is present and an array target, the result is true if @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays, are arrays whose elements are not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy the same storage units in array element order. As in case(B), the result is false, if @var{POINTER} is disassociated. @item (D) If @var{TARGET} is present and an scalar pointer, the result is true if @var{TARGET} is associated with @var{POINTER}, the target associated with @var{TARGET} are not zero-sized storage sequences and occupy the same storage units. The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. @item (E) If @var{TARGET} is present and an array pointer, the result is true if target associated with @var{POINTER} and the target associated with @var{TARGET} have the same shape, are not zero-sized arrays, are arrays whose elements are not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy the same storage units in array element order. The result is false, if either @var{TARGET} or @var{POINTER} is disassociated. @end table @item @emph{Example}: @smallexample program test_associated implicit none real, target :: tgt(2) = (/1., 2./) real, pointer :: ptr(:) ptr => tgt if (associated(ptr) .eqv. .false.) call abort if (associated(ptr,tgt) .eqv. .false.) call abort end program test_associated @end smallexample @item @emph{See also}: @ref{NULL} @end table @node ATAN @section @code{ATAN} --- Arctangent function @fnindex ATAN @fnindex DATAN @cindex trigonometric function, tangent, inverse @cindex tangent, inverse @table @asis @item @emph{Description}: @code{ATAN(X)} computes the arctangent of @var{X}. @item @emph{Standard}: Fortran 77 and later, for a complex argument and for two arguments Fortran 2008 or later @item @emph{Class}: Elemental function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = ATAN(X)} @item @code{RESULT = ATAN(Y, X)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}; if @var{Y} is present, @var{X} shall be REAL. @item @var{Y} shall be of the same type and kind as @var{X}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X}. If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}. Otherwise, it the arcus tangent of @var{X}, where the real part of the result is in radians and lies in the range @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}. @item @emph{Example}: @smallexample program test_atan real(8) :: x = 2.866_8 x = atan(x) end program test_atan @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @item @emph{See also}: Inverse function: @ref{TAN} @end table @node ATAN2 @section @code{ATAN2} --- Arctangent function @fnindex ATAN2 @fnindex DATAN2 @cindex trigonometric function, tangent, inverse @cindex tangent, inverse @table @asis @item @emph{Description}: @code{ATAN2(Y, X)} computes the principal value of the argument function of the complex number @math{X + i Y}. This function can be used to transform from Cartesian into polar coordinates and allows to determine the angle in the correct quadrant. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ATAN2(Y, X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{Y} @tab The type shall be @code{REAL}. @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}. If @var{Y} is zero, then @var{X} must be nonzero. @end multitable @item @emph{Return value}: The return value has the same type and kind type parameter as @var{Y}. It is the principal value of the complex number @math{X + i Y}. If @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}. The sign is positive if @var{Y} is positive. If @var{Y} is zero, then the return value is zero if @var{X} is strictly positive, @math{\pi} if @var{X} is negative and @var{Y} is positive zero (or the processor does not handle signed zeros), and @math{-\pi} if @var{X} is negative and @var{Y} is negative zero. Finally, if @var{X} is zero, then the magnitude of the result is @math{\pi/2}. @item @emph{Example}: @smallexample program test_atan2 real(4) :: x = 1.e0_4, y = 0.5e0_4 x = atan2(y,x) end program test_atan2 @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @end table @node ATANH @section @code{ATANH} --- Inverse hyperbolic tangent function @fnindex ATANH @fnindex DATANH @cindex area hyperbolic tangent @cindex inverse hyperbolic tangent @cindex hyperbolic function, tangent, inverse @cindex tangent, hyperbolic, inverse @table @asis @item @emph{Description}: @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ATANH(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value has same type and kind as @var{X}. If @var{X} is complex, the imaginary part of the result is in radians and lies between @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}. @item @emph{Example}: @smallexample PROGRAM test_atanh REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /) WRITE (*,*) ATANH(x) END PROGRAM @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension @end multitable @item @emph{See also}: Inverse function: @ref{TANH} @end table @node ATOMIC_ADD @section @code{ATOMIC_ADD} --- Atomic ADD operation @fnindex ATOMIC_ADD @cindex Atomic subroutine, add @table @asis @item @emph{Description}: @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the variable @var{ATOM}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer type with @code{ATOMIC_INT_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*] call atomic_add (atom[1], this_image()) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} @end table @node ATOMIC_AND @section @code{ATOMIC_AND} --- Atomic bitwise AND operation @fnindex ATOMIC_AND @cindex Atomic subroutine, AND @table @asis @item @emph{Description}: @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer type with @code{ATOMIC_INT_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*] call atomic_and (atom[1], int(b'10100011101')) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} @end table @node ATOMIC_CAS @section @code{ATOMIC_CAS} --- Atomic compare and swap @fnindex ATOMIC_DEFINE @cindex Atomic subroutine, compare and swap @table @asis @item @emph{Description}: @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM} that was used for the comparison. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer type with @code{ATOMIC_INT_KIND} kind or logical type with @code{ATOMIC_LOGICAL_KIND} kind. @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. @item @var{COMPARE} @tab Scalar variable of the same type and kind as @var{ATOM}. @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind is different, the value is converted to the kind of @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env logical(atomic_logical_kind) :: atom[*], prev call atomic_cas (atom[1], prev, .false., .true.)) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV} @end table @node ATOMIC_DEFINE @section @code{ATOMIC_DEFINE} --- Setting a variable atomically @fnindex ATOMIC_DEFINE @cindex Atomic subroutine, define @table @asis @item @emph{Description}: @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value @var{VALUE} atomically. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: Fortran 2008 and later; with @var{STAT}, TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer type with @code{ATOMIC_INT_KIND} kind or logical type with @code{ATOMIC_LOGICAL_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*] call atomic_define (atom[1], this_image()) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} @end table @node ATOMIC_FETCH_ADD @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch @fnindex ATOMIC_FETCH_ADD @cindex Atomic subroutine, ADD with fetch @table @asis @item @emph{Description}: @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the variable @var{ATOM}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer type with @code{ATOMIC_INT_KIND} kind. @code{ATOMIC_LOGICAL_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*], old call atomic_add (atom[1], this_image(), old) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} @end table @node ATOMIC_FETCH_AND @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch @fnindex ATOMIC_FETCH_AND @cindex Atomic subroutine, AND with fetch @table @asis @item @emph{Description}: @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer type with @code{ATOMIC_INT_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*], old call atomic_fetch_and (atom[1], int(b'10100011101'), old) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} @end table @node ATOMIC_FETCH_OR @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch @fnindex ATOMIC_FETCH_OR @cindex Atomic subroutine, OR with fetch @table @asis @item @emph{Description}: @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer type with @code{ATOMIC_INT_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*], old call atomic_fetch_or (atom[1], int(b'10100011101'), old) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR} @end table @node ATOMIC_FETCH_XOR @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch @fnindex ATOMIC_FETCH_XOR @cindex Atomic subroutine, XOR with fetch @table @asis @item @emph{Description}: @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer type with @code{ATOMIC_INT_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*], old call atomic_fetch_xor (atom[1], int(b'10100011101'), old) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR} @end table @node ATOMIC_OR @section @code{ATOMIC_OR} --- Atomic bitwise OR operation @fnindex ATOMIC_OR @cindex Atomic subroutine, OR @table @asis @item @emph{Description}: @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer type with @code{ATOMIC_INT_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*] call atomic_or (atom[1], int(b'10100011101')) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} @end table @node ATOMIC_REF @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically @fnindex ATOMIC_REF @cindex Atomic subroutine, reference @table @asis @item @emph{Description}: @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: Fortran 2008 and later; with @var{STAT}, TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer type with @code{ATOMIC_INT_KIND} kind or logical type with @code{ATOMIC_LOGICAL_KIND} kind. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env logical(atomic_logical_kind) :: atom[*] logical :: val call atomic_ref (atom, .false.) ! ... call atomic_ref (atom, val) if (val) then print *, "Obtained" end if end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR} @end table @node ATOMIC_XOR @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation @fnindex ATOMIC_XOR @cindex Atomic subroutine, XOR @table @asis @item @emph{Description}: @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value; in particular, for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has failed, the value @code{STAT_FAILED_IMAGE}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: Atomic subroutine @item @emph{Syntax}: @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer type with @code{ATOMIC_INT_KIND} kind. @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind is different, the value is converted to the kind of @var{ATOM}. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env integer(atomic_int_kind) :: atom[*] call atomic_xor (atom[1], int(b'10100011101')) end program atomic @end smallexample @item @emph{See also}: @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV}, @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR} @end table @node BACKTRACE @section @code{BACKTRACE} --- Show a backtrace @fnindex BACKTRACE @cindex backtrace @table @asis @item @emph{Description}: @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program execution continues normally afterwards. The backtrace information is printed to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}. @item @emph{Standard}: GNU Extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL BACKTRACE} @item @emph{Arguments}: None @item @emph{See also}: @ref{ABORT} @end table @node BESSEL_J0 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0 @fnindex BESSEL_J0 @fnindex BESJ0 @fnindex DBESJ0 @cindex Bessel function, first kind @table @asis @item @emph{Description}: @code{BESSEL_J0(X)} computes the Bessel function of the first kind of order 0 of @var{X}. This function is available under the name @code{BESJ0} as a GNU extension. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BESSEL_J0(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} and lies in the range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same kind as @var{X}. @item @emph{Example}: @smallexample program test_besj0 real(8) :: x = 0.0_8 x = bessel_j0(x) end program test_besj0 @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension @end multitable @end table @node BESSEL_J1 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1 @fnindex BESSEL_J1 @fnindex BESJ1 @fnindex DBESJ1 @cindex Bessel function, first kind @table @asis @item @emph{Description}: @code{BESSEL_J1(X)} computes the Bessel function of the first kind of order 1 of @var{X}. This function is available under the name @code{BESJ1} as a GNU extension. @item @emph{Standard}: Fortran 2008 @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BESSEL_J1(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} and lies in the range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same kind as @var{X}. @item @emph{Example}: @smallexample program test_besj1 real(8) :: x = 1.0_8 x = bessel_j1(x) end program test_besj1 @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension @end multitable @end table @node BESSEL_JN @section @code{BESSEL_JN} --- Bessel function of the first kind @fnindex BESSEL_JN @fnindex BESJN @fnindex DBESJN @cindex Bessel function, first kind @table @asis @item @emph{Description}: @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of order @var{N} of @var{X}. This function is available under the name @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays, their ranks and shapes shall conform. @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions of the first kind of the orders @var{N1} to @var{N2}. @item @emph{Standard}: Fortran 2008 and later, negative @var{N} is allowed as GNU extension @item @emph{Class}: Elemental function, except for the transformational function @code{BESSEL_JN(N1, N2, X)} @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = BESSEL_JN(N, X)} @item @code{RESULT = BESSEL_JN(N1, N2, X)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}. @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; for @code{BESSEL_JN(N1, N2, X)} it shall be scalar. @end multitable @item @emph{Return value}: The return value is a scalar of type @code{REAL}. It has the same kind as @var{X}. @item @emph{Note}: The transformational function uses a recurrence algorithm which might, for some values of @var{X}, lead to different results than calls to the elemental function. @item @emph{Example}: @smallexample program test_besjn real(8) :: x = 1.0_8 x = bessel_jn(5,x) end program test_besjn @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension @item @tab @code{REAL(8) X} @tab @tab @end multitable @end table @node BESSEL_Y0 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0 @fnindex BESSEL_Y0 @fnindex BESY0 @fnindex DBESY0 @cindex Bessel function, second kind @table @asis @item @emph{Description}: @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of order 0 of @var{X}. This function is available under the name @code{BESY0} as a GNU extension. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BESSEL_Y0(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL}. It has the same kind as @var{X}. @item @emph{Example}: @smallexample program test_besy0 real(8) :: x = 0.0_8 x = bessel_y0(x) end program test_besy0 @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension @end multitable @end table @node BESSEL_Y1 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1 @fnindex BESSEL_Y1 @fnindex BESY1 @fnindex DBESY1 @cindex Bessel function, second kind @table @asis @item @emph{Description}: @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of order 1 of @var{X}. This function is available under the name @code{BESY1} as a GNU extension. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BESSEL_Y1(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL}. It has the same kind as @var{X}. @item @emph{Example}: @smallexample program test_besy1 real(8) :: x = 1.0_8 x = bessel_y1(x) end program test_besy1 @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension @end multitable @end table @node BESSEL_YN @section @code{BESSEL_YN} --- Bessel function of the second kind @fnindex BESSEL_YN @fnindex BESYN @fnindex DBESYN @cindex Bessel function, second kind @table @asis @item @emph{Description}: @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of order @var{N} of @var{X}. This function is available under the name @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays, their ranks and shapes shall conform. @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions of the first kind of the orders @var{N1} to @var{N2}. @item @emph{Standard}: Fortran 2008 and later, negative @var{N} is allowed as GNU extension @item @emph{Class}: Elemental function, except for the transformational function @code{BESSEL_YN(N1, N2, X)} @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = BESSEL_YN(N, X)} @item @code{RESULT = BESSEL_YN(N1, N2, X)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} . @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}. @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}. @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}; for @code{BESSEL_YN(N1, N2, X)} it shall be scalar. @end multitable @item @emph{Return value}: The return value is a scalar of type @code{REAL}. It has the same kind as @var{X}. @item @emph{Note}: The transformational function uses a recurrence algorithm which might, for some values of @var{X}, lead to different results than calls to the elemental function. @item @emph{Example}: @smallexample program test_besyn real(8) :: x = 1.0_8 x = bessel_yn(5,x) end program test_besyn @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension @item @tab @code{REAL(8) X} @tab @tab @end multitable @end table @node BGE @section @code{BGE} --- Bitwise greater than or equal to @fnindex BGE @cindex bitwise comparison @table @asis @item @emph{Description}: Determines whether an integral is a bitwise greater than or equal to another. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BGE(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of @code{INTEGER} type. @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind as @var{I}. @end multitable @item @emph{Return value}: The return value is of type @code{LOGICAL} and of the default kind. @item @emph{See also}: @ref{BGT}, @ref{BLE}, @ref{BLT} @end table @node BGT @section @code{BGT} --- Bitwise greater than @fnindex BGT @cindex bitwise comparison @table @asis @item @emph{Description}: Determines whether an integral is a bitwise greater than another. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BGT(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of @code{INTEGER} type. @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind as @var{I}. @end multitable @item @emph{Return value}: The return value is of type @code{LOGICAL} and of the default kind. @item @emph{See also}: @ref{BGE}, @ref{BLE}, @ref{BLT} @end table @node BIT_SIZE @section @code{BIT_SIZE} --- Bit size inquiry function @fnindex BIT_SIZE @cindex bits, number of @cindex size of a variable, in bits @table @asis @item @emph{Description}: @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit) represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is independent of the actual value of @var{I}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = BIT_SIZE(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} @item @emph{Example}: @smallexample program test_bit_size integer :: i = 123 integer :: size size = bit_size(i) print *, size end program test_bit_size @end smallexample @end table @node BLE @section @code{BLE} --- Bitwise less than or equal to @fnindex BLE @cindex bitwise comparison @table @asis @item @emph{Description}: Determines whether an integral is a bitwise less than or equal to another. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BLE(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of @code{INTEGER} type. @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind as @var{I}. @end multitable @item @emph{Return value}: The return value is of type @code{LOGICAL} and of the default kind. @item @emph{See also}: @ref{BGT}, @ref{BGE}, @ref{BLT} @end table @node BLT @section @code{BLT} --- Bitwise less than @fnindex BLT @cindex bitwise comparison @table @asis @item @emph{Description}: Determines whether an integral is a bitwise less than another. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BLT(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of @code{INTEGER} type. @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind as @var{I}. @end multitable @item @emph{Return value}: The return value is of type @code{LOGICAL} and of the default kind. @item @emph{See also}: @ref{BGE}, @ref{BGT}, @ref{BLE} @end table @node BTEST @section @code{BTEST} --- Bit test function @fnindex BTEST @cindex bits, testing @table @asis @item @emph{Description}: @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS} in @var{I} is set. The counting of the bits starts at 0. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = BTEST(I, POS)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{POS} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{LOGICAL} @item @emph{Example}: @smallexample program test_btest integer :: i = 32768 + 1024 + 64 integer :: pos logical :: bool do pos=0,16 bool = btest(i, pos) print *, pos, bool end do end program test_btest @end smallexample @end table @node C_ASSOCIATED @section @code{C_ASSOCIATED} --- Status of a C pointer @fnindex C_ASSOCIATED @cindex association status, C pointer @cindex pointer, C association status @table @asis @item @emph{Description}: @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}. @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}. @end multitable @item @emph{Return value}: The return value is of type @code{LOGICAL}; it is @code{.false.} if either @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2} point to different addresses. @item @emph{Example}: @smallexample subroutine association_test(a,b) use iso_c_binding, only: c_associated, c_loc, c_ptr implicit none real, pointer :: a type(c_ptr) :: b if(c_associated(b, c_loc(a))) & stop 'b and a do not point to same target' end subroutine association_test @end smallexample @item @emph{See also}: @ref{C_LOC}, @ref{C_FUNLOC} @end table @node C_F_POINTER @section @code{C_F_POINTER} --- Convert C into Fortran pointer @fnindex C_F_POINTER @cindex pointer, convert C to Fortran @table @asis @item @emph{Description}: @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is @code{INTENT(IN)}. @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is @code{INTENT(OUT)}. @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER} with @code{INTENT(IN)}. It shall be present if and only if @var{fptr} is an array. The size must be equal to the rank of @var{fptr}. @end multitable @item @emph{Example}: @smallexample program main use iso_c_binding implicit none interface subroutine my_routine(p) bind(c,name='myC_func') import :: c_ptr type(c_ptr), intent(out) :: p end subroutine end interface type(c_ptr) :: cptr real,pointer :: a(:) call my_routine(cptr) call c_f_pointer(cptr, a, [12]) end program main @end smallexample @item @emph{See also}: @ref{C_LOC}, @ref{C_F_PROCPOINTER} @end table @node C_F_PROCPOINTER @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer @fnindex C_F_PROCPOINTER @cindex pointer, C address of pointers @table @asis @item @emph{Description}: @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer @var{CPTR} to the Fortran procedure pointer @var{FPTR}. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL C_F_PROCPOINTER(cptr, fptr)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is @code{INTENT(IN)}. @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is @code{INTENT(OUT)}. @end multitable @item @emph{Example}: @smallexample program main use iso_c_binding implicit none abstract interface function func(a) import :: c_float real(c_float), intent(in) :: a real(c_float) :: func end function end interface interface function getIterFunc() bind(c,name="getIterFunc") import :: c_funptr type(c_funptr) :: getIterFunc end function end interface type(c_funptr) :: cfunptr procedure(func), pointer :: myFunc cfunptr = getIterFunc() call c_f_procpointer(cfunptr, myFunc) end program main @end smallexample @item @emph{See also}: @ref{C_LOC}, @ref{C_F_POINTER} @end table @node C_FUNLOC @section @code{C_FUNLOC} --- Obtain the C address of a procedure @fnindex C_FUNLOC @cindex pointer, C address of procedures @table @asis @item @emph{Description}: @code{C_FUNLOC(x)} determines the C address of the argument. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = C_FUNLOC(x)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{x} @tab Interoperable function or pointer to such function. @end multitable @item @emph{Return value}: The return value is of type @code{C_FUNPTR} and contains the C address of the argument. @item @emph{Example}: @smallexample module x use iso_c_binding implicit none contains subroutine sub(a) bind(c) real(c_float) :: a a = sqrt(a)+5.0 end subroutine sub end module x program main use iso_c_binding use x implicit none interface subroutine my_routine(p) bind(c,name='myC_func') import :: c_funptr type(c_funptr), intent(in) :: p end subroutine end interface call my_routine(c_funloc(sub)) end program main @end smallexample @item @emph{See also}: @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} @end table @node C_LOC @section @code{C_LOC} --- Obtain the C address of an object @fnindex C_LOC @cindex procedure pointer, convert C to Fortran @table @asis @item @emph{Description}: @code{C_LOC(X)} determines the C address of the argument. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = C_LOC(X)} @item @emph{Arguments}: @multitable @columnfractions .10 .75 @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. @end multitable @item @emph{Return value}: The return value is of type @code{C_PTR} and contains the C address of the argument. @item @emph{Example}: @smallexample subroutine association_test(a,b) use iso_c_binding, only: c_associated, c_loc, c_ptr implicit none real, pointer :: a type(c_ptr) :: b if(c_associated(b, c_loc(a))) & stop 'b and a do not point to same target' end subroutine association_test @end smallexample @item @emph{See also}: @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER} @end table @node C_SIZEOF @section @code{C_SIZEOF} --- Size in bytes of an expression @fnindex C_SIZEOF @cindex expression size @cindex size of an expression @table @asis @item @emph{Description}: @code{C_SIZEOF(X)} calculates the number of bytes of storage the expression @code{X} occupies. @item @emph{Standard}: Fortran 2008 @item @emph{Class}: Inquiry function of the module @code{ISO_C_BINDING} @item @emph{Syntax}: @code{N = C_SIZEOF(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The argument shall be an interoperable data entity. @end multitable @item @emph{Return value}: The return value is of type integer and of the system-dependent kind @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the number of bytes occupied by the argument. If the argument has the @code{POINTER} attribute, the number of bytes of the storage area pointed to is returned. If the argument is of a derived type with @code{POINTER} or @code{ALLOCATABLE} components, the return value does not account for the sizes of the data pointed to by these components. @item @emph{Example}: @smallexample use iso_c_binding integer(c_int) :: i real(c_float) :: r, s(5) print *, (c_sizeof(s)/c_sizeof(r) == 5) end @end smallexample The example will print @code{.TRUE.} unless you are using a platform where default @code{REAL} variables are unusually padded. @item @emph{See also}: @ref{SIZEOF}, @ref{STORAGE_SIZE} @end table @node CEILING @section @code{CEILING} --- Integer ceiling function @fnindex CEILING @cindex ceiling @cindex rounding, ceiling @table @asis @item @emph{Description}: @code{CEILING(A)} returns the least integer greater than or equal to @var{A}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = CEILING(A [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab The type shall be @code{REAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present and a default-kind @code{INTEGER} otherwise. @item @emph{Example}: @smallexample program test_ceiling real :: x = 63.29 real :: y = -63.59 print *, ceiling(x) ! returns 64 print *, ceiling(y) ! returns -63 end program test_ceiling @end smallexample @item @emph{See also}: @ref{FLOOR}, @ref{NINT} @end table @node CHAR @section @code{CHAR} --- Character conversion function @fnindex CHAR @cindex conversion, to character @table @asis @item @emph{Description}: @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = CHAR(I [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{CHARACTER(1)} @item @emph{Example}: @smallexample program test_char integer :: i = 74 character(1) :: c c = char(i) print *, i, c ! returns 'J' end program test_char @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later @end multitable @item @emph{Note}: See @ref{ICHAR} for a discussion of converting between numerical values and formatted string representations. @item @emph{See also}: @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR} @end table @node CHDIR @section @code{CHDIR} --- Change working directory @fnindex CHDIR @cindex system, working directory @table @asis @item @emph{Description}: Change current working directory to a specified path. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL CHDIR(NAME [, STATUS])} @item @code{STATUS = CHDIR(NAME)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default kind and shall specify a valid path within the file system. @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default kind. Returns 0 on success, and a system specific and nonzero error code otherwise. @end multitable @item @emph{Example}: @smallexample PROGRAM test_chdir CHARACTER(len=255) :: path CALL getcwd(path) WRITE(*,*) TRIM(path) CALL chdir("/tmp") CALL getcwd(path) WRITE(*,*) TRIM(path) END PROGRAM @end smallexample @item @emph{See also}: @ref{GETCWD} @end table @node CHMOD @section @code{CHMOD} --- Change access permissions of files @fnindex CHMOD @cindex file system, change access mode @table @asis @item @emph{Description}: @code{CHMOD} changes the permissions of a file. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL CHMOD(NAME, MODE[, STATUS])} @item @code{STATUS = CHMOD(NAME, MODE)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the file name. Trailing blanks are ignored unless the character @code{achar(0)} is present, then all characters up to and excluding @code{achar(0)} are used as the file name. @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the file permission. @var{MODE} uses the same syntax as the @code{chmod} utility as defined by the POSIX standard. The argument shall either be a string of a nonnegative octal number or a symbolic mode. @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is @code{0} on success and nonzero otherwise. @end multitable @item @emph{Return value}: In either syntax, @var{STATUS} is set to @code{0} on success and nonzero otherwise. @item @emph{Example}: @code{CHMOD} as subroutine @smallexample program chmod_test implicit none integer :: status call chmod('test.dat','u+x',status) print *, 'Status: ', status end program chmod_test @end smallexample @code{CHMOD} as function: @smallexample program chmod_test implicit none integer :: status status = chmod('test.dat','u+x') print *, 'Status: ', status end program chmod_test @end smallexample @end table @node CMPLX @section @code{CMPLX} --- Complex conversion function @fnindex CMPLX @cindex complex numbers, conversion to @cindex conversion, to complex @table @asis @item @emph{Description}: @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to the real component. If @var{Y} is present it is converted to the imaginary component. If @var{Y} is not present then the imaginary component is set to 0.0. If @var{X} is complex then @var{Y} must not be present. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = CMPLX(X [, Y [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @item @var{Y} @tab (Optional; only allowed if @var{X} is not @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of @code{COMPLEX} type, with a kind equal to @var{KIND} if it is specified. If @var{KIND} is not specified, the result is of the default @code{COMPLEX} kind, regardless of the kinds of @var{X} and @var{Y}. @item @emph{Example}: @smallexample program test_cmplx integer :: i = 42 real :: x = 3.14 complex :: z z = cmplx(i, x) print *, z, cmplx(x) end program test_cmplx @end smallexample @item @emph{See also}: @ref{COMPLEX} @end table @node CO_BROADCAST @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images @fnindex CO_BROADCAST @cindex Collectives, value broadcasting @table @asis @item @emph{Description}: @code{CO_BROADCAST} copies the value of argument @var{A} on the image with image index @code{SOURCE_IMAGE} to all images in the current team. @var{A} becomes defined as if by intrinsic assignment. If the execution was successful and @var{STAT} is present, it is assigned the value zero. If the execution failed, @var{STAT} gets assigned a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing the occurred error. @item @emph{Standard}: Technical Specification (TS) 18508 or later @item @emph{Class}: Collective subroutine @item @emph{Syntax}: @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab INTENT(INOUT) argument; shall have the same dynamic type and type paramters on all images of the current team. If it is an array, it shall have the same shape on all images. @item @var{SOURCE_IMAGE} @tab a scalar integer expression. It shall have the same the same value on all images and refer to an image of the current team. @item @var{STAT} @tab (optional) a scalar integer variable @item @var{ERRMSG} @tab (optional) a scalar character variable @end multitable @item @emph{Example}: @smallexample program test integer :: val(3) if (this_image() == 1) then val = [1, 5, 3] end if call co_broadcast (val, source_image=1) print *, this_image, ":", val end program test @end smallexample @item @emph{See also}: @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE} @end table @node CO_MAX @section @code{CO_MAX} --- Maximal value on the current set of images @fnindex CO_MAX @cindex Collectives, maximal value @table @asis @item @emph{Description}: @code{CO_MAX} determines element-wise the maximal value of @var{A} on all images of the current team. If @var{RESULT_IMAGE} is present, the maximum values are returned in @var{A} on the specified image only and the value of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all images. If the execution was successful and @var{STAT} is present, it is assigned the value zero. If the execution failed, @var{STAT} gets assigned a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing the occurred error. @item @emph{Standard}: Technical Specification (TS) 18508 or later @item @emph{Class}: Collective subroutine @item @emph{Syntax}: @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab shall be an integer, real or character variable, which has the same type and type parameters on all images of the team. @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if present, it shall have the same the same value on all images and refer to an image of the current team. @item @var{STAT} @tab (optional) a scalar integer variable @item @var{ERRMSG} @tab (optional) a scalar character variable @end multitable @item @emph{Example}: @smallexample program test integer :: val val = this_image () call co_max (val, result_image=1) if (this_image() == 1) then write(*,*) "Maximal value", val ! prints num_images() end if end program test @end smallexample @item @emph{See also}: @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} @end table @node CO_MIN @section @code{CO_MIN} --- Minimal value on the current set of images @fnindex CO_MIN @cindex Collectives, minimal value @table @asis @item @emph{Description}: @code{CO_MIN} determines element-wise the minimal value of @var{A} on all images of the current team. If @var{RESULT_IMAGE} is present, the minimal values are returned in @var{A} on the specified image only and the value of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all images. If the execution was successful and @var{STAT} is present, it is assigned the value zero. If the execution failed, @var{STAT} gets assigned a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing the occurred error. @item @emph{Standard}: Technical Specification (TS) 18508 or later @item @emph{Class}: Collective subroutine @item @emph{Syntax}: @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab shall be an integer, real or character variable, which has the same type and type parameters on all images of the team. @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if present, it shall have the same the same value on all images and refer to an image of the current team. @item @var{STAT} @tab (optional) a scalar integer variable @item @var{ERRMSG} @tab (optional) a scalar character variable @end multitable @item @emph{Example}: @smallexample program test integer :: val val = this_image () call co_min (val, result_image=1) if (this_image() == 1) then write(*,*) "Minimal value", val ! prints 1 end if end program test @end smallexample @item @emph{See also}: @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} @end table @node CO_REDUCE @section @code{CO_REDUCE} --- Reduction of values on the current set of images @fnindex CO_REDUCE @cindex Collectives, generic reduction @table @asis @item @emph{Description}: @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A} on all images of the current team. The pure function passed as @var{OPERATOR} is used to pairwise reduce the values of @var{A} by passing either the value of @var{A} of different images or the result values of such a reduction as argument. If @var{A} is an array, the deduction is done element wise. If @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on the specified image only and the value of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all images. If the execution was successful and @var{STAT} is present, it is assigned the value zero. If the execution failed, @var{STAT} gets assigned a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing the occurred error. @item @emph{Standard}: Technical Specification (TS) 18508 or later @item @emph{Class}: Collective subroutine @item @emph{Syntax}: @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer, it shall be associated. @var{A} shall have the same type and type parameters on all images of the team; if it is an array, it shall have the same shape on all images. @item @var{OPERATOR} @tab pure function with two scalar nonallocatable arguments, which shall be nonpolymorphic and have the same type and type parameters as @var{A}. The function shall return a nonallocatable scalar of the same type and type parameters as @var{A}. The function shall be the same on all images and with regards to the arguments mathematically commutative and associative. Note that @var{OPERATOR} may not be an elemental function, unless it is an intrisic function. @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if present, it shall have the same the same value on all images and refer to an image of the current team. @item @var{STAT} @tab (optional) a scalar integer variable @item @var{ERRMSG} @tab (optional) a scalar character variable @end multitable @item @emph{Example}: @smallexample program test integer :: val val = this_image () call co_reduce (val, result_image=1, operator=myprod) if (this_image() == 1) then write(*,*) "Product value", val ! prints num_images() factorial end if contains pure function myprod(a, b) integer, value :: a, b integer :: myprod myprod = a * b end function myprod end program test @end smallexample @item @emph{Note}: While the rules permit in principle an intrinsic function, none of the intrinsics in the standard fulfill the criteria of having a specific function, which takes two arguments of the same type and returning that type as result. @item @emph{See also}: @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST} @end table @node CO_SUM @section @code{CO_SUM} --- Sum of values on the current set of images @fnindex CO_SUM @cindex Collectives, sum of values @table @asis @item @emph{Description}: @code{CO_SUM} sums up the values of each element of @var{A} on all images of the current team. If @var{RESULT_IMAGE} is present, the summed-up values are returned in @var{A} on the specified image only and the value of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all images. If the execution was successful and @var{STAT} is present, it is assigned the value zero. If the execution failed, @var{STAT} gets assigned a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing the occurred error. @item @emph{Standard}: Technical Specification (TS) 18508 or later @item @emph{Class}: Collective subroutine @item @emph{Syntax}: @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab shall be an integer, real or complex variable, which has the same type and type parameters on all images of the team. @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if present, it shall have the same the same value on all images and refer to an image of the current team. @item @var{STAT} @tab (optional) a scalar integer variable @item @var{ERRMSG} @tab (optional) a scalar character variable @end multitable @item @emph{Example}: @smallexample program test integer :: val val = this_image () call co_sum (val, result_image=1) if (this_image() == 1) then write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images() end if end program test @end smallexample @item @emph{See also}: @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST} @end table @node COMMAND_ARGUMENT_COUNT @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments @fnindex COMMAND_ARGUMENT_COUNT @cindex command-line arguments @cindex command-line arguments, number of @cindex arguments, to program @table @asis @item @emph{Description}: @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the command line when the containing program was invoked. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = COMMAND_ARGUMENT_COUNT()} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item None @end multitable @item @emph{Return value}: The return value is an @code{INTEGER} of default kind. @item @emph{Example}: @smallexample program test_command_argument_count integer :: count count = command_argument_count() print *, count end program test_command_argument_count @end smallexample @item @emph{See also}: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT} @end table @node COMPILER_OPTIONS @section @code{COMPILER_OPTIONS} --- Options passed to the compiler @fnindex COMPILER_OPTIONS @cindex flags inquiry function @cindex options inquiry function @cindex compiler flags inquiry function @table @asis @item @emph{Description}: @code{COMPILER_OPTIONS} returns a string with the options used for compiling. @item @emph{Standard}: Fortran 2008 @item @emph{Class}: Inquiry function of the module @code{ISO_FORTRAN_ENV} @item @emph{Syntax}: @code{STR = COMPILER_OPTIONS()} @item @emph{Arguments}: None. @item @emph{Return value}: The return value is a default-kind string with system-dependent length. It contains the compiler flags used to compile the file, which called the @code{COMPILER_OPTIONS} intrinsic. @item @emph{Example}: @smallexample use iso_fortran_env print '(4a)', 'This file was compiled by ', & compiler_version(), ' using the options ', & compiler_options() end @end smallexample @item @emph{See also}: @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV} @end table @node COMPILER_VERSION @section @code{COMPILER_VERSION} --- Compiler version string @fnindex COMPILER_VERSION @cindex compiler, name and version @cindex version of the compiler @table @asis @item @emph{Description}: @code{COMPILER_VERSION} returns a string with the name and the version of the compiler. @item @emph{Standard}: Fortran 2008 @item @emph{Class}: Inquiry function of the module @code{ISO_FORTRAN_ENV} @item @emph{Syntax}: @code{STR = COMPILER_VERSION()} @item @emph{Arguments}: None. @item @emph{Return value}: The return value is a default-kind string with system-dependent length. It contains the name of the compiler and its version number. @item @emph{Example}: @smallexample use iso_fortran_env print '(4a)', 'This file was compiled by ', & compiler_version(), ' using the options ', & compiler_options() end @end smallexample @item @emph{See also}: @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV} @end table @node COMPLEX @section @code{COMPLEX} --- Complex conversion function @fnindex COMPLEX @cindex complex numbers, conversion to @cindex conversion, to complex @table @asis @item @emph{Description}: @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted to the real component and @var{Y} is converted to the imaginary component. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = COMPLEX(X, Y)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}. @end multitable @item @emph{Return value}: If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return value is of default @code{COMPLEX} type. If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL} type and one is of @code{INTEGER} type, then the return value is of @code{COMPLEX} type with a kind equal to that of the @code{REAL} argument with the highest precision. @item @emph{Example}: @smallexample program test_complex integer :: i = 42 real :: x = 3.14 print *, complex(i, x) end program test_complex @end smallexample @item @emph{See also}: @ref{CMPLX} @end table @node CONJG @section @code{CONJG} --- Complex conjugate function @fnindex CONJG @fnindex DCONJG @cindex complex conjugate @table @asis @item @emph{Description}: @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)} then the result is @code{(x, -y)} @item @emph{Standard}: Fortran 77 and later, has overloads that are GNU extensions @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{Z = CONJG(Z)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{Z} @tab The type shall be @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of type @code{COMPLEX}. @item @emph{Example}: @smallexample program test_conjg complex :: z = (2.0, 3.0) complex(8) :: dz = (2.71_8, -3.14_8) z= conjg(z) print *, z dz = dconjg(dz) print *, dz end program test_conjg @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension @end multitable @end table @node COS @section @code{COS} --- Cosine function @fnindex COS @fnindex DCOS @fnindex CCOS @fnindex ZCOS @fnindex CDCOS @cindex trigonometric function, cosine @cindex cosine @table @asis @item @emph{Description}: @code{COS(X)} computes the cosine of @var{X}. @item @emph{Standard}: Fortran 77 and later, has overloads that are GNU extensions @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = COS(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X}. The real part of the result is in radians. If @var{X} is of the type @code{REAL}, the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}. @item @emph{Example}: @smallexample program test_cos real :: x = 0.0 x = cos(x) end program test_cos @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension @end multitable @item @emph{See also}: Inverse function: @ref{ACOS} @end table @node COSH @section @code{COSH} --- Hyperbolic cosine function @fnindex COSH @fnindex DCOSH @cindex hyperbolic cosine @cindex hyperbolic function, cosine @cindex cosine, hyperbolic @table @asis @item @emph{Description}: @code{COSH(X)} computes the hyperbolic cosine of @var{X}. @item @emph{Standard}: Fortran 77 and later, for a complex argument Fortran 2008 or later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{X = COSH(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value has same type and kind as @var{X}. If @var{X} is complex, the imaginary part of the result is in radians. If @var{X} is @code{REAL}, the return value has a lower bound of one, @math{\cosh (x) \geq 1}. @item @emph{Example}: @smallexample program test_cosh real(8) :: x = 1.0_8 x = cosh(x) end program test_cosh @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @item @emph{See also}: Inverse function: @ref{ACOSH} @end table @node COUNT @section @code{COUNT} --- Count function @fnindex COUNT @cindex array, conditionally count elements @cindex array, element counting @cindex array, number of elements @table @asis @item @emph{Description}: Counts the number of @code{.TRUE.} elements in a logical @var{MASK}, or, if the @var{DIM} argument is supplied, counts the number of elements along each row of the array in the @var{DIM} direction. If the array has zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then the result is @code{0}. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = COUNT(MASK [, DIM, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{MASK} @tab The type shall be @code{LOGICAL}. @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. If @var{DIM} is present, the result is an array with a rank one less than the rank of @var{ARRAY}, and a size corresponding to the shape of @var{ARRAY} with the @var{DIM} dimension removed. @item @emph{Example}: @smallexample program test_count integer, dimension(2,3) :: a, b logical, dimension(2,3) :: mask a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /)) b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /)) print '(3i3)', a(1,:) print '(3i3)', a(2,:) print * print '(3i3)', b(1,:) print '(3i3)', b(2,:) print * mask = a.ne.b print '(3l3)', mask(1,:) print '(3l3)', mask(2,:) print * print '(3i3)', count(mask) print * print '(3i3)', count(mask, 1) print * print '(3i3)', count(mask, 2) end program test_count @end smallexample @end table @node CPU_TIME @section @code{CPU_TIME} --- CPU elapsed time in seconds @fnindex CPU_TIME @cindex time, elapsed @table @asis @item @emph{Description}: Returns a @code{REAL} value representing the elapsed CPU time in seconds. This is useful for testing segments of code to determine execution time. If a time source is available, time will be reported with microsecond resolution. If no time source is available, @var{TIME} is set to @code{-1.0}. Note that @var{TIME} may contain a, system dependent, arbitrary offset and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute value is meaningless, only differences between subsequent calls to this subroutine, as shown in the example below, should be used. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL CPU_TIME(TIME)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}. @end multitable @item @emph{Return value}: None @item @emph{Example}: @smallexample program test_cpu_time real :: start, finish call cpu_time(start) ! put code to test here call cpu_time(finish) print '("Time = ",f6.3," seconds.")',finish-start end program test_cpu_time @end smallexample @item @emph{See also}: @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME} @end table @node CSHIFT @section @code{CSHIFT} --- Circular shift elements of an array @fnindex CSHIFT @cindex array, shift circularly @cindex array, permutation @cindex array, rotate @table @asis @item @emph{Description}: @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, then all complete rank one sections of @var{ARRAY} along the given dimension are shifted. Elements shifted out one end of each rank one section are shifted back in the other end. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of any type. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @item @var{DIM} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: Returns an array of same type and rank as the @var{ARRAY} argument. @item @emph{Example}: @smallexample program test_cshift integer, dimension(3,3) :: a a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) print '(3i3)', a(1,:) print '(3i3)', a(2,:) print '(3i3)', a(3,:) a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2) print * print '(3i3)', a(1,:) print '(3i3)', a(2,:) print '(3i3)', a(3,:) end program test_cshift @end smallexample @end table @node CTIME @section @code{CTIME} --- Convert a time into a string @fnindex CTIME @cindex time, conversion to string @cindex conversion, to string @table @asis @item @emph{Description}: @code{CTIME} converts a system time value, such as returned by @code{TIME8}, to a string. The output will be of the form @samp{Sat Aug 19 18:13:14 1995}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL CTIME(TIME, RESULT)}. @item @code{RESULT = CTIME(TIME)}. @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{TIME} @tab The type shall be of type @code{INTEGER}. @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and of default kind. It is an @code{INTENT(OUT)} argument. If the length of this variable is too short for the time and date string to fit completely, it will be blank on procedure return. @end multitable @item @emph{Return value}: The converted date and time as a string. @item @emph{Example}: @smallexample program test_ctime integer(8) :: i character(len=30) :: date i = time8() ! Do something, main part of the program call ctime(i,date) print *, 'Program was started on ', date end program test_ctime @end smallexample @item @emph{See Also}: @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} @end table @node DATE_AND_TIME @section @code{DATE_AND_TIME} --- Date and time subroutine @fnindex DATE_AND_TIME @cindex date, current @cindex current date @cindex time, current @cindex current time @table @asis @item @emph{Description}: @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and time information from the real-time system clock. @var{DATE} is @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm, representing the difference with respect to Coordinated Universal Time (UTC). Unavailable time and date parameters return blanks. @var{VALUES} is @code{INTENT(OUT)} and provides the following: @multitable @columnfractions .15 .30 .40 @item @tab @code{VALUE(1)}: @tab The year @item @tab @code{VALUE(2)}: @tab The month @item @tab @code{VALUE(3)}: @tab The day of the month @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes @item @tab @code{VALUE(5)}: @tab The hour of the day @item @tab @code{VALUE(6)}: @tab The minutes of the hour @item @tab @code{VALUE(7)}: @tab The seconds of the minute @item @tab @code{VALUE(8)}: @tab The milliseconds of the second @end multitable @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)} or larger, and of default kind. @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)} or larger, and of default kind. @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)} or larger, and of default kind. @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}. @end multitable @item @emph{Return value}: None @item @emph{Example}: @smallexample program test_time_and_date character(8) :: date character(10) :: time character(5) :: zone integer,dimension(8) :: values ! using keyword arguments call date_and_time(date,time,zone,values) call date_and_time(DATE=date,ZONE=zone) call date_and_time(TIME=time) call date_and_time(VALUES=values) print '(a,2x,a,2x,a)', date, time, zone print '(8i5)', values end program test_time_and_date @end smallexample @item @emph{See also}: @ref{CPU_TIME}, @ref{SYSTEM_CLOCK} @end table @node DBLE @section @code{DBLE} --- Double conversion function @fnindex DBLE @cindex conversion, to real @table @asis @item @emph{Description}: @code{DBLE(A)} Converts @var{A} to double precision real type. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = DBLE(A)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of type double precision real. @item @emph{Example}: @smallexample program test_dble real :: x = 2.18 integer :: i = 5 complex :: z = (2.3,1.14) print *, dble(x), dble(i), dble(z) end program test_dble @end smallexample @item @emph{See also}: @ref{REAL} @end table @node DCMPLX @section @code{DCMPLX} --- Double complex conversion function @fnindex DCMPLX @cindex complex numbers, conversion to @cindex conversion, to complex @table @asis @item @emph{Description}: @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is converted to the real component. If @var{Y} is present it is converted to the imaginary component. If @var{Y} is not present then the imaginary component is set to 0.0. If @var{X} is complex then @var{Y} must not be present. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = DCMPLX(X [, Y])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{COMPLEX(8)} @item @emph{Example}: @smallexample program test_dcmplx integer :: i = 42 real :: x = 3.14 complex :: z z = cmplx(i, x) print *, dcmplx(i) print *, dcmplx(x) print *, dcmplx(z) print *, dcmplx(x,i) end program test_dcmplx @end smallexample @end table @node DIGITS @section @code{DIGITS} --- Significant binary digits function @fnindex DIGITS @cindex model representation, significant digits @table @asis @item @emph{Description}: @code{DIGITS(X)} returns the number of significant binary digits of the internal model representation of @var{X}. For example, on a system using a 32-bit floating point representation, a default real number would likely return 24. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = DIGITS(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER}. @item @emph{Example}: @smallexample program test_digits integer :: i = 12345 real :: x = 3.143 real(8) :: y = 2.33 print *, digits(i) print *, digits(x) print *, digits(y) end program test_digits @end smallexample @end table @node DIM @section @code{DIM} --- Positive difference @fnindex DIM @fnindex IDIM @fnindex DDIM @cindex positive difference @table @asis @item @emph{Description}: @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive; otherwise returns zero. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = DIM(X, Y)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL} @item @var{Y} @tab The type shall be the same type and kind as @var{X}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} or @code{REAL}. @item @emph{Example}: @smallexample program test_dim integer :: i real(8) :: x i = dim(4, 15) x = dim(4.345_8, 2.111_8) print *, i print *, x end program test_dim @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @end table @node DOT_PRODUCT @section @code{DOT_PRODUCT} --- Dot product function @fnindex DOT_PRODUCT @cindex dot product @cindex vector product @cindex product, vector @table @asis @item @emph{Description}: @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be either numeric or logical and must be arrays of rank one and of equal size. If the vectors are @code{INTEGER} or @code{REAL}, the result is @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL}, the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1. @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. @end multitable @item @emph{Return value}: If the arguments are numeric, the return value is a scalar of numeric type, @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}. @item @emph{Example}: @smallexample program test_dot_prod integer, dimension(3) :: a, b a = (/ 1, 2, 3 /) b = (/ 4, 5, 6 /) print '(3i3)', a print * print '(3i3)', b print * print *, dot_product(a,b) end program test_dot_prod @end smallexample @end table @node DPROD @section @code{DPROD} --- Double product function @fnindex DPROD @cindex product, double-precision @table @asis @item @emph{Description}: @code{DPROD(X,Y)} returns the product @code{X*Y}. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = DPROD(X, Y)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @item @var{Y} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL(8)}. @item @emph{Example}: @smallexample program test_dprod real :: x = 5.2 real :: y = 2.3 real(8) :: d d = dprod(x,y) print *, d end program test_dprod @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @end table @node DREAL @section @code{DREAL} --- Double real part function @fnindex DREAL @cindex complex numbers, real part @table @asis @item @emph{Description}: @code{DREAL(Z)} returns the real part of complex variable @var{Z}. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = DREAL(A)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab The type shall be @code{COMPLEX(8)}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL(8)}. @item @emph{Example}: @smallexample program test_dreal complex(8) :: z = (1.3_8,7.2_8) print *, dreal(z) end program test_dreal @end smallexample @item @emph{See also}: @ref{AIMAG} @end table @node DSHIFTL @section @code{DSHIFTL} --- Combined left shift @fnindex DSHIFTL @cindex left shift, combined @cindex shift, left @table @asis @item @emph{Description}: @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT} bits of @var{J}, and the remaining bits are the rightmost bits of @var{I}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = DSHIFTL(I, J, SHIFT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. If both @var{I} and @var{J} have integer type, then they shall have the same kind type parameter. @var{I} and @var{J} shall not both be BOZ constants. @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. @end multitable @item @emph{Return value}: If either @var{I} or @var{J} is a BOZ constant, it is first converted as if by the intrinsic function @code{INT} to an integer type with the kind type parameter of the other. @item @emph{See also}: @ref{DSHIFTR} @end table @node DSHIFTR @section @code{DSHIFTR} --- Combined right shift @fnindex DSHIFTR @cindex right shift, combined @cindex shift, right @table @asis @item @emph{Description}: @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT} bits of @var{I}, and the remaining bits are the leftmost bits of @var{J}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = DSHIFTR(I, J, SHIFT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant. @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant. If both @var{I} and @var{J} have integer type, then they shall have the same kind type parameter. @var{I} and @var{J} shall not both be BOZ constants. @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(I)}; otherwise, @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}. @end multitable @item @emph{Return value}: If either @var{I} or @var{J} is a BOZ constant, it is first converted as if by the intrinsic function @code{INT} to an integer type with the kind type parameter of the other. @item @emph{See also}: @ref{DSHIFTL} @end table @node DTIME @section @code{DTIME} --- Execution time subroutine (or function) @fnindex DTIME @cindex time, elapsed @cindex elapsed time @table @asis @item @emph{Description}: @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime since the start of the process's execution in @var{TIME}. @var{VALUES} returns the user and system components of this time in @code{VALUES(1)} and @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. Subsequent invocations of @code{DTIME} return values accumulated since the previous invocation. On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wrap around) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program. Please note, that this implementation is thread safe if used within OpenMP directives, i.e., its state will be consistent while called from multiple threads. However, if @code{DTIME} is called from multiple threads, the result is still the time since the last invocation. This may not give the intended results. If possible, use @code{CPU_TIME} instead. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: @multitable @columnfractions .15 .30 .40 @item @tab @code{VALUES(1)}: @tab User time in seconds. @item @tab @code{VALUES(2)}: @tab System time in seconds. @item @tab @code{TIME}: @tab Run time since start in seconds. @end multitable @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL DTIME(VALUES, TIME)}. @item @code{TIME = DTIME(VALUES)}, (not recommended). @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. @item @var{TIME}@tab The type shall be @code{REAL(4)}. @end multitable @item @emph{Return value}: Elapsed time in seconds since the last invocation or since the start of program execution if not called before. @item @emph{Example}: @smallexample program test_dtime integer(8) :: i, j real, dimension(2) :: tarray real :: result call dtime(tarray, result) print *, result print *, tarray(1) print *, tarray(2) do i=1,100000000 ! Just a delay j = i * i - i end do call dtime(tarray, result) print *, result print *, tarray(1) print *, tarray(2) end program test_dtime @end smallexample @item @emph{See also}: @ref{CPU_TIME} @end table @node EOSHIFT @section @code{EOSHIFT} --- End-off shift elements of an array @fnindex EOSHIFT @cindex array, shift @table @asis @item @emph{Description}: @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one, then all complete rank one sections of @var{ARRAY} along the given dimension are shifted. Elements shifted out one end of each rank one section are dropped. If @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY} is copied back in the other end. If @var{BOUNDARY} is not present then the following are copied in depending on the type of @var{ARRAY}. @multitable @columnfractions .15 .80 @item @emph{Array Type} @tab @emph{Boundary Value} @item Numeric @tab 0 of the type and kind of @var{ARRAY}. @item Logical @tab @code{.FALSE.}. @item Character(@var{len}) @tab @var{len} blanks. @end multitable @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab May be any type, not scalar. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @item @var{BOUNDARY} @tab Same type as @var{ARRAY}. @item @var{DIM} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: Returns an array of same type and rank as the @var{ARRAY} argument. @item @emph{Example}: @smallexample program test_eoshift integer, dimension(3,3) :: a a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /)) print '(3i3)', a(1,:) print '(3i3)', a(2,:) print '(3i3)', a(3,:) a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2) print * print '(3i3)', a(1,:) print '(3i3)', a(2,:) print '(3i3)', a(3,:) end program test_eoshift @end smallexample @end table @node EPSILON @section @code{EPSILON} --- Epsilon function @fnindex EPSILON @cindex model representation, epsilon @table @asis @item @emph{Description}: @code{EPSILON(X)} returns the smallest number @var{E} of the same kind as @var{X} such that @math{1 + E > 1}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = EPSILON(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of same type as the argument. @item @emph{Example}: @smallexample program test_epsilon real :: x = 3.143 real(8) :: y = 2.33 print *, EPSILON(x) print *, EPSILON(y) end program test_epsilon @end smallexample @end table @node ERF @section @code{ERF} --- Error function @fnindex ERF @cindex error function @table @asis @item @emph{Description}: @code{ERF(X)} computes the error function of @var{X}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ERF(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL}, of the same kind as @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }. @item @emph{Example}: @smallexample program test_erf real(8) :: x = 0.17_8 x = erf(x) end program test_erf @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension @end multitable @end table @node ERFC @section @code{ERFC} --- Error function @fnindex ERFC @cindex error function, complementary @table @asis @item @emph{Description}: @code{ERFC(X)} computes the complementary error function of @var{X}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ERFC(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} and of the same kind as @var{X}. It lies in the range @math{ 0 \leq erfc (x) \leq 2 }. @item @emph{Example}: @smallexample program test_erfc real(8) :: x = 0.17_8 x = erfc(x) end program test_erfc @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension @end multitable @end table @node ERFC_SCALED @section @code{ERFC_SCALED} --- Error function @fnindex ERFC_SCALED @cindex error function, complementary, exponentially-scaled @table @asis @item @emph{Description}: @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary error function of @var{X}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ERFC_SCALED(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} and of the same kind as @var{X}. @item @emph{Example}: @smallexample program test_erfc_scaled real(8) :: x = 0.17_8 x = erfc_scaled(x) end program test_erfc_scaled @end smallexample @end table @node ETIME @section @code{ETIME} --- Execution time subroutine (or function) @fnindex ETIME @cindex time, elapsed @table @asis @item @emph{Description}: @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime since the start of the process's execution in @var{TIME}. @var{VALUES} returns the user and system components of this time in @code{VALUES(1)} and @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}. On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wrap around) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following: @multitable @columnfractions .15 .30 .60 @item @tab @code{VALUES(1)}: @tab User time in seconds. @item @tab @code{VALUES(2)}: @tab System time in seconds. @item @tab @code{TIME}: @tab Run time since start in seconds. @end multitable @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL ETIME(VALUES, TIME)}. @item @code{TIME = ETIME(VALUES)}, (not recommended). @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}. @item @var{TIME}@tab The type shall be @code{REAL(4)}. @end multitable @item @emph{Return value}: Elapsed time in seconds since the start of program execution. @item @emph{Example}: @smallexample program test_etime integer(8) :: i, j real, dimension(2) :: tarray real :: result call ETIME(tarray, result) print *, result print *, tarray(1) print *, tarray(2) do i=1,100000000 ! Just a delay j = i * i - i end do call ETIME(tarray, result) print *, result print *, tarray(1) print *, tarray(2) end program test_etime @end smallexample @item @emph{See also}: @ref{CPU_TIME} @end table @node EVENT_QUERY @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred @fnindex EVENT_QUERY @cindex Events, EVENT_QUERY @table @asis @item @emph{Description}: @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been posted to the @var{EVENT} variable and not yet been removed by calling @code{EVENT WAIT}. When @var{STAT} is present and the invokation was successful, it is assigned the value 0. If it is present and the invokation has failed, it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}. @item @emph{Standard}: TS 18508 or later @item @emph{Class}: subroutine @item @emph{Syntax}: @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE}, defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed. @item @var{COUNT} @tab (intent(out))Scalar integer with at least the precision of default integer. @item @var{STAT} @tab (optional) Scalar default-kind integer variable. @end multitable @item @emph{Example}: @smallexample program atomic use iso_fortran_env implicit none type(event_type) :: event_value_has_been_set[*] integer :: cnt if (this_image() == 1) then call event_query (event_value_has_been_set, cnt) if (cnt > 0) write(*,*) "Value has been set" elseif (this_image() == 2) then event post (event_value_has_been_set[1]) end if end program atomic @end smallexample @end table @node EXECUTE_COMMAND_LINE @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command @fnindex EXECUTE_COMMAND_LINE @cindex system, system call @cindex command line @table @asis @item @emph{Description}: @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or asynchronously. The @code{COMMAND} argument is passed to the shell and executed, using the C library's @code{system} call. (The shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present and has the value false, the execution of the command is asynchronous if the system supports it; otherwise, the command is executed synchronously. The three last arguments allow the user to get status information. After synchronous execution, @code{EXITSTAT} contains the integer exit code of the command, as returned by @code{system}. @code{CMDSTAT} is set to zero if the command line was executed (whatever its exit status was). @code{CMDMSG} is assigned an error message if an error has occurred. Note that the @code{system} function need not be thread-safe. It is the responsibility of the user to ensure that @code{system} is not called concurrently. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar. @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar. @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the default kind. @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the default kind. @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the default kind. @end multitable @item @emph{Example}: @smallexample program test_exec integer :: i call execute_command_line ("external_prog.exe", exitstat=i) print *, "Exit status of external_prog.exe was ", i call execute_command_line ("reindex_files.exe", wait=.false.) print *, "Now reindexing files in the background" end program test_exec @end smallexample @item @emph{Note}: Because this intrinsic is implemented in terms of the @code{system} function call, its behavior with respect to signaling is processor dependent. In particular, on POSIX-compliant systems, the SIGINT and SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As such, if the parent process is terminated, the child process might not be terminated alongside. @item @emph{See also}: @ref{SYSTEM} @end table @node EXIT @section @code{EXIT} --- Exit the program with status. @fnindex EXIT @cindex program termination @cindex terminate program @table @asis @item @emph{Description}: @code{EXIT} causes immediate termination of the program with status. If status is omitted it returns the canonical @emph{success} for the system. All Fortran I/O units are closed. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL EXIT([STATUS])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind. @end multitable @item @emph{Return value}: @code{STATUS} is passed to the parent process on exit. @item @emph{Example}: @smallexample program test_exit integer :: STATUS = 0 print *, 'This program is going to exit.' call EXIT(STATUS) end program test_exit @end smallexample @item @emph{See also}: @ref{ABORT}, @ref{KILL} @end table @node EXP @section @code{EXP} --- Exponential function @fnindex EXP @fnindex DEXP @fnindex CEXP @fnindex ZEXP @fnindex CDEXP @cindex exponential function @cindex logarithm function, inverse @table @asis @item @emph{Description}: @code{EXP(X)} computes the base @math{e} exponential of @var{X}. @item @emph{Standard}: Fortran 77 and later, has overloads that are GNU extensions @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = EXP(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value has same type and kind as @var{X}. @item @emph{Example}: @smallexample program test_exp real :: x = 1.0 x = exp(x) end program test_exp @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension @end multitable @end table @node EXPONENT @section @code{EXPONENT} --- Exponent function @fnindex EXPONENT @cindex real number, exponent @cindex floating point, exponent @table @asis @item @emph{Description}: @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X} is zero the value returned is zero. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = EXPONENT(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type default @code{INTEGER}. @item @emph{Example}: @smallexample program test_exponent real :: x = 1.0 integer :: i i = exponent(x) print *, i print *, exponent(0.0) end program test_exponent @end smallexample @end table @node EXTENDS_TYPE_OF @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension @fnindex EXTENDS_TYPE_OF @table @asis @item @emph{Description}: Query dynamic type for extension. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be an object of extensible declared type or unlimited polymorphic. @item @var{MOLD} @tab Shall be an object of extensible declared type or unlimited polymorphic. @end multitable @item @emph{Return value}: The return value is a scalar of type default logical. It is true if and only if the dynamic type of A is an extension type of the dynamic type of MOLD. @item @emph{See also}: @ref{SAME_TYPE_AS} @end table @node FDATE @section @code{FDATE} --- Get the current time as a string @fnindex FDATE @cindex time, current @cindex current time @cindex date, current @cindex current date @table @asis @item @emph{Description}: @code{FDATE(DATE)} returns the current date (using the same format as @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE, TIME())}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL FDATE(DATE)}. @item @code{DATE = FDATE()}. @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the default kind. It is an @code{INTENT(OUT)} argument. If the length of this variable is too short for the date and time string to fit completely, it will be blank on procedure return. @end multitable @item @emph{Return value}: The current date and time as a string. @item @emph{Example}: @smallexample program test_fdate integer(8) :: i, j character(len=30) :: date call fdate(date) print *, 'Program started on ', date do i = 1, 100000000 ! Just a delay j = i * i - i end do call fdate(date) print *, 'Program ended on ', date end program test_fdate @end smallexample @item @emph{See also}: @ref{DATE_AND_TIME}, @ref{CTIME} @end table @node FGET @section @code{FGET} --- Read a single character in stream mode from stdin @fnindex FGET @cindex read character, stream mode @cindex stream mode, read character @cindex file operation, read character @table @asis @item @emph{Description}: Read a single character in stream mode from stdin by bypassing normal formatted output. Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. Note that the @code{FGET} intrinsic is provided for backwards compatibility with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. Programmers should consider the use of new stream IO feature in new code for future portability. See also @ref{Fortran 2003 status}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL FGET(C [, STATUS])} @item @code{STATUS = FGET(C)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success, -1 on end-of-file, and a system specific positive error code otherwise. @end multitable @item @emph{Example}: @smallexample PROGRAM test_fget INTEGER, PARAMETER :: strlen = 100 INTEGER :: status, i = 1 CHARACTER(len=strlen) :: str = "" WRITE (*,*) 'Enter text:' DO CALL fget(str(i:i), status) if (status /= 0 .OR. i > strlen) exit i = i + 1 END DO WRITE (*,*) TRIM(str) END PROGRAM @end smallexample @item @emph{See also}: @ref{FGETC}, @ref{FPUT}, @ref{FPUTC} @end table @node FGETC @section @code{FGETC} --- Read a single character in stream mode @fnindex FGETC @cindex read character, stream mode @cindex stream mode, read character @cindex file operation, read character @table @asis @item @emph{Description}: Read a single character in stream mode by bypassing normal formatted output. Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. Note that the @code{FGET} intrinsic is provided for backwards compatibility with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. Programmers should consider the use of new stream IO feature in new code for future portability. See also @ref{Fortran 2003 status}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL FGETC(UNIT, C [, STATUS])} @item @code{STATUS = FGETC(UNIT, C)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab The type shall be @code{INTEGER}. @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success, -1 on end-of-file and a system specific positive error code otherwise. @end multitable @item @emph{Example}: @smallexample PROGRAM test_fgetc INTEGER :: fd = 42, status CHARACTER :: c OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD") DO CALL fgetc(fd, c, status) IF (status /= 0) EXIT call fput(c) END DO CLOSE(UNIT=fd) END PROGRAM @end smallexample @item @emph{See also}: @ref{FGET}, @ref{FPUT}, @ref{FPUTC} @end table @node FLOOR @section @code{FLOOR} --- Integer floor function @fnindex FLOOR @cindex floor @cindex rounding, floor @table @asis @item @emph{Description}: @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = FLOOR(A [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab The type shall be @code{REAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present and of default-kind @code{INTEGER} otherwise. @item @emph{Example}: @smallexample program test_floor real :: x = 63.29 real :: y = -63.59 print *, floor(x) ! returns 63 print *, floor(y) ! returns -64 end program test_floor @end smallexample @item @emph{See also}: @ref{CEILING}, @ref{NINT} @end table @node FLUSH @section @code{FLUSH} --- Flush I/O unit(s) @fnindex FLUSH @cindex file operation, flush @table @asis @item @emph{Description}: Flushes Fortran unit(s) currently open for output. Without the optional argument, all units are flushed, otherwise just the unit specified. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL FLUSH(UNIT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}. @end multitable @item @emph{Note}: Beginning with the Fortran 2003 standard, there is a @code{FLUSH} statement that should be preferred over the @code{FLUSH} intrinsic. The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement have identical effect: they flush the runtime library's I/O buffer so that the data becomes visible to other processes. This does not guarantee that the data is committed to disk. On POSIX systems, you can request that all data is transferred to the storage device by calling the @code{fsync} function, with the POSIX file descriptor of the I/O unit as argument (retrieved with GNU intrinsic @code{FNUM}). The following example shows how: @smallexample ! Declare the interface for POSIX fsync function interface function fsync (fd) bind(c,name="fsync") use iso_c_binding, only: c_int integer(c_int), value :: fd integer(c_int) :: fsync end function fsync end interface ! Variable declaration integer :: ret ! Opening unit 10 open (10,file="foo") ! ... ! Perform I/O on unit 10 ! ... ! Flush and sync flush(10) ret = fsync(fnum(10)) ! Handle possible error if (ret /= 0) stop "Error calling FSYNC" @end smallexample @end table @node FNUM @section @code{FNUM} --- File number function @fnindex FNUM @cindex file operation, file number @table @asis @item @emph{Description}: @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the open Fortran I/O unit @code{UNIT}. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = FNUM(UNIT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} @item @emph{Example}: @smallexample program test_fnum integer :: i open (unit=10, status = "scratch") i = fnum(10) print *, i close (10) end program test_fnum @end smallexample @end table @node FPUT @section @code{FPUT} --- Write a single character in stream mode to stdout @fnindex FPUT @cindex write character, stream mode @cindex stream mode, write character @cindex file operation, write character @table @asis @item @emph{Description}: Write a single character in stream mode to stdout by bypassing normal formatted output. Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. Note that the @code{FGET} intrinsic is provided for backwards compatibility with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. Programmers should consider the use of new stream IO feature in new code for future portability. See also @ref{Fortran 2003 status}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL FPUT(C [, STATUS])} @item @code{STATUS = FPUT(C)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success, -1 on end-of-file and a system specific positive error code otherwise. @end multitable @item @emph{Example}: @smallexample PROGRAM test_fput CHARACTER(len=10) :: str = "gfortran" INTEGER :: i DO i = 1, len_trim(str) CALL fput(str(i:i)) END DO END PROGRAM @end smallexample @item @emph{See also}: @ref{FPUTC}, @ref{FGET}, @ref{FGETC} @end table @node FPUTC @section @code{FPUTC} --- Write a single character in stream mode @fnindex FPUTC @cindex write character, stream mode @cindex stream mode, write character @cindex file operation, write character @table @asis @item @emph{Description}: Write a single character in stream mode by bypassing normal formatted output. Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. Note that the @code{FGET} intrinsic is provided for backwards compatibility with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility. Programmers should consider the use of new stream IO feature in new code for future portability. See also @ref{Fortran 2003 status}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL FPUTC(UNIT, C [, STATUS])} @item @code{STATUS = FPUTC(UNIT, C)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab The type shall be @code{INTEGER}. @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success, -1 on end-of-file and a system specific positive error code otherwise. @end multitable @item @emph{Example}: @smallexample PROGRAM test_fputc CHARACTER(len=10) :: str = "gfortran" INTEGER :: fd = 42, i OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW") DO i = 1, len_trim(str) CALL fputc(fd, str(i:i)) END DO CLOSE(fd) END PROGRAM @end smallexample @item @emph{See also}: @ref{FPUT}, @ref{FGET}, @ref{FGETC} @end table @node FRACTION @section @code{FRACTION} --- Fractional part of the model representation @fnindex FRACTION @cindex real number, fraction @cindex floating point, fraction @table @asis @item @emph{Description}: @code{FRACTION(X)} returns the fractional part of the model representation of @code{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{Y = FRACTION(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type of the argument shall be a @code{REAL}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as the argument. The fractional part of the model representation of @code{X} is returned; it is @code{X * RADIX(X)**(-EXPONENT(X))}. @item @emph{Example}: @smallexample program test_fraction real :: x x = 178.1387e-4 print *, fraction(x), x * radix(x)**(-exponent(x)) end program test_fraction @end smallexample @end table @node FREE @section @code{FREE} --- Frees memory @fnindex FREE @cindex pointer, cray @table @asis @item @emph{Description}: Frees memory previously allocated by @code{MALLOC}. The @code{FREE} intrinsic is an extension intended to be used with Cray pointers, and is provided in GNU Fortran to allow user to compile legacy code. For new code using Fortran 95 pointers, the memory de-allocation intrinsic is @code{DEALLOCATE}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL FREE(PTR)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the location of the memory that should be de-allocated. @end multitable @item @emph{Return value}: None @item @emph{Example}: See @code{MALLOC} for an example. @item @emph{See also}: @ref{MALLOC} @end table @node FSEEK @section @code{FSEEK} --- Low level file positioning subroutine @fnindex FSEEK @cindex file operation, seek @cindex file operation, position @table @asis @item @emph{Description}: Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET}, if set to 1, @var{OFFSET} is taken to be relative to the current position @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}. On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek fails silently. This intrinsic routine is not fully backwards compatible with @command{g77}. In @command{g77}, the @code{FSEEK} takes a statement label instead of a @var{STATUS} variable. If FSEEK is used in old code, change @smallexample CALL FSEEK(UNIT, OFFSET, WHENCE, *label) @end smallexample to @smallexample INTEGER :: status CALL FSEEK(UNIT, OFFSET, WHENCE, status) IF (status /= 0) GOTO label @end smallexample Please note that GNU Fortran provides the Fortran 2003 Stream facility. Programmers should consider the use of new stream IO feature in new code for future portability. See also @ref{Fortran 2003 status}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}. @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}. @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}. Its value shall be either 0, 1 or 2. @item @var{STATUS} @tab (Optional) shall be a scalar of type @code{INTEGER(4)}. @end multitable @item @emph{Example}: @smallexample PROGRAM test_fseek INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2 INTEGER :: fd, offset, ierr ierr = 0 offset = 5 fd = 10 OPEN(UNIT=fd, FILE="fseek.test") CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET print *, FTELL(fd), ierr CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end print *, FTELL(fd), ierr CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning print *, FTELL(fd), ierr CLOSE(UNIT=fd) END PROGRAM @end smallexample @item @emph{See also}: @ref{FTELL} @end table @node FSTAT @section @code{FSTAT} --- Get file status @fnindex FSTAT @cindex file system, file status @table @asis @item @emph{Description}: @code{FSTAT} is identical to @ref{STAT}, except that information about an already opened file is obtained. The elements in @code{VALUES} are the same as described by @ref{STAT}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])} @item @code{STATUS = FSTAT(UNIT, VALUES)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}. @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 on success and a system specific error code otherwise. @end multitable @item @emph{Example}: See @ref{STAT} for an example. @item @emph{See also}: To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT} @end table @node FTELL @section @code{FTELL} --- Current stream position @fnindex FTELL @cindex file operation, position @table @asis @item @emph{Description}: Retrieves the current position within an open file. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL FTELL(UNIT, OFFSET)} @item @code{OFFSET = FTELL(UNIT)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{OFFSET} @tab Shall of type @code{INTEGER}. @item @var{UNIT} @tab Shall of type @code{INTEGER}. @end multitable @item @emph{Return value}: In either syntax, @var{OFFSET} is set to the current offset of unit number @var{UNIT}, or to @math{-1} if the unit is not currently open. @item @emph{Example}: @smallexample PROGRAM test_ftell INTEGER :: i OPEN(10, FILE="temp.dat") CALL ftell(10,i) WRITE(*,*) i END PROGRAM @end smallexample @item @emph{See also}: @ref{FSEEK} @end table @node GAMMA @section @code{GAMMA} --- Gamma function @fnindex GAMMA @fnindex DGAMMA @cindex Gamma function @cindex Factorial function @table @asis @item @emph{Description}: @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive, integer values of @var{X} the Gamma function simplifies to the factorial function @math{\Gamma(x)=(x-1)!}. @tex $$ \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t $$ @end tex @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{X = GAMMA(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL} and neither zero nor a negative integer. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} of the same kind as @var{X}. @item @emph{Example}: @smallexample program test_gamma real :: x = 1.0 x = gamma(x) ! returns 1.0 end program test_gamma @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension @end multitable @item @emph{See also}: Logarithm of the Gamma function: @ref{LOG_GAMMA} @end table @node GERROR @section @code{GERROR} --- Get last system error message @fnindex GERROR @cindex system, error handling @table @asis @item @emph{Description}: Returns the system error message corresponding to the last system error. This resembles the functionality of @code{strerror(3)} in C. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL GERROR(RESULT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default @end multitable @item @emph{Example}: @smallexample PROGRAM test_gerror CHARACTER(len=100) :: msg CALL gerror(msg) WRITE(*,*) msg END PROGRAM @end smallexample @item @emph{See also}: @ref{IERRNO}, @ref{PERROR} @end table @node GETARG @section @code{GETARG} --- Get command line arguments @fnindex GETARG @cindex command-line arguments @cindex arguments, to program @table @asis @item @emph{Description}: Retrieve the @var{POS}-th argument that was passed on the command line when the containing program was invoked. This intrinsic routine is provided for backwards compatibility with GNU Fortran 77. In new code, programmers should consider the use of the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 standard. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL GETARG(POS, VALUE)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than the default integer kind; @math{@var{POS} \geq 0} @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. @item @var{VALUE} @tab Shall be of type @code{CHARACTER}. @end multitable @item @emph{Return value}: After @code{GETARG} returns, the @var{VALUE} argument holds the @var{POS}th command line argument. If @var{VALUE} can not hold the argument, it is truncated to fit the length of @var{VALUE}. If there are less than @var{POS} arguments specified at the command line, @var{VALUE} will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set to the name of the program (on systems that support this feature). @item @emph{Example}: @smallexample PROGRAM test_getarg INTEGER :: i CHARACTER(len=32) :: arg DO i = 1, iargc() CALL getarg(i, arg) WRITE (*,*) arg END DO END PROGRAM @end smallexample @item @emph{See also}: GNU Fortran 77 compatibility function: @ref{IARGC} Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} @end table @node GET_COMMAND @section @code{GET_COMMAND} --- Get the entire command line @fnindex GET_COMMAND @cindex command-line arguments @cindex arguments, to program @table @asis @item @emph{Description}: Retrieve the entire command line that was used to invoke the program. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and of default kind. @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of default kind. @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of default kind. @end multitable @item @emph{Return value}: If @var{COMMAND} is present, stores the entire command line that was used to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is assigned the length of the command line. If @var{STATUS} is present, it is assigned 0 upon success of the command, -1 if @var{COMMAND} is too short to store the command line, or a positive value in case of an error. @item @emph{Example}: @smallexample PROGRAM test_get_command CHARACTER(len=255) :: cmd CALL get_command(cmd) WRITE (*,*) TRIM(cmd) END PROGRAM @end smallexample @item @emph{See also}: @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} @end table @node GET_COMMAND_ARGUMENT @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments @fnindex GET_COMMAND_ARGUMENT @cindex command-line arguments @cindex arguments, to program @table @asis @item @emph{Description}: Retrieve the @var{NUMBER}-th argument that was passed on the command line when the containing program was invoked. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of default kind, @math{@var{NUMBER} \geq 0} @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} and of default kind. @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} and of default kind. @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} and of default kind. @end multitable @item @emph{Return value}: After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER} arguments specified at the command line, @var{VALUE} will be filled with blanks. If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on systems that support this feature). The @var{LENGTH} argument contains the length of the @var{NUMBER}-th command line argument. If the argument retrieval fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is zero. @item @emph{Example}: @smallexample PROGRAM test_get_command_argument INTEGER :: i CHARACTER(len=32) :: arg i = 0 DO CALL get_command_argument(i, arg) IF (LEN_TRIM(arg) == 0) EXIT WRITE (*,*) TRIM(arg) i = i+1 END DO END PROGRAM @end smallexample @item @emph{See also}: @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT} @end table @node GETCWD @section @code{GETCWD} --- Get current working directory @fnindex GETCWD @cindex system, working directory @table @asis @item @emph{Description}: Get current working directory. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL GETCWD(C [, STATUS])} @item @code{STATUS = GETCWD(C)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind. @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, a system specific and nonzero error code otherwise. @end multitable @item @emph{Example}: @smallexample PROGRAM test_getcwd CHARACTER(len=255) :: cwd CALL getcwd(cwd) WRITE(*,*) TRIM(cwd) END PROGRAM @end smallexample @item @emph{See also}: @ref{CHDIR} @end table @node GETENV @section @code{GETENV} --- Get an environmental variable @fnindex GETENV @cindex environment variable @table @asis @item @emph{Description}: Get the @var{VALUE} of the environmental variable @var{NAME}. This intrinsic routine is provided for backwards compatibility with GNU Fortran 77. In new code, programmers should consider the use of the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran 2003 standard. Note that @code{GETENV} need not be thread-safe. It is the responsibility of the user to ensure that the environment is not being updated concurrently with a call to the @code{GETENV} intrinsic. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL GETENV(NAME, VALUE)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind. @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind. @end multitable @item @emph{Return value}: Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is not large enough to hold the data, it is truncated. If @var{NAME} is not set, @var{VALUE} will be filled with blanks. @item @emph{Example}: @smallexample PROGRAM test_getenv CHARACTER(len=255) :: homedir CALL getenv("HOME", homedir) WRITE (*,*) TRIM(homedir) END PROGRAM @end smallexample @item @emph{See also}: @ref{GET_ENVIRONMENT_VARIABLE} @end table @node GET_ENVIRONMENT_VARIABLE @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable @fnindex GET_ENVIRONMENT_VARIABLE @cindex environment variable @table @asis @item @emph{Description}: Get the @var{VALUE} of the environmental variable @var{NAME}. Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It is the responsibility of the user to ensure that the environment is not being updated concurrently with a call to the @code{GET_ENVIRONMENT_VARIABLE} intrinsic. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER} and of default kind. @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER} and of default kind. @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER} and of default kind. @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER} and of default kind. @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL} and of default kind. @end multitable @item @emph{Return value}: Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is not large enough to hold the data, it is truncated. If @var{NAME} is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH} contains the length needed for storing the environment variable @var{NAME} or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present but too short for the environment variable; it is 1 if the environment variable does not exist and 2 if the processor does not support environment variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is present with the value @code{.FALSE.}, the trailing blanks in @var{NAME} are significant; otherwise they are not part of the environment variable name. @item @emph{Example}: @smallexample PROGRAM test_getenv CHARACTER(len=255) :: homedir CALL get_environment_variable("HOME", homedir) WRITE (*,*) TRIM(homedir) END PROGRAM @end smallexample @end table @node GETGID @section @code{GETGID} --- Group ID function @fnindex GETGID @cindex system, group ID @table @asis @item @emph{Description}: Returns the numerical group ID of the current process. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = GETGID()} @item @emph{Return value}: The return value of @code{GETGID} is an @code{INTEGER} of the default kind. @item @emph{Example}: See @code{GETPID} for an example. @item @emph{See also}: @ref{GETPID}, @ref{GETUID} @end table @node GETLOG @section @code{GETLOG} --- Get login name @fnindex GETLOG @cindex system, login name @cindex login name @table @asis @item @emph{Description}: Gets the username under which the program is running. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL GETLOG(C)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind. @end multitable @item @emph{Return value}: Stores the current user name in @var{LOGIN}. (On systems where POSIX functions @code{geteuid} and @code{getpwuid} are not available, and the @code{getlogin} function is not implemented either, this will return a blank string.) @item @emph{Example}: @smallexample PROGRAM TEST_GETLOG CHARACTER(32) :: login CALL GETLOG(login) WRITE(*,*) login END PROGRAM @end smallexample @item @emph{See also}: @ref{GETUID} @end table @node GETPID @section @code{GETPID} --- Process ID function @fnindex GETPID @cindex system, process ID @cindex process ID @table @asis @item @emph{Description}: Returns the numerical process identifier of the current process. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = GETPID()} @item @emph{Return value}: The return value of @code{GETPID} is an @code{INTEGER} of the default kind. @item @emph{Example}: @smallexample program info print *, "The current process ID is ", getpid() print *, "Your numerical user ID is ", getuid() print *, "Your numerical group ID is ", getgid() end program info @end smallexample @item @emph{See also}: @ref{GETGID}, @ref{GETUID} @end table @node GETUID @section @code{GETUID} --- User ID function @fnindex GETUID @cindex system, user ID @cindex user id @table @asis @item @emph{Description}: Returns the numerical user ID of the current process. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = GETUID()} @item @emph{Return value}: The return value of @code{GETUID} is an @code{INTEGER} of the default kind. @item @emph{Example}: See @code{GETPID} for an example. @item @emph{See also}: @ref{GETPID}, @ref{GETLOG} @end table @node GMTIME @section @code{GMTIME} --- Convert time to GMT info @fnindex GMTIME @cindex time, conversion to GMT info @table @asis @item @emph{Description}: Given a system time value @var{TIME} (as provided by the @code{TIME8} intrinsic), fills @var{VALUES} with values extracted from it appropriate to the UTC time zone (Universal Coordinated Time, also known in some countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL GMTIME(TIME, VALUES)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{TIME} @tab An @code{INTEGER} scalar expression corresponding to a system time, with @code{INTENT(IN)}. @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, with @code{INTENT(OUT)}. @end multitable @item @emph{Return value}: The elements of @var{VALUES} are assigned as follows: @enumerate @item Seconds after the minute, range 0--59 or 0--61 to allow for leap seconds @item Minutes after the hour, range 0--59 @item Hours past midnight, range 0--23 @item Day of month, range 0--31 @item Number of months since January, range 0--12 @item Years since 1900 @item Number of days since Sunday, range 0--6 @item Days since January 1 @item Daylight savings indicator: positive if daylight savings is in effect, zero if not, and negative if the information is not available. @end enumerate @item @emph{See also}: @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8} @end table @node HOSTNM @section @code{HOSTNM} --- Get system host name @fnindex HOSTNM @cindex system, host name @table @asis @item @emph{Description}: Retrieves the host name of the system on which the program is running. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL HOSTNM(C [, STATUS])} @item @code{STATUS = HOSTNM(NAME)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind. @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success, or a system specific error code otherwise. @end multitable @item @emph{Return value}: In either syntax, @var{NAME} is set to the current hostname if it can be obtained, or to a blank string otherwise. @end table @node HUGE @section @code{HUGE} --- Largest number of a kind @fnindex HUGE @cindex limits, largest number @cindex model representation, largest number @table @asis @item @emph{Description}: @code{HUGE(X)} returns the largest number that is not an infinity in the model of the type of @code{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = HUGE(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X} @item @emph{Example}: @smallexample program test_huge_tiny print *, huge(0), huge(0.0), huge(0.0d0) print *, tiny(0.0), tiny(0.0d0) end program test_huge_tiny @end smallexample @end table @node HYPOT @section @code{HYPOT} --- Euclidean distance function @fnindex HYPOT @cindex Euclidean distance @table @asis @item @emph{Description}: @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = HYPOT(X, Y)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}. @end multitable @item @emph{Return value}: The return value has the same type and kind type parameter as @var{X}. @item @emph{Example}: @smallexample program test_hypot real(4) :: x = 1.e0_4, y = 0.5e0_4 x = hypot(x,y) end program test_hypot @end smallexample @end table @node IACHAR @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence @fnindex IACHAR @cindex @acronym{ASCII} collating sequence @cindex collating sequence, @acronym{ASCII} @cindex conversion, to integer @table @asis @item @emph{Description}: @code{IACHAR(C)} returns the code for the @acronym{ASCII} character in the first character position of @code{C}. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IACHAR(C [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. @item @emph{Example}: @smallexample program test_iachar integer i i = iachar(' ') end program test_iachar @end smallexample @item @emph{Note}: See @ref{ICHAR} for a discussion of converting between numerical values and formatted string representations. @item @emph{See also}: @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR} @end table @node IALL @section @code{IALL} --- Bitwise AND of array elements @fnindex IALL @cindex array, AND @cindex bits, AND of array elements @table @asis @item @emph{Description}: Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = IALL(ARRAY[, MASK])} @item @code{RESULT = IALL(ARRAY, DIM[, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} with a value in the range from 1 to n, where n equals the rank of @var{ARRAY}. @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} and either be a scalar or an array of the same shape as @var{ARRAY}. @end multitable @item @emph{Return value}: The result is of the same type as @var{ARRAY}. If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped is returned. @item @emph{Example}: @smallexample PROGRAM test_iall INTEGER(1) :: a(2) a(1) = b'00100100' a(2) = b'01101010' ! prints 00100000 PRINT '(b8.8)', IALL(a) END PROGRAM @end smallexample @item @emph{See also}: @ref{IANY}, @ref{IPARITY}, @ref{IAND} @end table @node IAND @section @code{IAND} --- Bitwise logical and @fnindex IAND @cindex bitwise logical and @cindex logical and, bitwise @table @asis @item @emph{Description}: Bitwise logical @code{AND}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IAND(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{J} @tab The type shall be @code{INTEGER}, of the same kind as @var{I}. (As a GNU extension, different kinds are also permitted.) @end multitable @item @emph{Return value}: The return type is @code{INTEGER}, of the same kind as the arguments. (If the argument kinds differ, it is of the same kind as the larger argument.) @item @emph{Example}: @smallexample PROGRAM test_iand INTEGER :: a, b DATA a / Z'F' /, b / Z'3' / WRITE (*,*) IAND(a, b) END PROGRAM @end smallexample @item @emph{See also}: @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} @end table @node IANY @section @code{IANY} --- Bitwise OR of array elements @fnindex IANY @cindex array, OR @cindex bits, OR of array elements @table @asis @item @emph{Description}: Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = IANY(ARRAY[, MASK])} @item @code{RESULT = IANY(ARRAY, DIM[, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} with a value in the range from 1 to n, where n equals the rank of @var{ARRAY}. @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} and either be a scalar or an array of the same shape as @var{ARRAY}. @end multitable @item @emph{Return value}: The result is of the same type as @var{ARRAY}. If @var{DIM} is absent, a scalar with the bitwise OR of all elements in @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped is returned. @item @emph{Example}: @smallexample PROGRAM test_iany INTEGER(1) :: a(2) a(1) = b'00100100' a(2) = b'01101010' ! prints 01101110 PRINT '(b8.8)', IANY(a) END PROGRAM @end smallexample @item @emph{See also}: @ref{IPARITY}, @ref{IALL}, @ref{IOR} @end table @node IARGC @section @code{IARGC} --- Get the number of command line arguments @fnindex IARGC @cindex command-line arguments @cindex command-line arguments, number of @cindex arguments, to program @table @asis @item @emph{Description}: @code{IARGC} returns the number of arguments passed on the command line when the containing program was invoked. This intrinsic routine is provided for backwards compatibility with GNU Fortran 77. In new code, programmers should consider the use of the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 standard. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = IARGC()} @item @emph{Arguments}: None. @item @emph{Return value}: The number of command line arguments, type @code{INTEGER(4)}. @item @emph{Example}: See @ref{GETARG} @item @emph{See also}: GNU Fortran 77 compatibility subroutine: @ref{GETARG} Fortran 2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT} @end table @node IBCLR @section @code{IBCLR} --- Clear bit @fnindex IBCLR @cindex bits, unset @cindex bits, clear @table @asis @item @emph{Description}: @code{IBCLR} returns the value of @var{I} with the bit at position @var{POS} set to zero. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IBCLR(I, POS)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{POS} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} @end table @node IBITS @section @code{IBITS} --- Bit extraction @fnindex IBITS @cindex bits, get @cindex bits, extract @table @asis @item @emph{Description}: @code{IBITS} extracts a field of length @var{LEN} from @var{I}, starting from bit position @var{POS} and extending left for @var{LEN} bits. The result is right-justified and the remaining bits are zeroed. The value of @code{POS+LEN} must be less than or equal to the value @code{BIT_SIZE(I)}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IBITS(I, POS, LEN)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{POS} @tab The type shall be @code{INTEGER}. @item @var{LEN} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR} @end table @node IBSET @section @code{IBSET} --- Set bit @fnindex IBSET @cindex bits, set @table @asis @item @emph{Description}: @code{IBSET} returns the value of @var{I} with the bit at position @var{POS} set to one. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IBSET(I, POS)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{POS} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS} @end table @node ICHAR @section @code{ICHAR} --- Character-to-integer conversion function @fnindex ICHAR @cindex conversion, to integer @table @asis @item @emph{Description}: @code{ICHAR(C)} returns the code for the character in the first character position of @code{C} in the system's native character set. The correspondence between characters and their codes is not necessarily the same across different GNU Fortran implementations. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ICHAR(C [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. @item @emph{Example}: @smallexample program test_ichar integer i i = ichar(' ') end program test_ichar @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later @end multitable @item @emph{Note}: No intrinsic exists to convert between a numeric value and a formatted character string representation -- for instance, given the @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or @code{REAL} value with the value 154, or vice versa. Instead, this functionality is provided by internal-file I/O, as in the following example: @smallexample program read_val integer value character(len=10) string, string2 string = '154' ! Convert a string to a numeric value read (string,'(I10)') value print *, value ! Convert a value to a formatted string write (string2,'(I10)') value print *, string2 end program read_val @end smallexample @item @emph{See also}: @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR} @end table @node IDATE @section @code{IDATE} --- Get current local time subroutine (day/month/year) @fnindex IDATE @cindex date, current @cindex current date @table @asis @item @emph{Description}: @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the current local time. The day (in the range 1-31), month (in the range 1-12), and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively. The year has four significant digits. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL IDATE(VALUES)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and the kind shall be the default integer kind. @end multitable @item @emph{Return value}: Does not return anything. @item @emph{Example}: @smallexample program test_idate integer, dimension(3) :: tarray call idate(tarray) print *, tarray(1) print *, tarray(2) print *, tarray(3) end program test_idate @end smallexample @end table @node IEOR @section @code{IEOR} --- Bitwise logical exclusive or @fnindex IEOR @cindex bitwise logical exclusive or @cindex logical exclusive or, bitwise @table @asis @item @emph{Description}: @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and @var{J}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IEOR(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{J} @tab The type shall be @code{INTEGER}, of the same kind as @var{I}. (As a GNU extension, different kinds are also permitted.) @end multitable @item @emph{Return value}: The return type is @code{INTEGER}, of the same kind as the arguments. (If the argument kinds differ, it is of the same kind as the larger argument.) @item @emph{See also}: @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} @end table @node IERRNO @section @code{IERRNO} --- Get the last system error number @fnindex IERRNO @cindex system, error handling @table @asis @item @emph{Description}: Returns the last system error number, as given by the C @code{errno} variable. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = IERRNO()} @item @emph{Arguments}: None. @item @emph{Return value}: The return value is of type @code{INTEGER} and of the default integer kind. @item @emph{See also}: @ref{PERROR} @end table @node IMAGE_INDEX @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index @fnindex IMAGE_INDEX @cindex coarray, @code{IMAGE_INDEX} @cindex images, cosubscript to image index conversion @table @asis @item @emph{Description}: Returns the image index belonging to a cosubscript. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Inquiry function. @item @emph{Syntax}: @code{RESULT = IMAGE_INDEX(COARRAY, SUB)} @item @emph{Arguments}: None. @multitable @columnfractions .15 .70 @item @var{COARRAY} @tab Coarray of any type. @item @var{SUB} @tab default integer rank-1 array of a size equal to the corank of @var{COARRAY}. @end multitable @item @emph{Return value}: Scalar default integer with the value of the image index which corresponds to the cosubscripts. For invalid cosubscripts the result is zero. @item @emph{Example}: @smallexample INTEGER :: array[2,-1:4,8,*] ! Writes 28 (or 0 if there are fewer than 28 images) WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1]) @end smallexample @item @emph{See also}: @ref{THIS_IMAGE}, @ref{NUM_IMAGES} @end table @node INDEX intrinsic @section @code{INDEX} --- Position of a substring within a string @fnindex INDEX @cindex substring position @cindex string, find substring @table @asis @item @emph{Description}: Returns the position of the start of the first occurrence of string @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If the @var{BACK} argument is present and true, the return value is the start of the last occurrence rather than the first. @item @emph{Standard}: Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)} @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with @code{INTENT(IN)} @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{SCAN}, @ref{VERIFY} @end table @node INT @section @code{INT} --- Convert to integer type @fnindex INT @fnindex IFIX @fnindex IDINT @cindex conversion, to integer @table @asis @item @emph{Description}: Convert to integer type @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = INT(A [, KIND))} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be of type @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: These functions return a @code{INTEGER} variable or array under the following rules: @table @asis @item (A) If @var{A} is of type @code{INTEGER}, @code{INT(A) = A} @item (B) If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer whose magnitude is the largest integer that does not exceed the magnitude of @var{A} and whose sign is the same as the sign of @var{A}. @item (C) If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}. @end table @item @emph{Example}: @smallexample program test_int integer :: i = 42 complex :: z = (-3.7, 1.0) print *, int(i) print *, int(z), int(z,8) end program @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later @end multitable @end table @node INT2 @section @code{INT2} --- Convert to 16-bit integer type @fnindex INT2 @fnindex SHORT @cindex conversion, to integer @table @asis @item @emph{Description}: Convert to a @code{KIND=2} integer type. This is equivalent to the standard @code{INT} intrinsic with an optional argument of @code{KIND=2}, and is only included for backwards compatibility. The @code{SHORT} intrinsic is equivalent to @code{INT2}. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = INT2(A)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be of type @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is a @code{INTEGER(2)} variable. @item @emph{See also}: @ref{INT}, @ref{INT8}, @ref{LONG} @end table @node INT8 @section @code{INT8} --- Convert to 64-bit integer type @fnindex INT8 @cindex conversion, to integer @table @asis @item @emph{Description}: Convert to a @code{KIND=8} integer type. This is equivalent to the standard @code{INT} intrinsic with an optional argument of @code{KIND=8}, and is only included for backwards compatibility. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = INT8(A)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be of type @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is a @code{INTEGER(8)} variable. @item @emph{See also}: @ref{INT}, @ref{INT2}, @ref{LONG} @end table @node IOR @section @code{IOR} --- Bitwise logical or @fnindex IOR @cindex bitwise logical or @cindex logical or, bitwise @table @asis @item @emph{Description}: @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and @var{J}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IOR(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{J} @tab The type shall be @code{INTEGER}, of the same kind as @var{I}. (As a GNU extension, different kinds are also permitted.) @end multitable @item @emph{Return value}: The return type is @code{INTEGER}, of the same kind as the arguments. (If the argument kinds differ, it is of the same kind as the larger argument.) @item @emph{See also}: @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT} @end table @node IPARITY @section @code{IPARITY} --- Bitwise XOR of array elements @fnindex IPARITY @cindex array, parity @cindex array, XOR @cindex bits, XOR of array elements @table @asis @item @emph{Description}: Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = IPARITY(ARRAY[, MASK])} @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} with a value in the range from 1 to n, where n equals the rank of @var{ARRAY}. @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} and either be a scalar or an array of the same shape as @var{ARRAY}. @end multitable @item @emph{Return value}: The result is of the same type as @var{ARRAY}. If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped is returned. @item @emph{Example}: @smallexample PROGRAM test_iparity INTEGER(1) :: a(2) a(1) = b'00100100' a(2) = b'01101010' ! prints 01001110 PRINT '(b8.8)', IPARITY(a) END PROGRAM @end smallexample @item @emph{See also}: @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY} @end table @node IRAND @section @code{IRAND} --- Integer pseudo-random number @fnindex IRAND @cindex random number generation @table @asis @item @emph{Description}: @code{IRAND(FLAG)} returns a pseudo-random number from a uniform distribution between 0 and a system-dependent limit (which is in most cases 2147483647). If @var{FLAG} is 0, the next number in the current sequence is returned; if @var{FLAG} is 1, the generator is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, it is used as a new seed with @code{SRAND}. This intrinsic routine is provided for backwards compatibility with GNU Fortran 77. It implements a simple modulo generator as provided by @command{g77}. For new code, one should consider the use of @ref{RANDOM_NUMBER} as it implements a superior algorithm. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = IRAND(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. @end multitable @item @emph{Return value}: The return value is of @code{INTEGER(kind=4)} type. @item @emph{Example}: @smallexample program test_irand integer,parameter :: seed = 86456 call srand(seed) print *, irand(), irand(), irand(), irand() print *, irand(seed), irand(), irand(), irand() end program test_irand @end smallexample @end table @node IS_IOSTAT_END @section @code{IS_IOSTAT_END} --- Test for end-of-file value @fnindex IS_IOSTAT_END @cindex @code{IOSTAT}, end of file @table @asis @item @emph{Description}: @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O status ``end of file''. The function is equivalent to comparing the variable with the @code{IOSTAT_END} parameter of the intrinsic module @code{ISO_FORTRAN_ENV}. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IS_IOSTAT_END(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of the type @code{INTEGER}. @end multitable @item @emph{Return value}: Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if @var{I} has the value which indicates an end of file condition for @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. @item @emph{Example}: @smallexample PROGRAM iostat IMPLICIT NONE INTEGER :: stat, i OPEN(88, FILE='test.dat') READ(88, *, IOSTAT=stat) i IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE' END PROGRAM @end smallexample @end table @node IS_IOSTAT_EOR @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value @fnindex IS_IOSTAT_EOR @cindex @code{IOSTAT}, end of record @table @asis @item @emph{Description}: @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O status ``end of record''. The function is equivalent to comparing the variable with the @code{IOSTAT_EOR} parameter of the intrinsic module @code{ISO_FORTRAN_ENV}. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = IS_IOSTAT_EOR(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of the type @code{INTEGER}. @end multitable @item @emph{Return value}: Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if @var{I} has the value which indicates an end of file condition for @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise. @item @emph{Example}: @smallexample PROGRAM iostat IMPLICIT NONE INTEGER :: stat, i(50) OPEN(88, FILE='test.dat', FORM='UNFORMATTED') READ(88, IOSTAT=stat) i IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD' END PROGRAM @end smallexample @end table @node ISATTY @section @code{ISATTY} --- Whether a unit is a terminal device. @fnindex ISATTY @cindex system, terminal @table @asis @item @emph{Description}: Determine whether a unit is connected to a terminal device. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = ISATTY(UNIT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. @end multitable @item @emph{Return value}: Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal device, @code{.FALSE.} otherwise. @item @emph{Example}: @smallexample PROGRAM test_isatty INTEGER(kind=1) :: unit DO unit = 1, 10 write(*,*) isatty(unit=unit) END DO END PROGRAM @end smallexample @item @emph{See also}: @ref{TTYNAM} @end table @node ISHFT @section @code{ISHFT} --- Shift bits @fnindex ISHFT @cindex bits, shift @table @asis @item @emph{Description}: @code{ISHFT} returns a value corresponding to @var{I} with all of the bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than zero corresponds to a left shift, a value of zero corresponds to no shift, and a value less than zero corresponds to a right shift. If the absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. Bits shifted out from the left end or right end are lost; zeros are shifted in from the opposite end. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ISHFT(I, SHIFT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{ISHFTC} @end table @node ISHFTC @section @code{ISHFTC} --- Shift bits circularly @fnindex ISHFTC @cindex bits, shift circular @table @asis @item @emph{Description}: @code{ISHFTC} returns a value corresponding to @var{I} with the rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that is, bits shifted out one end are shifted into the opposite end. A value of @var{SHIFT} greater than zero corresponds to a left shift, a value of zero corresponds to no shift, and a value less than zero corresponds to a right shift. The absolute value of @var{SHIFT} must be less than @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be equivalent to @code{BIT_SIZE(I)}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = ISHFTC(I, SHIFT [, SIZE])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER}; the value must be greater than zero and less than or equal to @code{BIT_SIZE(I)}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{ISHFT} @end table @node ISNAN @section @code{ISNAN} --- Test for a NaN @fnindex ISNAN @cindex IEEE, ISNAN @table @asis @item @emph{Description}: @code{ISNAN} tests whether a floating-point value is an IEEE Not-a-Number (NaN). @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{ISNAN(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Variable of the type @code{REAL}. @end multitable @item @emph{Return value}: Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE} if @var{X} is a NaN and @code{FALSE} otherwise. @item @emph{Example}: @smallexample program test_nan implicit none real :: x x = -1.0 x = sqrt(x) if (isnan(x)) stop '"x" is a NaN' end program test_nan @end smallexample @end table @node ITIME @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) @fnindex ITIME @cindex time, current @cindex current time @table @asis @item @emph{Description}: @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the current local time. The hour (in the range 1-24), minute (in the range 1-60), and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES}, respectively. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL ITIME(VALUES)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and the kind shall be the default integer kind. @end multitable @item @emph{Return value}: Does not return anything. @item @emph{Example}: @smallexample program test_itime integer, dimension(3) :: tarray call itime(tarray) print *, tarray(1) print *, tarray(2) print *, tarray(3) end program test_itime @end smallexample @end table @node KILL @section @code{KILL} --- Send a signal to a process @fnindex KILL @table @asis @item @emph{Description}: @item @emph{Standard}: Sends the signal specified by @var{SIGNAL} to the process @var{PID}. See @code{kill(2)}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL KILL(C, VALUE [, STATUS])} @item @code{STATUS = KILL(C, VALUE)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with @code{INTENT(IN)} @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with @code{INTENT(IN)} @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code otherwise. @end multitable @item @emph{See also}: @ref{ABORT}, @ref{EXIT} @end table @node KIND @section @code{KIND} --- Kind of an entity @fnindex KIND @cindex kind @table @asis @item @emph{Description}: @code{KIND(X)} returns the kind value of the entity @var{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{K = KIND(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER}, @code{REAL}, @code{COMPLEX} or @code{CHARACTER}. @end multitable @item @emph{Return value}: The return value is a scalar of type @code{INTEGER} and of the default integer kind. @item @emph{Example}: @smallexample program test_kind integer,parameter :: kc = kind(' ') integer,parameter :: kl = kind(.true.) print *, "The default character kind is ", kc print *, "The default logical kind is ", kl end program test_kind @end smallexample @end table @node LBOUND @section @code{LBOUND} --- Lower dimension bounds of an array @fnindex LBOUND @cindex array, lower bound @table @asis @item @emph{Description}: Returns the lower bounds of an array, or a single lower bound along the @var{DIM} dimension. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array, of any type. @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. If @var{DIM} is absent, the result is an array of the lower bounds of @var{ARRAY}. If @var{DIM} is present, the result is a scalar corresponding to the lower bound of the array along that dimension. If @var{ARRAY} is an expression rather than a whole array or array structure component, or if it has a zero extent along the relevant dimension, the lower bound is taken to be 1. @item @emph{See also}: @ref{UBOUND}, @ref{LCOBOUND} @end table @node LCOBOUND @section @code{LCOBOUND} --- Lower codimension bounds of an array @fnindex LCOBOUND @cindex coarray, lower bound @table @asis @item @emph{Description}: Returns the lower bounds of a coarray, or a single lower cobound along the @var{DIM} codimension. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an coarray, of any type. @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. If @var{DIM} is absent, the result is an array of the lower cobounds of @var{COARRAY}. If @var{DIM} is present, the result is a scalar corresponding to the lower cobound of the array along that codimension. @item @emph{See also}: @ref{UCOBOUND}, @ref{LBOUND} @end table @node LEADZ @section @code{LEADZ} --- Number of leading zero bits of an integer @fnindex LEADZ @cindex zero bits @table @asis @item @emph{Description}: @code{LEADZ} returns the number of leading zero bits of an integer. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LEADZ(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER}. @end multitable @item @emph{Return value}: The type of the return value is the default @code{INTEGER}. If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. @item @emph{Example}: @smallexample PROGRAM test_leadz WRITE (*,*) BIT_SIZE(1) ! prints 32 WRITE (*,*) LEADZ(1) ! prints 31 END PROGRAM @end smallexample @item @emph{See also}: @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR} @end table @node LEN @section @code{LEN} --- Length of a character entity @fnindex LEN @cindex string, length @table @asis @item @emph{Description}: Returns the length of a character string. If @var{STRING} is an array, the length of an element of @var{STRING} is returned. Note that @var{STRING} need not be defined when this intrinsic is invoked, since only the length, not the content, of @var{STRING} is needed. @item @emph{Standard}: Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{L = LEN(STRING [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab Shall be a scalar or array of type @code{CHARACTER}, with @code{INTENT(IN)} @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR} @end table @node LEN_TRIM @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters @fnindex LEN_TRIM @cindex string, length, without trailing whitespace @table @asis @item @emph{Description}: Returns the length of a character string, ignoring any trailing blanks. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LEN_TRIM(STRING [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, with @code{INTENT(IN)} @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. @item @emph{See also}: @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR} @end table @node LGE @section @code{LGE} --- Lexical greater than or equal @fnindex LGE @cindex lexical comparison of strings @cindex string, comparison @table @asis @item @emph{Description}: Determines whether one string is lexically greater than or equal to another string, where the two strings are interpreted as containing ASCII character codes. If the String A and String B are not the same length, the shorter is compared as if spaces were appended to it to form a value that has the same length as the longer. In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, @code{LLE}, and @code{LLT} differ from the corresponding intrinsic operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in that the latter use the processor's character ordering (which is not ASCII on some targets), whereas the former always use the ASCII ordering. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LGE(STRING_A, STRING_B)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. @end multitable @item @emph{Return value}: Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.} otherwise, based on the ASCII ordering. @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{LGT}, @ref{LLE}, @ref{LLT} @end table @node LGT @section @code{LGT} --- Lexical greater than @fnindex LGT @cindex lexical comparison of strings @cindex string, comparison @table @asis @item @emph{Description}: Determines whether one string is lexically greater than another string, where the two strings are interpreted as containing ASCII character codes. If the String A and String B are not the same length, the shorter is compared as if spaces were appended to it to form a value that has the same length as the longer. In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, @code{LLE}, and @code{LLT} differ from the corresponding intrinsic operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in that the latter use the processor's character ordering (which is not ASCII on some targets), whereas the former always use the ASCII ordering. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LGT(STRING_A, STRING_B)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. @end multitable @item @emph{Return value}: Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.} otherwise, based on the ASCII ordering. @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{LGE}, @ref{LLE}, @ref{LLT} @end table @node LINK @section @code{LINK} --- Create a hard link @fnindex LINK @cindex file system, create link @cindex file system, hard link @table @asis @item @emph{Description}: Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null character (@code{CHAR(0)}) can be used to mark the end of the names in @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file names are ignored. If the @var{STATUS} argument is supplied, it contains 0 on success or a nonzero error code upon return; see @code{link(2)}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])} @item @code{STATUS = LINK(PATH1, PATH2)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. @end multitable @item @emph{See also}: @ref{SYMLNK}, @ref{UNLINK} @end table @node LLE @section @code{LLE} --- Lexical less than or equal @fnindex LLE @cindex lexical comparison of strings @cindex string, comparison @table @asis @item @emph{Description}: Determines whether one string is lexically less than or equal to another string, where the two strings are interpreted as containing ASCII character codes. If the String A and String B are not the same length, the shorter is compared as if spaces were appended to it to form a value that has the same length as the longer. In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, @code{LLE}, and @code{LLT} differ from the corresponding intrinsic operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in that the latter use the processor's character ordering (which is not ASCII on some targets), whereas the former always use the ASCII ordering. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LLE(STRING_A, STRING_B)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. @end multitable @item @emph{Return value}: Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.} otherwise, based on the ASCII ordering. @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{LGE}, @ref{LGT}, @ref{LLT} @end table @node LLT @section @code{LLT} --- Lexical less than @fnindex LLT @cindex lexical comparison of strings @cindex string, comparison @table @asis @item @emph{Description}: Determines whether one string is lexically less than another string, where the two strings are interpreted as containing ASCII character codes. If the String A and String B are not the same length, the shorter is compared as if spaces were appended to it to form a value that has the same length as the longer. In general, the lexical comparison intrinsics @code{LGE}, @code{LGT}, @code{LLE}, and @code{LLT} differ from the corresponding intrinsic operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in that the latter use the processor's character ordering (which is not ASCII on some targets), whereas the former always use the ASCII ordering. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LLT(STRING_A, STRING_B)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type. @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type. @end multitable @item @emph{Return value}: Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.} otherwise, based on the ASCII ordering. @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{LGE}, @ref{LGT}, @ref{LLE} @end table @node LNBLNK @section @code{LNBLNK} --- Index of the last non-blank character in a string @fnindex LNBLNK @cindex string, find non-blank character @table @asis @item @emph{Description}: Returns the length of a character string, ignoring any trailing blanks. This is identical to the standard @code{LEN_TRIM} intrinsic, and is only included for backwards compatibility. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LNBLNK(STRING)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}, with @code{INTENT(IN)} @end multitable @item @emph{Return value}: The return value is of @code{INTEGER(kind=4)} type. @item @emph{See also}: @ref{INDEX intrinsic}, @ref{LEN_TRIM} @end table @node LOC @section @code{LOC} --- Returns the address of a variable @fnindex LOC @cindex location of a variable in memory @table @asis @item @emph{Description}: @code{LOC(X)} returns the address of @var{X} as an integer. @item @emph{Standard}: GNU extension @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = LOC(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Variable of any type. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER}, with a @code{KIND} corresponding to the size (in bytes) of a memory address on the target machine. @item @emph{Example}: @smallexample program test_loc integer :: i real :: r i = loc(r) print *, i end program test_loc @end smallexample @end table @node LOG @section @code{LOG} --- Natural logarithm function @fnindex LOG @fnindex ALOG @fnindex DLOG @fnindex CLOG @fnindex ZLOG @fnindex CDLOG @cindex exponential function, inverse @cindex logarithm function @cindex natural logarithm function @table @asis @item @emph{Description}: @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the logarithm to the base @math{e}. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LOG(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} or @code{COMPLEX}. The kind type parameter is the same as @var{X}. If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range @math{-\pi < \omega \leq \pi}. @item @emph{Example}: @smallexample program test_log real(8) :: x = 2.7182818284590451_8 complex :: z = (1.0, 2.0) x = log(x) ! will yield (approximately) 1 z = log(z) end program test_log @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu @end multitable @end table @node LOG10 @section @code{LOG10} --- Base 10 logarithm function @fnindex LOG10 @fnindex ALOG10 @fnindex DLOG10 @cindex exponential function, inverse @cindex logarithm function with base 10 @cindex base 10 logarithm function @table @asis @item @emph{Description}: @code{LOG10(X)} computes the base 10 logarithm of @var{X}. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LOG10(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} or @code{COMPLEX}. The kind type parameter is the same as @var{X}. @item @emph{Example}: @smallexample program test_log10 real(8) :: x = 10.0_8 x = log10(x) end program test_log10 @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later @end multitable @end table @node LOG_GAMMA @section @code{LOG_GAMMA} --- Logarithm of the Gamma function @fnindex LOG_GAMMA @fnindex LGAMMA @fnindex ALGAMA @fnindex DLGAMA @cindex Gamma function, logarithm of @table @asis @item @emph{Description}: @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value of the Gamma (@math{\Gamma}) function. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{X = LOG_GAMMA(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL} and neither zero nor a negative integer. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} of the same kind as @var{X}. @item @emph{Example}: @smallexample program test_log_gamma real :: x = 1.0 x = lgamma(x) ! returns 0.0 end program test_log_gamma @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension @end multitable @item @emph{See also}: Gamma function: @ref{GAMMA} @end table @node LOGICAL @section @code{LOGICAL} --- Convert to logical type @fnindex LOGICAL @cindex conversion, to logical @table @asis @item @emph{Description}: Converts one kind of @code{LOGICAL} variable to another. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LOGICAL(L [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{L} @tab The type shall be @code{LOGICAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is a @code{LOGICAL} value equal to @var{L}, with a kind corresponding to @var{KIND}, or of the default logical kind if @var{KIND} is not given. @item @emph{See also}: @ref{INT}, @ref{REAL}, @ref{CMPLX} @end table @node LONG @section @code{LONG} --- Convert to integer type @fnindex LONG @cindex conversion, to integer @table @asis @item @emph{Description}: Convert to a @code{KIND=4} integer type, which is the same size as a C @code{long} integer. This is equivalent to the standard @code{INT} intrinsic with an optional argument of @code{KIND=4}, and is only included for backwards compatibility. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LONG(A)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be of type @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is a @code{INTEGER(4)} variable. @item @emph{See also}: @ref{INT}, @ref{INT2}, @ref{INT8} @end table @node LSHIFT @section @code{LSHIFT} --- Left shift bits @fnindex LSHIFT @cindex bits, shift left @table @asis @item @emph{Description}: @code{LSHIFT} returns a value corresponding to @var{I} with all of the bits shifted left by @var{SHIFT} places. If the absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. Bits shifted out from the left end are lost; zeros are shifted in from the opposite end. This function has been superseded by the @code{ISHFT} intrinsic, which is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic, which is standard in Fortran 2008 and later. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = LSHIFT(I, SHIFT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL}, @ref{SHIFTR} @end table @node LSTAT @section @code{LSTAT} --- Get file status @fnindex LSTAT @cindex file system, file status @table @asis @item @emph{Description}: @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link, then the link itself is statted, not the file that it refers to. The elements in @code{VALUES} are the same as described by @ref{STAT}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])} @item @code{STATUS = LSTAT(NAME, VALUES)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default kind, a valid path within the file system. @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 on success and a system specific error code otherwise. @end multitable @item @emph{Example}: See @ref{STAT} for an example. @item @emph{See also}: To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT} @end table @node LTIME @section @code{LTIME} --- Convert time to local time info @fnindex LTIME @cindex time, conversion to local time info @table @asis @item @emph{Description}: Given a system time value @var{TIME} (as provided by the @code{TIME8} intrinsic), fills @var{VALUES} with values extracted from it appropriate to the local time zone using @code{localtime(3)}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL LTIME(TIME, VALUES)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{TIME} @tab An @code{INTEGER} scalar expression corresponding to a system time, with @code{INTENT(IN)}. @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements, with @code{INTENT(OUT)}. @end multitable @item @emph{Return value}: The elements of @var{VALUES} are assigned as follows: @enumerate @item Seconds after the minute, range 0--59 or 0--61 to allow for leap seconds @item Minutes after the hour, range 0--59 @item Hours past midnight, range 0--23 @item Day of month, range 0--31 @item Number of months since January, range 0--12 @item Years since 1900 @item Number of days since Sunday, range 0--6 @item Days since January 1 @item Daylight savings indicator: positive if daylight savings is in effect, zero if not, and negative if the information is not available. @end enumerate @item @emph{See also}: @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8} @end table @node MALLOC @section @code{MALLOC} --- Allocate dynamic memory @fnindex MALLOC @cindex pointer, cray @table @asis @item @emph{Description}: @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and returns the address of the allocated memory. The @code{MALLOC} intrinsic is an extension intended to be used with Cray pointers, and is provided in GNU Fortran to allow the user to compile legacy code. For new code using Fortran 95 pointers, the memory allocation intrinsic is @code{ALLOCATE}. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{PTR = MALLOC(SIZE)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SIZE} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER(K)}, with @var{K} such that variables of type @code{INTEGER(K)} have the same size as C pointers (@code{sizeof(void *)}). @item @emph{Example}: The following example demonstrates the use of @code{MALLOC} and @code{FREE} with Cray pointers. @smallexample program test_malloc implicit none integer i real*8 x(*), z pointer(ptr_x,x) ptr_x = malloc(20*8) do i = 1, 20 x(i) = sqrt(1.0d0 / i) end do z = 0 do i = 1, 20 z = z + x(i) print *, z end do call free(ptr_x) end program test_malloc @end smallexample @item @emph{See also}: @ref{FREE} @end table @node MASKL @section @code{MASKL} --- Left justified mask @fnindex MASKL @cindex mask, left justified @table @asis @item @emph{Description}: @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the remaining bits set to 0. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = MASKL(I[, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER}. @item @var{KIND} @tab Shall be a scalar constant expression of type @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER}. If @var{KIND} is present, it specifies the kind value of the return type; otherwise, it is of the default integer kind. @item @emph{See also}: @ref{MASKR} @end table @node MASKR @section @code{MASKR} --- Right justified mask @fnindex MASKR @cindex mask, right justified @table @asis @item @emph{Description}: @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the remaining bits set to 0. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = MASKR(I[, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER}. @item @var{KIND} @tab Shall be a scalar constant expression of type @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER}. If @var{KIND} is present, it specifies the kind value of the return type; otherwise, it is of the default integer kind. @item @emph{See also}: @ref{MASKL} @end table @node MATMUL @section @code{MATMUL} --- matrix multiplication @fnindex MATMUL @cindex matrix multiplication @cindex product, matrix @table @asis @item @emph{Description}: Performs a matrix multiplication on numeric or logical arguments. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{MATRIX_A} @tab An array of @code{INTEGER}, @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of one or two. @item @var{MATRIX_B} @tab An array of @code{INTEGER}, @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric type; otherwise, an array of @code{LOGICAL} type. The rank shall be one or two, and the first (or only) dimension of @var{MATRIX_B} shall be equal to the last (or only) dimension of @var{MATRIX_A}. @end multitable @item @emph{Return value}: The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and kind of the result follow the usual type and kind promotion rules, as for the @code{*} or @code{.AND.} operators. @item @emph{See also}: @end table @node MAX @section @code{MAX} --- Maximum value of an argument list @fnindex MAX @fnindex MAX0 @fnindex AMAX0 @fnindex MAX1 @fnindex AMAX1 @fnindex DMAX1 @cindex maximum value @table @asis @item @emph{Description}: Returns the argument with the largest (most positive) value. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = MAX(A1, A2 [, A3 [, ...]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A1} @tab The type shall be @code{INTEGER} or @code{REAL}. @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind as @var{A1}. (As a GNU extension, arguments of different kinds are permitted.) @end multitable @item @emph{Return value}: The return value corresponds to the maximum value among the arguments, and has the same type and kind as the first argument. @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN} @end table @node MAXEXPONENT @section @code{MAXEXPONENT} --- Maximum exponent of a real kind @fnindex MAXEXPONENT @cindex model representation, maximum exponent @table @asis @item @emph{Description}: @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the type of @code{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = MAXEXPONENT(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the default integer kind. @item @emph{Example}: @smallexample program exponents real(kind=4) :: x real(kind=8) :: y print *, minexponent(x), maxexponent(x) print *, minexponent(y), maxexponent(y) end program exponents @end smallexample @end table @node MAXLOC @section @code{MAXLOC} --- Location of the maximum value within an array @fnindex MAXLOC @cindex array, location of maximum element @table @asis @item @emph{Description}: Determines the location of the element in the array with the maximum value, or, if the @var{DIM} argument is supplied, determines the locations of the maximum element along each row of the array in the @var{DIM} direction. If @var{MASK} is present, only the elements for which @var{MASK} is @code{.TRUE.} are considered. If more than one element in the array has the maximum value, the location returned is that of the first such element in array element order. If the array has zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then the result is an array of zeroes. Similarly, if @var{DIM} is supplied and all of the elements of @var{MASK} along a given row are zero, the result value for that row is zero. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])} @item @code{RESULT = MAXLOC(ARRAY [, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or @code{REAL}. @item @var{DIM} @tab (Optional) Shall be a scalar of type @code{INTEGER}, with a value between one and the rank of @var{ARRAY}, inclusive. It may not be an optional dummy argument. @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, and conformable with @var{ARRAY}. @end multitable @item @emph{Return value}: If @var{DIM} is absent, the result is a rank-one array with a length equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result is an array with a rank one less than the rank of @var{ARRAY}, and a size corresponding to the size of @var{ARRAY} with the @var{DIM} dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank of one, the result is a scalar. In all cases, the result is of default @code{INTEGER} type. @item @emph{See also}: @ref{MAX}, @ref{MAXVAL} @end table @node MAXVAL @section @code{MAXVAL} --- Maximum value of an array @fnindex MAXVAL @cindex array, maximum value @cindex maximum value @table @asis @item @emph{Description}: Determines the maximum value of the elements in an array value, or, if the @var{DIM} argument is supplied, determines the maximum value along each row of the array in the @var{DIM} direction. If @var{MASK} is present, only the elements for which @var{MASK} is @code{.TRUE.} are considered. If the array has zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)} if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character type. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])} @item @code{RESULT = MAXVAL(ARRAY [, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or @code{REAL}. @item @var{DIM} @tab (Optional) Shall be a scalar of type @code{INTEGER}, with a value between one and the rank of @var{ARRAY}, inclusive. It may not be an optional dummy argument. @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, and conformable with @var{ARRAY}. @end multitable @item @emph{Return value}: If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result is a scalar. If @var{DIM} is present, the result is an array with a rank one less than the rank of @var{ARRAY}, and a size corresponding to the size of @var{ARRAY} with the @var{DIM} dimension removed. In all cases, the result is of the same type and kind as @var{ARRAY}. @item @emph{See also}: @ref{MAX}, @ref{MAXLOC} @end table @node MCLOCK @section @code{MCLOCK} --- Time function @fnindex MCLOCK @cindex time, clock ticks @cindex clock ticks @table @asis @item @emph{Description}: Returns the number of clock ticks since the start of the process, based on the function @code{clock(3)} in the C standard library. This intrinsic is not fully portable, such as to systems with 32-bit @code{INTEGER} types but supporting times wider than 32 bits. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = MCLOCK()} @item @emph{Return value}: The return value is a scalar of type @code{INTEGER(4)}, equal to the number of clock ticks since the start of the process, or @code{-1} if the system does not support @code{clock(3)}. @item @emph{See also}: @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME} @end table @node MCLOCK8 @section @code{MCLOCK8} --- Time function (64-bit) @fnindex MCLOCK8 @cindex time, clock ticks @cindex clock ticks @table @asis @item @emph{Description}: Returns the number of clock ticks since the start of the process, based on the function @code{clock(3)} in the C standard library. @emph{Warning:} this intrinsic does not increase the range of the timing values over that returned by @code{clock(3)}. On a system with a 32-bit @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though it is converted to a 64-bit @code{INTEGER(8)} value. That means overflows of the 32-bit value can still occur. Therefore, the values returned by this intrinsic might be or become negative or numerically less than previous values during a single run of the compiled program. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = MCLOCK8()} @item @emph{Return value}: The return value is a scalar of type @code{INTEGER(8)}, equal to the number of clock ticks since the start of the process, or @code{-1} if the system does not support @code{clock(3)}. @item @emph{See also}: @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} @end table @node MERGE @section @code{MERGE} --- Merge variables @fnindex MERGE @cindex array, merge arrays @cindex array, combine arrays @table @asis @item @emph{Description}: Select values from two arrays according to a logical mask. The result is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to @var{FSOURCE} if it is @code{.FALSE.}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{TSOURCE} @tab May be of any type. @item @var{FSOURCE} @tab Shall be of the same type and type parameters as @var{TSOURCE}. @item @var{MASK} @tab Shall be of type @code{LOGICAL}. @end multitable @item @emph{Return value}: The result is of the same type and type parameters as @var{TSOURCE}. @end table @node MERGE_BITS @section @code{MERGE_BITS} --- Merge of bits under mask @fnindex MERGE_BITS @cindex bits, merge @table @asis @item @emph{Description}: @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J} as determined by the mask. The i-th bit of the result is equal to the i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to the i-th bit of @var{J} otherwise. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = MERGE_BITS(I, J, MASK)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER}. @item @var{J} @tab Shall be of type @code{INTEGER} and of the same kind as @var{I}. @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same kind as @var{I}. @end multitable @item @emph{Return value}: The result is of the same type and kind as @var{I}. @end table @node MIN @section @code{MIN} --- Minimum value of an argument list @fnindex MIN @fnindex MIN0 @fnindex AMIN0 @fnindex MIN1 @fnindex AMIN1 @fnindex DMIN1 @cindex minimum value @table @asis @item @emph{Description}: Returns the argument with the smallest (most negative) value. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = MIN(A1, A2 [, A3, ...])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A1} @tab The type shall be @code{INTEGER} or @code{REAL}. @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind as @var{A1}. (As a GNU extension, arguments of different kinds are permitted.) @end multitable @item @emph{Return value}: The return value corresponds to the maximum value among the arguments, and has the same type and kind as the first argument. @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{MAX}, @ref{MINLOC}, @ref{MINVAL} @end table @node MINEXPONENT @section @code{MINEXPONENT} --- Minimum exponent of a real kind @fnindex MINEXPONENT @cindex model representation, minimum exponent @table @asis @item @emph{Description}: @code{MINEXPONENT(X)} returns the minimum exponent in the model of the type of @code{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = MINEXPONENT(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the default integer kind. @item @emph{Example}: See @code{MAXEXPONENT} for an example. @end table @node MINLOC @section @code{MINLOC} --- Location of the minimum value within an array @fnindex MINLOC @cindex array, location of minimum element @table @asis @item @emph{Description}: Determines the location of the element in the array with the minimum value, or, if the @var{DIM} argument is supplied, determines the locations of the minimum element along each row of the array in the @var{DIM} direction. If @var{MASK} is present, only the elements for which @var{MASK} is @code{.TRUE.} are considered. If more than one element in the array has the minimum value, the location returned is that of the first such element in array element order. If the array has zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then the result is an array of zeroes. Similarly, if @var{DIM} is supplied and all of the elements of @var{MASK} along a given row are zero, the result value for that row is zero. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])} @item @code{RESULT = MINLOC(ARRAY [, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or @code{REAL}. @item @var{DIM} @tab (Optional) Shall be a scalar of type @code{INTEGER}, with a value between one and the rank of @var{ARRAY}, inclusive. It may not be an optional dummy argument. @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, and conformable with @var{ARRAY}. @end multitable @item @emph{Return value}: If @var{DIM} is absent, the result is a rank-one array with a length equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result is an array with a rank one less than the rank of @var{ARRAY}, and a size corresponding to the size of @var{ARRAY} with the @var{DIM} dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank of one, the result is a scalar. In all cases, the result is of default @code{INTEGER} type. @item @emph{See also}: @ref{MIN}, @ref{MINVAL} @end table @node MINVAL @section @code{MINVAL} --- Minimum value of an array @fnindex MINVAL @cindex array, minimum value @cindex minimum value @table @asis @item @emph{Description}: Determines the minimum value of the elements in an array value, or, if the @var{DIM} argument is supplied, determines the minimum value along each row of the array in the @var{DIM} direction. If @var{MASK} is present, only the elements for which @var{MASK} is @code{.TRUE.} are considered. If the array has zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if @var{ARRAY} is of character type. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])} @item @code{RESULT = MINVAL(ARRAY [, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or @code{REAL}. @item @var{DIM} @tab (Optional) Shall be a scalar of type @code{INTEGER}, with a value between one and the rank of @var{ARRAY}, inclusive. It may not be an optional dummy argument. @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}, and conformable with @var{ARRAY}. @end multitable @item @emph{Return value}: If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result is a scalar. If @var{DIM} is present, the result is an array with a rank one less than the rank of @var{ARRAY}, and a size corresponding to the size of @var{ARRAY} with the @var{DIM} dimension removed. In all cases, the result is of the same type and kind as @var{ARRAY}. @item @emph{See also}: @ref{MIN}, @ref{MINLOC} @end table @node MOD @section @code{MOD} --- Remainder function @fnindex MOD @fnindex AMOD @fnindex DMOD @cindex remainder @cindex division, remainder @table @asis @item @emph{Description}: @code{MOD(A,P)} computes the remainder of the division of A by P@. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = MOD(A, P)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A} and not equal to zero. @end multitable @item @emph{Return value}: The return value is the result of @code{A - (INT(A/P) * P)}. The type and kind of the return value is the same as that of the arguments. The returned value has the same sign as A and a magnitude less than the magnitude of P. @item @emph{Example}: @smallexample program test_mod print *, mod(17,3) print *, mod(17.5,5.5) print *, mod(17.5d0,5.5) print *, mod(17.5,5.5d0) print *, mod(-17,3) print *, mod(-17.5,5.5) print *, mod(-17.5d0,5.5) print *, mod(-17.5,5.5d0) print *, mod(17,-3) print *, mod(17.5,-5.5) print *, mod(17.5d0,-5.5) print *, mod(17.5,-5.5d0) end program test_mod @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Arguments @tab Return type @tab Standard @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later @end multitable @item @emph{See also}: @ref{MODULO} @end table @node MODULO @section @code{MODULO} --- Modulo function @fnindex MODULO @cindex modulo @cindex division, modulo @table @asis @item @emph{Description}: @code{MODULO(A,P)} computes the @var{A} modulo @var{P}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = MODULO(A, P)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}. @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}. It shall not be zero. @end multitable @item @emph{Return value}: The type and kind of the result are those of the arguments. @table @asis @item If @var{A} and @var{P} are of type @code{INTEGER}: @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P} (exclusive). @item If @var{A} and @var{P} are of type @code{REAL}: @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}. @end table The returned value has the same sign as P and a magnitude less than the magnitude of P. @item @emph{Example}: @smallexample program test_modulo print *, modulo(17,3) print *, modulo(17.5,5.5) print *, modulo(-17,3) print *, modulo(-17.5,5.5) print *, modulo(17,-3) print *, modulo(17.5,-5.5) end program @end smallexample @item @emph{See also}: @ref{MOD} @end table @node MOVE_ALLOC @section @code{MOVE_ALLOC} --- Move allocation from one object to another @fnindex MOVE_ALLOC @cindex moving allocation @cindex allocation, moving @table @asis @item @emph{Description}: @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to @var{TO}. @var{FROM} will become deallocated in the process. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Pure subroutine @item @emph{Syntax}: @code{CALL MOVE_ALLOC(FROM, TO)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be of any type and kind. @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be of the same type, kind and rank as @var{FROM}. @end multitable @item @emph{Return value}: None @item @emph{Example}: @smallexample program test_move_alloc integer, allocatable :: a(:), b(:) allocate(a(3)) a = [ 1, 2, 3 ] call move_alloc(a, b) print *, allocated(a), allocated(b) print *, b end program test_move_alloc @end smallexample @end table @node MVBITS @section @code{MVBITS} --- Move bits from one integer to another @fnindex MVBITS @cindex bits, move @table @asis @item @emph{Description}: Moves @var{LEN} bits from positions @var{FROMPOS} through @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not affected by the movement of bits is unchanged. The values of @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than @code{BIT_SIZE(FROM)}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental subroutine @item @emph{Syntax}: @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{FROM} @tab The type shall be @code{INTEGER}. @item @var{FROMPOS} @tab The type shall be @code{INTEGER}. @item @var{LEN} @tab The type shall be @code{INTEGER}. @item @var{TO} @tab The type shall be @code{INTEGER}, of the same kind as @var{FROM}. @item @var{TOPOS} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{See also}: @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR} @end table @node NEAREST @section @code{NEAREST} --- Nearest representable number @fnindex NEAREST @cindex real number, nearest different @cindex floating point, nearest different @table @asis @item @emph{Description}: @code{NEAREST(X, S)} returns the processor-representable number nearest to @code{X} in the direction indicated by the sign of @code{S}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = NEAREST(X, S)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL}. @item @var{S} @tab Shall be of type @code{REAL} and not equal to zero. @end multitable @item @emph{Return value}: The return value is of the same type as @code{X}. If @code{S} is positive, @code{NEAREST} returns the processor-representable number greater than @code{X} and nearest to it. If @code{S} is negative, @code{NEAREST} returns the processor-representable number smaller than @code{X} and nearest to it. @item @emph{Example}: @smallexample program test_nearest real :: x, y x = nearest(42.0, 1.0) y = nearest(42.0, -1.0) write (*,"(3(G20.15))") x, y, x - y end program test_nearest @end smallexample @end table @node NEW_LINE @section @code{NEW_LINE} --- New line character @fnindex NEW_LINE @cindex newline @cindex output, newline @table @asis @item @emph{Description}: @code{NEW_LINE(C)} returns the new-line character. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = NEW_LINE(C)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{C} @tab The argument shall be a scalar or array of the type @code{CHARACTER}. @end multitable @item @emph{Return value}: Returns a @var{CHARACTER} scalar of length one with the new-line character of the same kind as parameter @var{C}. @item @emph{Example}: @smallexample program newline implicit none write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.' end program newline @end smallexample @end table @node NINT @section @code{NINT} --- Nearest whole number @fnindex NINT @fnindex IDNINT @cindex rounding, nearest whole number @table @asis @item @emph{Description}: @code{NINT(A)} rounds its argument to the nearest whole number. @item @emph{Standard}: Fortran 77 and later, with @var{KIND} argument Fortran 90 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = NINT(A [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab The type of the argument shall be @code{REAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: Returns @var{A} with the fractional portion of its magnitude eliminated by rounding to the nearest whole number and with its sign preserved, converted to an @code{INTEGER} of the default kind. @item @emph{Example}: @smallexample program test_nint real(4) x4 real(8) x8 x4 = 1.234E0_4 x8 = 4.321_8 print *, nint(x4), idnint(x8) end program test_nint @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return Type @tab Standard @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later @end multitable @item @emph{See also}: @ref{CEILING}, @ref{FLOOR} @end table @node NORM2 @section @code{NORM2} --- Euclidean vector norms @fnindex NORM2 @cindex Euclidean vector norm @cindex L2 vector norm @cindex norm, Euclidean @table @asis @item @emph{Description}: Calculates the Euclidean vector norm (@math{L_2} norm) of of @var{ARRAY} along dimension @var{DIM}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = NORM2(ARRAY[, DIM])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{REAL} @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} with a value in the range from 1 to n, where n equals the rank of @var{ARRAY}. @end multitable @item @emph{Return value}: The result is of the same type as @var{ARRAY}. If @var{DIM} is absent, a scalar with the square root of the sum of all elements in @var{ARRAY} squared is returned. Otherwise, an array of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped is returned. @item @emph{Example}: @smallexample PROGRAM test_sum REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ] print *, NORM2(x) ! = sqrt(55.) ~ 7.416 END PROGRAM @end smallexample @end table @node NOT @section @code{NOT} --- Logical negation @fnindex NOT @cindex bits, negate @cindex bitwise logical not @cindex logical not, bitwise @table @asis @item @emph{Description}: @code{NOT} returns the bitwise Boolean inverse of @var{I}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = NOT(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return type is @code{INTEGER}, of the same kind as the argument. @item @emph{See also}: @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR} @end table @node NULL @section @code{NULL} --- Function that returns an disassociated pointer @fnindex NULL @cindex pointer, status @cindex pointer, disassociated @table @asis @item @emph{Description}: Returns a disassociated pointer. If @var{MOLD} is present, a disassociated pointer of the same type is returned, otherwise the type is determined by context. In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003 includes cases where it is required. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{PTR => NULL([MOLD])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{MOLD} @tab (Optional) shall be a pointer of any association status and of any type. @end multitable @item @emph{Return value}: A disassociated pointer. @item @emph{Example}: @smallexample REAL, POINTER, DIMENSION(:) :: VEC => NULL () @end smallexample @item @emph{See also}: @ref{ASSOCIATED} @end table @node NUM_IMAGES @section @code{NUM_IMAGES} --- Function that returns the number of images @fnindex NUM_IMAGES @cindex coarray, @code{NUM_IMAGES} @cindex images, number of @table @asis @item @emph{Description}: Returns the number of images. @item @emph{Standard}: Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument, Technical Specification (TS) 18508 or later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression @end multitable @item @emph{Return value}: Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0, the number of images in the current team is returned. For values smaller or equal distance to the initial team, it returns the number of images index on the ancestor team which has a distance of @var{DISTANCE} from the invoking team. If @var{DISTANCE} is larger than the distance to the initial team, the number of images of the initial team is returned. If @var{FAILED} is not present the total number of images is returned; if it has the value @code{.TRUE.}, the number of failed images is returned, otherwise, the number of images which do have not the failed status. @item @emph{Example}: @smallexample INTEGER :: value[*] INTEGER :: i value = THIS_IMAGE() SYNC ALL IF (THIS_IMAGE() == 1) THEN DO i = 1, NUM_IMAGES() WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] END DO END IF @end smallexample @item @emph{See also}: @ref{THIS_IMAGE}, @ref{IMAGE_INDEX} @end table @node OR @section @code{OR} --- Bitwise logical OR @fnindex OR @cindex bitwise logical or @cindex logical or, bitwise @table @asis @item @emph{Description}: Bitwise logical @code{OR}. This intrinsic routine is provided for backwards compatibility with GNU Fortran 77. For integer arguments, programmers should consider the use of the @ref{IOR} intrinsic defined by the Fortran standard. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = OR(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be either a scalar @code{INTEGER} type or a scalar @code{LOGICAL} type. @item @var{J} @tab The type shall be the same as the type of @var{J}. @end multitable @item @emph{Return value}: The return type is either a scalar @code{INTEGER} or a scalar @code{LOGICAL}. If the kind type parameters differ, then the smaller kind type is implicitly converted to larger kind, and the return has the larger kind. @item @emph{Example}: @smallexample PROGRAM test_or LOGICAL :: T = .TRUE., F = .FALSE. INTEGER :: a, b DATA a / Z'F' /, b / Z'3' / WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F) WRITE (*,*) OR(a, b) END PROGRAM @end smallexample @item @emph{See also}: Fortran 95 elemental function: @ref{IOR} @end table @node PACK @section @code{PACK} --- Pack an array into an array of rank one @fnindex PACK @cindex array, packing @cindex array, reduce dimension @cindex array, gather elements @table @asis @item @emph{Description}: Stores the elements of @var{ARRAY} in an array of rank one. The beginning of the resulting array is made up of elements whose @var{MASK} equals @code{TRUE}. Afterwards, positions are filled with elements taken from @var{VECTOR}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = PACK(ARRAY, MASK[,VECTOR])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of any type. @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} scalar. @item @var{VECTOR} @tab (Optional) shall be an array of the same type as @var{ARRAY} and of rank one. If present, the number of elements in @var{VECTOR} shall be equal to or greater than the number of true elements in @var{MASK}. If @var{MASK} is scalar, the number of elements in @var{VECTOR} shall be equal to or greater than the number of elements in @var{ARRAY}. @end multitable @item @emph{Return value}: The result is an array of rank one and the same type as that of @var{ARRAY}. If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the number of @code{TRUE} values in @var{MASK} otherwise. @item @emph{Example}: Gathering nonzero elements from an array: @smallexample PROGRAM test_pack_1 INTEGER :: m(6) m = (/ 1, 0, 0, 0, 5, 0 /) WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5" END PROGRAM @end smallexample Gathering nonzero elements from an array and appending elements from @var{VECTOR}: @smallexample PROGRAM test_pack_2 INTEGER :: m(4) m = (/ 1, 0, 0, 2 /) WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4" END PROGRAM @end smallexample @item @emph{See also}: @ref{UNPACK} @end table @node PARITY @section @code{PARITY} --- Reduction with exclusive OR @fnindex PARITY @cindex Parity @cindex Reduction, XOR @cindex XOR reduction @table @asis @item @emph{Description}: Calculates the parity, i.e. the reduction using @code{.XOR.}, of @var{MASK} along dimension @var{DIM}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = PARITY(MASK[, DIM])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL} @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} with a value in the range from 1 to n, where n equals the rank of @var{MASK}. @end multitable @item @emph{Return value}: The result is of the same type as @var{MASK}. If @var{DIM} is absent, a scalar with the parity of all elements in @var{MASK} is returned, i.e. true if an odd number of elements is @code{.true.} and false otherwise. If @var{DIM} is present, an array of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a shape similar to that of @var{MASK} with dimension @var{DIM} dropped is returned. @item @emph{Example}: @smallexample PROGRAM test_sum LOGICAL :: x(2) = [ .true., .false. ] print *, PARITY(x) ! prints "T" (true). END PROGRAM @end smallexample @end table @node PERROR @section @code{PERROR} --- Print system error message @fnindex PERROR @cindex system, error handling @table @asis @item @emph{Description}: Prints (on the C @code{stderr} stream) a newline-terminated error message corresponding to the last system error. This is prefixed by @var{STRING}, a colon and a space. See @code{perror(3)}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL PERROR(STRING)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the default kind. @end multitable @item @emph{See also}: @ref{IERRNO} @end table @node POPCNT @section @code{POPCNT} --- Number of bits set @fnindex POPCNT @cindex binary representation @cindex bits set @table @asis @item @emph{Description}: @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary representation of @code{I}. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = POPCNT(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the default integer kind. @item @emph{See also}: @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ} @item @emph{Example}: @smallexample program test_population print *, popcnt(127), poppar(127) print *, popcnt(huge(0_4)), poppar(huge(0_4)) print *, popcnt(huge(0_8)), poppar(huge(0_8)) end program test_population @end smallexample @end table @node POPPAR @section @code{POPPAR} --- Parity of the number of bits set @fnindex POPPAR @cindex binary representation @cindex parity @table @asis @item @emph{Description}: @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity of the number of bits set ('1' bits) in the binary representation of @code{I}. It is equal to 0 if @code{I} has an even number of bits set, and 1 for an odd number of '1' bits. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = POPPAR(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the default integer kind. @item @emph{See also}: @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ} @item @emph{Example}: @smallexample program test_population print *, popcnt(127), poppar(127) print *, popcnt(huge(0_4)), poppar(huge(0_4)) print *, popcnt(huge(0_8)), poppar(huge(0_8)) end program test_population @end smallexample @end table @node PRECISION @section @code{PRECISION} --- Decimal precision of a real kind @fnindex PRECISION @cindex model representation, precision @table @asis @item @emph{Description}: @code{PRECISION(X)} returns the decimal precision in the model of the type of @code{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = PRECISION(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the default integer kind. @item @emph{See also}: @ref{SELECTED_REAL_KIND}, @ref{RANGE} @item @emph{Example}: @smallexample program prec_and_range real(kind=4) :: x(2) complex(kind=8) :: y print *, precision(x), range(x) print *, precision(y), range(y) end program prec_and_range @end smallexample @end table @node PRESENT @section @code{PRESENT} --- Determine whether an optional dummy argument is specified @fnindex PRESENT @table @asis @item @emph{Description}: Determines whether an optional dummy argument is present. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = PRESENT(A)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab May be of any type and may be a pointer, scalar or array value, or a dummy procedure. It shall be the name of an optional dummy argument accessible within the current subroutine or function. @end multitable @item @emph{Return value}: Returns either @code{TRUE} if the optional argument @var{A} is present, or @code{FALSE} otherwise. @item @emph{Example}: @smallexample PROGRAM test_present WRITE(*,*) f(), f(42) ! "F T" CONTAINS LOGICAL FUNCTION f(x) INTEGER, INTENT(IN), OPTIONAL :: x f = PRESENT(x) END FUNCTION END PROGRAM @end smallexample @end table @node PRODUCT @section @code{PRODUCT} --- Product of array elements @fnindex PRODUCT @cindex array, product @cindex array, multiply elements @cindex array, conditionally multiply elements @cindex multiply array elements @table @asis @item @emph{Description}: Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = PRODUCT(ARRAY[, MASK])} @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, @code{REAL} or @code{COMPLEX}. @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} with a value in the range from 1 to n, where n equals the rank of @var{ARRAY}. @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} and either be a scalar or an array of the same shape as @var{ARRAY}. @end multitable @item @emph{Return value}: The result is of the same type as @var{ARRAY}. If @var{DIM} is absent, a scalar with the product of all elements in @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped is returned. @item @emph{Example}: @smallexample PROGRAM test_product INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) print *, PRODUCT(x) ! all elements, product = 120 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15 END PROGRAM @end smallexample @item @emph{See also}: @ref{SUM} @end table @node RADIX @section @code{RADIX} --- Base of a model number @fnindex RADIX @cindex model representation, base @cindex model representation, radix @table @asis @item @emph{Description}: @code{RADIX(X)} returns the base of the model representing the entity @var{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = RADIX(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL} @end multitable @item @emph{Return value}: The return value is a scalar of type @code{INTEGER} and of the default integer kind. @item @emph{See also}: @ref{SELECTED_REAL_KIND} @item @emph{Example}: @smallexample program test_radix print *, "The radix for the default integer kind is", radix(0) print *, "The radix for the default real kind is", radix(0.0) end program test_radix @end smallexample @end table @node RAN @section @code{RAN} --- Real pseudo-random number @fnindex RAN @cindex random number generation @table @asis @item @emph{Description}: For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is provided as an alias for @code{RAND}. See @ref{RAND} for complete documentation. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{See also}: @ref{RAND}, @ref{RANDOM_NUMBER} @end table @node RAND @section @code{RAND} --- Real pseudo-random number @fnindex RAND @cindex random number generation @table @asis @item @emph{Description}: @code{RAND(FLAG)} returns a pseudo-random number from a uniform distribution between 0 and 1. If @var{FLAG} is 0, the next number in the current sequence is returned; if @var{FLAG} is 1, the generator is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value, it is used as a new seed with @code{SRAND}. This intrinsic routine is provided for backwards compatibility with GNU Fortran 77. It implements a simple modulo generator as provided by @command{g77}. For new code, one should consider the use of @ref{RANDOM_NUMBER} as it implements a superior algorithm. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = RAND(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4. @end multitable @item @emph{Return value}: The return value is of @code{REAL} type and the default kind. @item @emph{Example}: @smallexample program test_rand integer,parameter :: seed = 86456 call srand(seed) print *, rand(), rand(), rand(), rand() print *, rand(seed), rand(), rand(), rand() end program test_rand @end smallexample @item @emph{See also}: @ref{SRAND}, @ref{RANDOM_NUMBER} @end table @node RANDOM_NUMBER @section @code{RANDOM_NUMBER} --- Pseudo-random number @fnindex RANDOM_NUMBER @cindex random number generation @table @asis @item @emph{Description}: Returns a single pseudorandom number or an array of pseudorandom numbers from the uniform distribution over the range @math{ 0 \leq x < 1}. The runtime-library implements George Marsaglia's KISS (Keep It Simple Stupid) random number generator (RNG). This RNG combines: @enumerate @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885} with a period of @math{2^{32}}, @item A 3-shift shift-register generator with a period of @math{2^{32} - 1}, @item Two 16-bit multiply-with-carry generators with a period of @math{597273182964842497 > 2^{59}}. @end enumerate The overall period exceeds @math{2^{123}}. Please note, this RNG is thread safe if used within OpenMP directives, i.e., its state will be consistent while called from multiple threads. However, the KISS generator does not create random numbers in parallel from multiple sources, but in sequence from a single source. If an OpenMP-enabled application heavily relies on random numbers, one should consider employing a dedicated parallel random number generator instead. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{RANDOM_NUMBER(HARVEST)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}. @end multitable @item @emph{Example}: @smallexample program test_random_number REAL :: r(5,5) CALL init_random_seed() ! see example of RANDOM_SEED CALL RANDOM_NUMBER(r) end program @end smallexample @item @emph{See also}: @ref{RANDOM_SEED} @end table @node RANDOM_SEED @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence @fnindex RANDOM_SEED @cindex random number generation, seeding @cindex seeding a random number generator @table @asis @item @emph{Description}: Restarts or queries the state of the pseudorandom number generator used by @code{RANDOM_NUMBER}. If @code{RANDOM_SEED} is called without arguments, it is initialized to a default state. The example below shows how to initialize the random seed with a varying seed in order to ensure a different random number sequence for each invocation of the program. Note that setting any of the seed values to zero should be avoided as it can result in poor quality random numbers being generated. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL RANDOM_SEED([SIZE, PUT, GET])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size of the arrays used with the @var{PUT} and @var{GET} arguments. @item @var{PUT} @tab (Optional) Shall be an array of type default @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of the array must be larger than or equal to the number returned by the @var{SIZE} argument. @item @var{GET} @tab (Optional) Shall be an array of type default @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size of the array must be larger than or equal to the number returned by the @var{SIZE} argument. @end multitable @item @emph{Example}: @smallexample subroutine init_random_seed() use iso_fortran_env, only: int64 implicit none integer, allocatable :: seed(:) integer :: i, n, un, istat, dt(8), pid integer(int64) :: t call random_seed(size = n) allocate(seed(n)) ! First try if the OS provides a random number generator open(newunit=un, file="/dev/urandom", access="stream", & form="unformatted", action="read", status="old", iostat=istat) if (istat == 0) then read(un) seed close(un) else ! Fallback to XOR:ing the current time and pid. The PID is ! useful in case one launches multiple instances of the same ! program in parallel. call system_clock(t) if (t == 0) then call date_and_time(values=dt) t = (dt(1) - 1970) * 365_int64 * 24 * 60 * 60 * 1000 & + dt(2) * 31_int64 * 24 * 60 * 60 * 1000 & + dt(3) * 24_int64 * 60 * 60 * 1000 & + dt(5) * 60 * 60 * 1000 & + dt(6) * 60 * 1000 + dt(7) * 1000 & + dt(8) end if pid = getpid() t = ieor(t, int(pid, kind(t))) do i = 1, n seed(i) = lcg(t) end do end if call random_seed(put=seed) contains ! This simple PRNG might not be good enough for real work, but is ! sufficient for seeding a better PRNG. function lcg(s) integer :: lcg integer(int64) :: s if (s == 0) then s = 104729 else s = mod(s, 4294967296_int64) end if s = mod(s * 279470273_int64, 4294967291_int64) lcg = int(mod(s, int(huge(0), int64)), kind(0)) end function lcg end subroutine init_random_seed @end smallexample @item @emph{See also}: @ref{RANDOM_NUMBER} @end table @node RANGE @section @code{RANGE} --- Decimal exponent range @fnindex RANGE @cindex model representation, range @table @asis @item @emph{Description}: @code{RANGE(X)} returns the decimal exponent range in the model of the type of @code{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = RANGE(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the default integer kind. @item @emph{See also}: @ref{SELECTED_REAL_KIND}, @ref{PRECISION} @item @emph{Example}: See @code{PRECISION} for an example. @end table @node RANK @section @code{RANK} --- Rank of a data object @fnindex RANK @cindex rank @table @asis @item @emph{Description}: @code{RANK(A)} returns the rank of a scalar or array data object. @item @emph{Standard}: Technical Specification (TS) 29113 @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = RANK(A)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab can be of any type @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the default integer kind. For arrays, their rank is returned; for scalars zero is returned. @item @emph{Example}: @smallexample program test_rank integer :: a real, allocatable :: b(:,:) print *, rank(a), rank(b) ! Prints: 0 2 end program test_rank @end smallexample @end table @node REAL @section @code{REAL} --- Convert to real type @fnindex REAL @fnindex REALPART @fnindex FLOAT @fnindex DFLOAT @fnindex SNGL @cindex conversion, to real @cindex complex numbers, real part @table @asis @item @emph{Description}: @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The @code{REALPART} function is provided for compatibility with @command{g77}, and its use is strongly discouraged. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = REAL(A [, KIND])} @item @code{RESULT = REALPART(Z)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: These functions return a @code{REAL} variable or array under the following rules: @table @asis @item (A) @code{REAL(A)} is converted to a default real type if @var{A} is an integer or real variable. @item (B) @code{REAL(A)} is converted to a real type with the kind type parameter of @var{A} if @var{A} is a complex variable. @item (C) @code{REAL(A, KIND)} is converted to a real type with kind type parameter @var{KIND} if @var{A} is a complex, integer, or real variable. @end table @item @emph{Example}: @smallexample program test_real complex :: x = (1.0, 2.0) print *, real(x), real(x,8), realpart(x) end program test_real @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later @end multitable @item @emph{See also}: @ref{DBLE} @end table @node RENAME @section @code{RENAME} --- Rename a file @fnindex RENAME @cindex file system, rename file @table @asis @item @emph{Description}: Renames a file from file @var{PATH1} to @var{PATH2}. A null character (@code{CHAR(0)}) can be used to mark the end of the names in @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file names are ignored. If the @var{STATUS} argument is supplied, it contains 0 on success or a nonzero error code upon return; see @code{rename(2)}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])} @item @code{STATUS = RENAME(PATH1, PATH2)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. @end multitable @item @emph{See also}: @ref{LINK} @end table @node REPEAT @section @code{REPEAT} --- Repeated string concatenation @fnindex REPEAT @cindex string, repeat @cindex string, concatenate @table @asis @item @emph{Description}: Concatenates @var{NCOPIES} copies of a string. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = REPEAT(STRING, NCOPIES)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}. @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}. @end multitable @item @emph{Return value}: A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies of @var{STRING}. @item @emph{Example}: @smallexample program test_repeat write(*,*) repeat("x", 5) ! "xxxxx" end program @end smallexample @end table @node RESHAPE @section @code{RESHAPE} --- Function to reshape an array @fnindex RESHAPE @cindex array, change dimensions @cindex array, transmogrify @table @asis @item @emph{Description}: Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary, the new array may be padded with elements from @var{PAD} or permuted as defined by @var{ORDER}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SOURCE} @tab Shall be an array of any type. @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an array of rank one. Its values must be positive or zero. @item @var{PAD} @tab (Optional) shall be an array of the same type as @var{SOURCE}. @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER} and an array of the same shape as @var{SHAPE}. Its values shall be a permutation of the numbers from 1 to n, where n is the size of @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall be assumed. @end multitable @item @emph{Return value}: The result is an array of shape @var{SHAPE} with the same type as @var{SOURCE}. @item @emph{Example}: @smallexample PROGRAM test_reshape INTEGER, DIMENSION(4) :: x WRITE(*,*) SHAPE(x) ! prints "4" WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2" END PROGRAM @end smallexample @item @emph{See also}: @ref{SHAPE} @end table @node RRSPACING @section @code{RRSPACING} --- Reciprocal of the relative spacing @fnindex RRSPACING @cindex real number, relative spacing @cindex floating point, relative spacing @table @asis @item @emph{Description}: @code{RRSPACING(X)} returns the reciprocal of the relative spacing of model numbers near @var{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = RRSPACING(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X}. The value returned is equal to @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}. @item @emph{See also}: @ref{SPACING} @end table @node RSHIFT @section @code{RSHIFT} --- Right shift bits @fnindex RSHIFT @cindex bits, shift right @table @asis @item @emph{Description}: @code{RSHIFT} returns a value corresponding to @var{I} with all of the bits shifted right by @var{SHIFT} places. If the absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. Bits shifted out from the right end are lost. The fill is arithmetic: the bits shifted in from the left end are equal to the leftmost bit, which in two's complement representation is the sign bit. This function has been superseded by the @code{SHIFTA} intrinsic, which is standard in Fortran 2008 and later. @item @emph{Standard}: GNU extension @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = RSHIFT(I, SHIFT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR}, @ref{SHIFTL} @end table @node SAME_TYPE_AS @section @code{SAME_TYPE_AS} --- Query dynamic types for equality @fnindex SAME_TYPE_AS @table @asis @item @emph{Description}: Query dynamic types for equality. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = SAME_TYPE_AS(A, B)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be an object of extensible declared type or unlimited polymorphic. @item @var{B} @tab Shall be an object of extensible declared type or unlimited polymorphic. @end multitable @item @emph{Return value}: The return value is a scalar of type default logical. It is true if and only if the dynamic type of A is the same as the dynamic type of B. @item @emph{See also}: @ref{EXTENDS_TYPE_OF} @end table @node SCALE @section @code{SCALE} --- Scale a real value @fnindex SCALE @cindex real number, scale @cindex floating point, scale @table @asis @item @emph{Description}: @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SCALE(X, I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type of the argument shall be a @code{REAL}. @item @var{I} @tab The type of the argument shall be a @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X}. Its value is @code{X * RADIX(X)**I}. @item @emph{Example}: @smallexample program test_scale real :: x = 178.1387e-4 integer :: i = 5 print *, scale(x,i), x*radix(x)**i end program test_scale @end smallexample @end table @node SCAN @section @code{SCAN} --- Scan a string for the presence of a set of characters @fnindex SCAN @cindex string, find subset @table @asis @item @emph{Description}: Scans a @var{STRING} for any of the characters in a @var{SET} of characters. If @var{BACK} is either absent or equals @code{FALSE}, this function returns the position of the leftmost character of @var{STRING} that is in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position is returned. If no character of @var{SET} is found in @var{STRING}, the result is zero. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab Shall be of type @code{CHARACTER}. @item @var{SET} @tab Shall be of type @code{CHARACTER}. @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. @item @emph{Example}: @smallexample PROGRAM test_scan WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O' WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A' WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none END PROGRAM @end smallexample @item @emph{See also}: @ref{INDEX intrinsic}, @ref{VERIFY} @end table @node SECNDS @section @code{SECNDS} --- Time function @fnindex SECNDS @cindex time, elapsed @cindex elapsed time @table @asis @item @emph{Description}: @code{SECNDS(X)} gets the time in seconds from the real-time system clock. @var{X} is a reference time, also in seconds. If this is zero, the time in seconds from midnight is returned. This function is non-standard and its use is discouraged. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = SECNDS (X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{T} @tab Shall be of type @code{REAL(4)}. @item @var{X} @tab Shall be of type @code{REAL(4)}. @end multitable @item @emph{Return value}: None @item @emph{Example}: @smallexample program test_secnds integer :: i real(4) :: t1, t2 print *, secnds (0.0) ! seconds since midnight t1 = secnds (0.0) ! reference time do i = 1, 10000000 ! do something end do t2 = secnds (t1) ! elapsed time print *, "Something took ", t2, " seconds." end program test_secnds @end smallexample @end table @node SECOND @section @code{SECOND} --- CPU time function @fnindex SECOND @cindex time, elapsed @cindex elapsed time @table @asis @item @emph{Description}: Returns a @code{REAL(4)} value representing the elapsed CPU time in seconds. This provides the same functionality as the standard @code{CPU_TIME} intrinsic, and is only included for backwards compatibility. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL SECOND(TIME)} @item @code{TIME = SECOND()} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{TIME} @tab Shall be of type @code{REAL(4)}. @end multitable @item @emph{Return value}: In either syntax, @var{TIME} is set to the process's current runtime in seconds. @item @emph{See also}: @ref{CPU_TIME} @end table @node SELECTED_CHAR_KIND @section @code{SELECTED_CHAR_KIND} --- Choose character kind @fnindex SELECTED_CHAR_KIND @cindex character kind @cindex kind, character @table @asis @item @emph{Description}: @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character set named @var{NAME}, if a character set with such a name is supported, or @math{-1} otherwise. Currently, supported character sets include ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646'' (Universal Character Set, UCS-4) which is commonly known as Unicode. @item @emph{Standard}: Fortran 2003 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = SELECTED_CHAR_KIND(NAME)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NAME} @tab Shall be a scalar and of the default character type. @end multitable @item @emph{Example}: @smallexample program character_kind use iso_fortran_env implicit none integer, parameter :: ascii = selected_char_kind ("ascii") integer, parameter :: ucs4 = selected_char_kind ('ISO_10646') character(kind=ascii, len=26) :: alphabet character(kind=ucs4, len=30) :: hello_world alphabet = ascii_"abcdefghijklmnopqrstuvwxyz" hello_world = ucs4_'Hello World and Ni Hao -- ' & // char (int (z'4F60'), ucs4) & // char (int (z'597D'), ucs4) write (*,*) alphabet open (output_unit, encoding='UTF-8') write (*,*) trim (hello_world) end program character_kind @end smallexample @end table @node SELECTED_INT_KIND @section @code{SELECTED_INT_KIND} --- Choose integer kind @fnindex SELECTED_INT_KIND @cindex integer kind @cindex kind, integer @table @asis @item @emph{Description}: @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer type that can represent all values ranging from @math{-10^R} (exclusive) to @math{10^R} (exclusive). If there is no integer kind that accommodates this range, @code{SELECTED_INT_KIND} returns @math{-1}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = SELECTED_INT_KIND(R)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}. @end multitable @item @emph{Example}: @smallexample program large_integers integer,parameter :: k5 = selected_int_kind(5) integer,parameter :: k15 = selected_int_kind(15) integer(kind=k5) :: i5 integer(kind=k15) :: i15 print *, huge(i5), huge(i15) ! The following inequalities are always true print *, huge(i5) >= 10_k5**5-1 print *, huge(i15) >= 10_k15**15-1 end program large_integers @end smallexample @end table @node SELECTED_REAL_KIND @section @code{SELECTED_REAL_KIND} --- Choose real kind @fnindex SELECTED_REAL_KIND @cindex real kind @cindex kind, real @cindex radix, real @table @asis @item @emph{Description}: @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type with decimal precision of at least @code{P} digits, exponent range of at least @code{R}, and with a radix of @code{RADIX}. @item @emph{Standard}: Fortran 95 and later, with @code{RADIX} Fortran 2008 or later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}. @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}. @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}. @end multitable Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall be present; since Fortran 2008, they are assumed to be zero if absent. @item @emph{Return value}: @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of a real data type with decimal precision of at least @code{P} digits, a decimal exponent range of at least @code{R}, and with the requested @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with any radix can be returned. If more than one real data type meet the criteria, the kind of the data type with the smallest decimal precision is returned. If no real data type matches the criteria, the result is @table @asis @item -1 if the processor does not support a real data type with a precision greater than or equal to @code{P}, but the @code{R} and @code{RADIX} requirements can be fulfilled @item -2 if the processor does not support a real type with an exponent range greater than or equal to @code{R}, but @code{P} and @code{RADIX} are fulfillable @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements are fulfillable @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements are fulfillable @item -5 if there is no real type with the given @code{RADIX} @end table @item @emph{See also}: @ref{PRECISION}, @ref{RANGE}, @ref{RADIX} @item @emph{Example}: @smallexample program real_kinds integer,parameter :: p6 = selected_real_kind(6) integer,parameter :: p10r100 = selected_real_kind(10,100) integer,parameter :: r400 = selected_real_kind(r=400) real(kind=p6) :: x real(kind=p10r100) :: y real(kind=r400) :: z print *, precision(x), range(x) print *, precision(y), range(y) print *, precision(z), range(z) end program real_kinds @end smallexample @end table @node SET_EXPONENT @section @code{SET_EXPONENT} --- Set the exponent of the model @fnindex SET_EXPONENT @cindex real number, set exponent @cindex floating point, set exponent @table @asis @item @emph{Description}: @code{SET_EXPONENT(X, I)} returns the real number whose fractional part is that that of @var{X} and whose exponent part is @var{I}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SET_EXPONENT(X, I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL}. @item @var{I} @tab Shall be of type @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X}. The real number whose fractional part is that that of @var{X} and whose exponent part if @var{I} is returned; it is @code{FRACTION(X) * RADIX(X)**I}. @item @emph{Example}: @smallexample PROGRAM test_setexp REAL :: x = 178.1387e-4 INTEGER :: i = 17 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i END PROGRAM @end smallexample @end table @node SHAPE @section @code{SHAPE} --- Determine the shape of an array @fnindex SHAPE @cindex array, shape @table @asis @item @emph{Description}: Determines the shape of an array. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = SHAPE(SOURCE [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SOURCE} @tab Shall be an array or scalar of any type. If @var{SOURCE} is a pointer it must be associated and allocatable arrays must be allocated. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} has dimensions. The elements of the resulting array correspond to the extend of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar, the result is the rank one array of size zero. If @var{KIND} is absent, the return value has the default integer kind otherwise the specified kind. @item @emph{Example}: @smallexample PROGRAM test_shape INTEGER, DIMENSION(-1:1, -1:2) :: A WRITE(*,*) SHAPE(A) ! (/ 3, 4 /) WRITE(*,*) SIZE(SHAPE(42)) ! (/ /) END PROGRAM @end smallexample @item @emph{See also}: @ref{RESHAPE}, @ref{SIZE} @end table @node SHIFTA @section @code{SHIFTA} --- Right shift with fill @fnindex SHIFTA @cindex bits, shift right @cindex shift, right with fill @table @asis @item @emph{Description}: @code{SHIFTA} returns a value corresponding to @var{I} with all of the bits shifted right by @var{SHIFT} places. If the absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. Bits shifted out from the right end are lost. The fill is arithmetic: the bits shifted in from the left end are equal to the leftmost bit, which in two's complement representation is the sign bit. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SHIFTA(I, SHIFT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{SHIFTL}, @ref{SHIFTR} @end table @node SHIFTL @section @code{SHIFTL} --- Left shift @fnindex SHIFTL @cindex bits, shift left @cindex shift, left @table @asis @item @emph{Description}: @code{SHIFTL} returns a value corresponding to @var{I} with all of the bits shifted left by @var{SHIFT} places. If the absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. Bits shifted out from the left end are lost, and bits shifted in from the right end are set to 0. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SHIFTL(I, SHIFT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{SHIFTA}, @ref{SHIFTR} @end table @node SHIFTR @section @code{SHIFTR} --- Right shift @fnindex SHIFTR @cindex bits, shift right @cindex shift, right @table @asis @item @emph{Description}: @code{SHIFTR} returns a value corresponding to @var{I} with all of the bits shifted right by @var{SHIFT} places. If the absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. Bits shifted out from the right end are lost, and bits shifted in from the left end are set to 0. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SHIFTR(I, SHIFT)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be @code{INTEGER}. @item @var{SHIFT} @tab The type shall be @code{INTEGER}. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of the same kind as @var{I}. @item @emph{See also}: @ref{SHIFTA}, @ref{SHIFTL} @end table @node SIGN @section @code{SIGN} --- Sign copying function @fnindex SIGN @fnindex ISIGN @fnindex DSIGN @cindex sign copying @table @asis @item @emph{Description}: @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SIGN(A, B)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL} @item @var{B} @tab Shall be of the same type and kind as @var{A} @end multitable @item @emph{Return value}: The kind of the return value is that of @var{A} and @var{B}. If @math{B\ge 0} then the result is @code{ABS(A)}, else it is @code{-ABS(A)}. @item @emph{Example}: @smallexample program test_sign print *, sign(-12,1) print *, sign(-12,0) print *, sign(-12,-1) print *, sign(-12.,1.) print *, sign(-12.,0.) print *, sign(-12.,-1.) end program test_sign @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Arguments @tab Return type @tab Standard @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu @end multitable @end table @node SIGNAL @section @code{SIGNAL} --- Signal handling subroutine (or function) @fnindex SIGNAL @cindex system, signal handling @table @asis @item @emph{Description}: @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine @var{HANDLER} to be executed with a single integer argument when signal @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to turn off handling of signal @var{NUMBER} or revert to its default action. See @code{signal(2)}. If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument is supplied, it is set to the value returned by @code{signal(2)}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])} @item @code{STATUS = SIGNAL(NUMBER, HANDLER)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)} @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. @code{INTEGER}. It is @code{INTENT(IN)}. @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar integer. It has @code{INTENT(OUT)}. @end multitable @c TODO: What should the interface of the handler be? Does it take arguments? @item @emph{Return value}: The @code{SIGNAL} function returns the value returned by @code{signal(2)}. @item @emph{Example}: @smallexample program test_signal intrinsic signal external handler_print call signal (12, handler_print) call signal (10, 1) call sleep (30) end program test_signal @end smallexample @end table @node SIN @section @code{SIN} --- Sine function @fnindex SIN @fnindex DSIN @fnindex CSIN @fnindex ZSIN @fnindex CDSIN @cindex trigonometric function, sine @cindex sine @table @asis @item @emph{Description}: @code{SIN(X)} computes the sine of @var{X}. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SIN(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value has same type and kind as @var{X}. @item @emph{Example}: @smallexample program test_sin real :: x = 0.0 x = sin(x) end program test_sin @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu @end multitable @item @emph{See also}: @ref{ASIN} @end table @node SINH @section @code{SINH} --- Hyperbolic sine function @fnindex SINH @fnindex DSINH @cindex hyperbolic sine @cindex hyperbolic function, sine @cindex sine, hyperbolic @table @asis @item @emph{Description}: @code{SINH(X)} computes the hyperbolic sine of @var{X}. @item @emph{Standard}: Fortran 95 and later, for a complex argument Fortran 2008 or later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SINH(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value has same type and kind as @var{X}. @item @emph{Example}: @smallexample program test_sinh real(8) :: x = - 1.0_8 x = sinh(x) end program test_sinh @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later @end multitable @item @emph{See also}: @ref{ASINH} @end table @node SIZE @section @code{SIZE} --- Determine the size of an array @fnindex SIZE @cindex array, size @cindex array, number of elements @cindex array, count elements @table @asis @item @emph{Description}: Determine the extent of @var{ARRAY} along a specified dimension @var{DIM}, or the total number of elements in @var{ARRAY} if @var{DIM} is absent. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is a pointer it must be associated and allocatable arrays must be allocated. @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} and its value shall be in the range from 1 to n, where n equals the rank of @var{ARRAY}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. @item @emph{Example}: @smallexample PROGRAM test_size WRITE(*,*) SIZE((/ 1, 2 /)) ! 2 END PROGRAM @end smallexample @item @emph{See also}: @ref{SHAPE}, @ref{RESHAPE} @end table @node SIZEOF @section @code{SIZEOF} --- Size in bytes of an expression @fnindex SIZEOF @cindex expression size @cindex size of an expression @table @asis @item @emph{Description}: @code{SIZEOF(X)} calculates the number of bytes of storage the expression @code{X} occupies. @item @emph{Standard}: GNU extension @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{N = SIZEOF(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The argument shall be of any type, rank or shape. @end multitable @item @emph{Return value}: The return value is of type integer and of the system-dependent kind @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the number of bytes occupied by the argument. If the argument has the @code{POINTER} attribute, the number of bytes of the storage area pointed to is returned. If the argument is of a derived type with @code{POINTER} or @code{ALLOCATABLE} components, the return value does not account for the sizes of the data pointed to by these components. If the argument is polymorphic, the size according to the dynamic type is returned. The argument may not be a procedure or procedure pointer. Note that the code assumes for arrays that those are contiguous; for contiguous arrays, it returns the storage or an array element multiplied by the size of the array. @item @emph{Example}: @smallexample integer :: i real :: r, s(5) print *, (sizeof(s)/sizeof(r) == 5) end @end smallexample The example will print @code{.TRUE.} unless you are using a platform where default @code{REAL} variables are unusually padded. @item @emph{See also}: @ref{C_SIZEOF}, @ref{STORAGE_SIZE} @end table @node SLEEP @section @code{SLEEP} --- Sleep for the specified number of seconds @fnindex SLEEP @cindex delayed execution @table @asis @item @emph{Description}: Calling this subroutine causes the process to pause for @var{SECONDS} seconds. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL SLEEP(SECONDS)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}. @end multitable @item @emph{Example}: @smallexample program test_sleep call sleep(5) end @end smallexample @end table @node SPACING @section @code{SPACING} --- Smallest distance between two numbers of a given type @fnindex SPACING @cindex real number, relative spacing @cindex floating point, relative spacing @table @asis @item @emph{Description}: Determines the distance between the argument @var{X} and the nearest adjacent number of the same type. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SPACING(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL}. @end multitable @item @emph{Return value}: The result is of the same type as the input argument @var{X}. @item @emph{Example}: @smallexample PROGRAM test_spacing INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37) INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200) WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686 END PROGRAM @end smallexample @item @emph{See also}: @ref{RRSPACING} @end table @node SPREAD @section @code{SPREAD} --- Add a dimension to an array @fnindex SPREAD @cindex array, increase dimension @cindex array, duplicate elements @cindex array, duplicate dimensions @table @asis @item @emph{Description}: Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified dimension @var{DIM}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and a rank less than seven. @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}. @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}. @end multitable @item @emph{Return value}: The result is an array of the same type as @var{SOURCE} and has rank n+1 where n equals the rank of @var{SOURCE}. @item @emph{Example}: @smallexample PROGRAM test_spread INTEGER :: a = 1, b(2) = (/ 1, 2 /) WRITE(*,*) SPREAD(A, 1, 2) ! "1 1" WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2" END PROGRAM @end smallexample @item @emph{See also}: @ref{UNPACK} @end table @node SQRT @section @code{SQRT} --- Square-root function @fnindex SQRT @fnindex DSQRT @fnindex CSQRT @fnindex ZSQRT @fnindex CDSQRT @cindex root @cindex square-root @table @asis @item @emph{Description}: @code{SQRT(X)} computes the square root of @var{X}. @item @emph{Standard}: Fortran 77 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = SQRT(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value is of type @code{REAL} or @code{COMPLEX}. The kind type parameter is the same as @var{X}. @item @emph{Example}: @smallexample program test_sqrt real(8) :: x = 2.0_8 complex :: z = (1.0, 2.0) x = sqrt(x) z = sqrt(z) end program test_sqrt @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension @end multitable @end table @node SRAND @section @code{SRAND} --- Reinitialize the random number generator @fnindex SRAND @cindex random number generation, seeding @cindex seeding a random number generator @table @asis @item @emph{Description}: @code{SRAND} reinitializes the pseudo-random number generator called by @code{RAND} and @code{IRAND}. The new seed used by the generator is specified by the required argument @var{SEED}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL SRAND(SEED)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}. @end multitable @item @emph{Return value}: Does not return anything. @item @emph{Example}: See @code{RAND} and @code{IRAND} for examples. @item @emph{Notes}: The Fortran standard specifies the intrinsic subroutines @code{RANDOM_SEED} to initialize the pseudo-random number generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers. These subroutines should be used in new codes. Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND}, @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and @code{RANDOM_SEED} on the other hand) access two independent pseudo-random number generators. @item @emph{See also}: @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER} @end table @node STAT @section @code{STAT} --- Get file status @fnindex STAT @cindex file system, file status @table @asis @item @emph{Description}: This function returns information about a file. No permissions are required on the file itself, but execute (search) permission is required on all of the directories in path that lead to the file. The elements that are obtained and stored in the array @code{VALUES}: @multitable @columnfractions .15 .70 @item @code{VALUES(1)} @tab Device ID @item @code{VALUES(2)} @tab Inode number @item @code{VALUES(3)} @tab File mode @item @code{VALUES(4)} @tab Number of links @item @code{VALUES(5)} @tab Owner's uid @item @code{VALUES(6)} @tab Owner's gid @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available) @item @code{VALUES(8)} @tab File size (bytes) @item @code{VALUES(9)} @tab Last access time @item @code{VALUES(10)} @tab Last modification time @item @code{VALUES(11)} @tab Last file status change time @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available) @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available) @end multitable Not all these elements are relevant on all systems. If an element is not relevant, it is returned as 0. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL STAT(NAME, VALUES [, STATUS])} @item @code{STATUS = STAT(NAME, VALUES)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the default kind and a valid path within the file system. @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}. @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 on success and a system specific error code otherwise. @end multitable @item @emph{Example}: @smallexample PROGRAM test_stat INTEGER, DIMENSION(13) :: buff INTEGER :: status CALL STAT("/etc/passwd", buff, status) IF (status == 0) THEN WRITE (*, FMT="('Device ID:', T30, I19)") buff(1) WRITE (*, FMT="('Inode number:', T30, I19)") buff(2) WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3) WRITE (*, FMT="('Number of links:', T30, I19)") buff(4) WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5) WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6) WRITE (*, FMT="('Device where located:', T30, I19)") buff(7) WRITE (*, FMT="('File size:', T30, I19)") buff(8) WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9)) WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10)) WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11)) WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12) WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13) END IF END PROGRAM @end smallexample @item @emph{See also}: To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT} @end table @node STORAGE_SIZE @section @code{STORAGE_SIZE} --- Storage size in bits @fnindex STORAGE_SIZE @cindex storage size @table @asis @item @emph{Description}: Returns the storage size of argument @var{A} in bits. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = STORAGE_SIZE(A [, KIND])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{A} @tab Shall be a scalar or array of any type. @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression. @end multitable @item @emph{Return Value}: The result is a scalar integer with the kind type parameter specified by KIND (or default integer type if KIND is missing). The result value is the size expressed in bits for an element of an array that has the dynamic type and type parameters of A. @item @emph{See also}: @ref{C_SIZEOF}, @ref{SIZEOF} @end table @node SUM @section @code{SUM} --- Sum of array elements @fnindex SUM @cindex array, sum @cindex array, add elements @cindex array, conditionally add elements @cindex sum array elements @table @asis @item @emph{Description}: Adds the elements of @var{ARRAY} along dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = SUM(ARRAY[, MASK])} @item @code{RESULT = SUM(ARRAY, DIM[, MASK])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}, @code{REAL} or @code{COMPLEX}. @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER} with a value in the range from 1 to n, where n equals the rank of @var{ARRAY}. @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL} and either be a scalar or an array of the same shape as @var{ARRAY}. @end multitable @item @emph{Return value}: The result is of the same type as @var{ARRAY}. If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped is returned. @item @emph{Example}: @smallexample PROGRAM test_sum INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /) print *, SUM(x) ! all elements, sum = 15 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9 END PROGRAM @end smallexample @item @emph{See also}: @ref{PRODUCT} @end table @node SYMLNK @section @code{SYMLNK} --- Create a symbolic link @fnindex SYMLNK @cindex file system, create link @cindex file system, soft link @table @asis @item @emph{Description}: Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null character (@code{CHAR(0)}) can be used to mark the end of the names in @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file names are ignored. If the @var{STATUS} argument is supplied, it contains 0 on success or a nonzero error code upon return; see @code{symlink(2)}. If the system does not supply @code{symlink(2)}, @code{ENOSYS} is returned. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])} @item @code{STATUS = SYMLNK(PATH1, PATH2)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type. @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type. @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. @end multitable @item @emph{See also}: @ref{LINK}, @ref{UNLINK} @end table @node SYSTEM @section @code{SYSTEM} --- Execute a shell command @fnindex SYSTEM @cindex system, system call @table @asis @item @emph{Description}: Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If argument @var{STATUS} is present, it contains the value returned by @code{system(3)}, which is presumably 0 if the shell command succeeded. Note that which shell is used to invoke the command is system-dependent and environment-dependent. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. Note that the @code{system} function need not be thread-safe. It is the responsibility of the user to ensure that @code{system} is not called concurrently. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL SYSTEM(COMMAND [, STATUS])} @item @code{STATUS = SYSTEM(COMMAND)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type. @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. @end multitable @item @emph{See also}: @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard and should considered in new code for future portability. @end table @node SYSTEM_CLOCK @section @code{SYSTEM_CLOCK} --- Time function @fnindex SYSTEM_CLOCK @cindex time, clock ticks @cindex clock ticks @table @asis @item @emph{Description}: Determines the @var{COUNT} of a processor clock since an unspecified time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines the number of clock ticks per second. If the platform supports a monotonic clock, that clock is used and can, depending on the platform clock implementation, provide up to nanosecond resolution. If a monotonic clock is not available, the implementation falls back to a realtime clock. @var{COUNT_RATE} is system dependent and can vary depending on the kind of the arguments. For @var{kind=4} arguments (and smaller integer kinds), @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and larger integer kinds), @var{COUNT} typically represents micro- or nanoseconds depending on resolution of the underlying platform clock. @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the millisecond resolution of the @var{kind=4} version implies that the @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues with the wrap around and for more precise timing, please use the @var{kind=8} version. If there is no clock, or querying the clock fails, @var{COUNT} is set to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero. When running on a platform using the GNU C library (glibc) version 2.16 or older, or a derivative thereof, the high resolution monotonic clock is available only when linking with the @var{rt} library. This can be done explicitly by adding the @code{-lrt} flag when linking the application, but is also done implicitly when using OpenMP. On the Windows platform, the version with @var{kind=4} arguments uses the @code{GetTickCount} function, whereas the @var{kind=8} version uses @code{QueryPerformanceCounter} and @code{QueryPerformanceCounterFrequency}. For more information, and potential caveats, please see the platform documentation. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Subroutine @item @emph{Syntax}: @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{COUNT} @tab (Optional) shall be a scalar of type @code{INTEGER} with @code{INTENT(OUT)}. @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}. @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type @code{INTEGER} with @code{INTENT(OUT)}. @end multitable @item @emph{Example}: @smallexample PROGRAM test_system_clock INTEGER :: count, count_rate, count_max CALL SYSTEM_CLOCK(count, count_rate, count_max) WRITE(*,*) count, count_rate, count_max END PROGRAM @end smallexample @item @emph{See also}: @ref{DATE_AND_TIME}, @ref{CPU_TIME} @end table @node TAN @section @code{TAN} --- Tangent function @fnindex TAN @fnindex DTAN @cindex trigonometric function, tangent @cindex tangent @table @asis @item @emph{Description}: @code{TAN(X)} computes the tangent of @var{X}. @item @emph{Standard}: Fortran 77 and later, for a complex argument Fortran 2008 or later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = TAN(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value has same type and kind as @var{X}. @item @emph{Example}: @smallexample program test_tan real(8) :: x = 0.165_8 x = tan(x) end program test_tan @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later @end multitable @item @emph{See also}: @ref{ATAN} @end table @node TANH @section @code{TANH} --- Hyperbolic tangent function @fnindex TANH @fnindex DTANH @cindex hyperbolic tangent @cindex hyperbolic function, tangent @cindex tangent, hyperbolic @table @asis @item @emph{Description}: @code{TANH(X)} computes the hyperbolic tangent of @var{X}. @item @emph{Standard}: Fortran 77 and later, for a complex argument Fortran 2008 or later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{X = TANH(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}. @end multitable @item @emph{Return value}: The return value has same type and kind as @var{X}. If @var{X} is complex, the imaginary part of the result is in radians. If @var{X} is @code{REAL}, the return value lies in the range @math{ - 1 \leq tanh(x) \leq 1 }. @item @emph{Example}: @smallexample program test_tanh real(8) :: x = 2.1_8 x = tanh(x) end program test_tanh @end smallexample @item @emph{Specific names}: @multitable @columnfractions .20 .20 .20 .25 @item Name @tab Argument @tab Return type @tab Standard @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later @end multitable @item @emph{See also}: @ref{ATANH} @end table @node THIS_IMAGE @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image @fnindex THIS_IMAGE @cindex coarray, @code{THIS_IMAGE} @cindex images, index of this image @table @asis @item @emph{Description}: Returns the cosubscript for this image. @item @emph{Standard}: Fortran 2008 and later. With @var{DISTANCE} argument, Technical Specification (TS) 18508 or later @item @emph{Class}: Transformational function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{RESULT = THIS_IMAGE()} @item @code{RESULT = THIS_IMAGE(DISTANCE)} @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer (not permitted together with @var{COARRAY}). @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM} present, required). @item @var{DIM} @tab default integer scalar (optional). If present, @var{DIM} shall be between one and the corank of @var{COARRAY}. @end multitable @item @emph{Return value}: Default integer. If @var{COARRAY} is not present, it is scalar; if @var{DISTANCE} is not present or has value 0, its value is the image index on the invoking image for the current team, for values smaller or equal distance to the initial team, it returns the image index on the ancestor team which has a distance of @var{DISTANCE} from the invoking team. If @var{DISTANCE} is larger than the distance to the initial team, the image index of the initial team is returned. Otherwise when the @var{COARRAY} is present, if @var{DIM} is not present, a rank-1 array with corank elements is returned, containing the cosubscripts for @var{COARRAY} specifying the invoking image. If @var{DIM} is present, a scalar is returned, with the value of the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}. @item @emph{Example}: @smallexample INTEGER :: value[*] INTEGER :: i value = THIS_IMAGE() SYNC ALL IF (THIS_IMAGE() == 1) THEN DO i = 1, NUM_IMAGES() WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i] END DO END IF ! Check whether the current image is the initial image IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE()) error stop "something is rotten here" @end smallexample @item @emph{See also}: @ref{NUM_IMAGES}, @ref{IMAGE_INDEX} @end table @node TIME @section @code{TIME} --- Time function @fnindex TIME @cindex time, current @cindex current time @table @asis @item @emph{Description}: Returns the current time encoded as an integer (in the manner of the function @code{time(3)} in the C standard library). This value is suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}. This intrinsic is not fully portable, such as to systems with 32-bit @code{INTEGER} types but supporting times wider than 32 bits. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program. See @ref{TIME8}, for information on a similar intrinsic that might be portable to more GNU Fortran implementations, though to fewer Fortran compilers. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = TIME()} @item @emph{Return value}: The return value is a scalar of type @code{INTEGER(4)}. @item @emph{See also}: @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8} @end table @node TIME8 @section @code{TIME8} --- Time function (64-bit) @fnindex TIME8 @cindex time, current @cindex current time @table @asis @item @emph{Description}: Returns the current time encoded as an integer (in the manner of the function @code{time(3)} in the C standard library). This value is suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}. @emph{Warning:} this intrinsic does not increase the range of the timing values over that returned by @code{time(3)}. On a system with a 32-bit @code{time(3)}, @code{TIME8} will return a 32-bit value, even though it is converted to a 64-bit @code{INTEGER(8)} value. That means overflows of the 32-bit value can still occur. Therefore, the values returned by this intrinsic might be or become negative or numerically less than previous values during a single run of the compiled program. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = TIME8()} @item @emph{Return value}: The return value is a scalar of type @code{INTEGER(8)}. @item @emph{See also}: @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME} @end table @node TINY @section @code{TINY} --- Smallest positive number of a real kind @fnindex TINY @cindex limits, smallest number @cindex model representation, smallest number @table @asis @item @emph{Description}: @code{TINY(X)} returns the smallest positive (non zero) number in the model of the type of @code{X}. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = TINY(X)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{X} @tab Shall be of type @code{REAL}. @end multitable @item @emph{Return value}: The return value is of the same type and kind as @var{X} @item @emph{Example}: See @code{HUGE} for an example. @end table @node TRAILZ @section @code{TRAILZ} --- Number of trailing zero bits of an integer @fnindex TRAILZ @cindex zero bits @table @asis @item @emph{Description}: @code{TRAILZ} returns the number of trailing zero bits of an integer. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = TRAILZ(I)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab Shall be of type @code{INTEGER}. @end multitable @item @emph{Return value}: The type of the return value is the default @code{INTEGER}. If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}. @item @emph{Example}: @smallexample PROGRAM test_trailz WRITE (*,*) TRAILZ(8) ! prints 3 END PROGRAM @end smallexample @item @emph{See also}: @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT} @end table @node TRANSFER @section @code{TRANSFER} --- Transfer bit patterns @fnindex TRANSFER @cindex bits, move @cindex type cast @table @asis @item @emph{Description}: Interprets the bitwise representation of @var{SOURCE} in memory as if it is the representation of a variable or array of the same type and type parameters as @var{MOLD}. This is approximately equivalent to the C concept of @emph{casting} one type to another. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{SOURCE} @tab Shall be a scalar or an array of any type. @item @var{MOLD} @tab Shall be a scalar or an array of any type. @item @var{SIZE} @tab (Optional) shall be a scalar of type @code{INTEGER}. @end multitable @item @emph{Return value}: The result has the same type as @var{MOLD}, with the bit level representation of @var{SOURCE}. If @var{SIZE} is present, the result is a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent but @var{MOLD} is an array (of any size or shape), the result is a one- dimensional array of the minimum length needed to contain the entirety of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent and @var{MOLD} is a scalar, the result is a scalar. If the bitwise representation of the result is longer than that of @var{SOURCE}, then the leading bits of the result correspond to those of @var{SOURCE} and any trailing bits are filled arbitrarily. When the resulting bit representation does not correspond to a valid representation of a variable of the same type as @var{MOLD}, the results are undefined, and subsequent operations on the result cannot be guaranteed to produce sensible behavior. For example, it is possible to create @code{LOGICAL} variables for which @code{@var{VAR}} and @code{.NOT.@var{VAR}} both appear to be true. @item @emph{Example}: @smallexample PROGRAM test_transfer integer :: x = 2143289344 print *, transfer(x, 1.0) ! prints "NaN" on i686 END PROGRAM @end smallexample @end table @node TRANSPOSE @section @code{TRANSPOSE} --- Transpose an array of rank two @fnindex TRANSPOSE @cindex array, transpose @cindex matrix, transpose @cindex transpose @table @asis @item @emph{Description}: Transpose an array of rank two. Element (i, j) of the result has the value @code{MATRIX(j, i)}, for all i, j. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = TRANSPOSE(MATRIX)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two. @end multitable @item @emph{Return value}: The result has the same type as @var{MATRIX}, and has shape @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}. @end table @node TRIM @section @code{TRIM} --- Remove trailing blank characters of a string @fnindex TRIM @cindex string, remove trailing whitespace @table @asis @item @emph{Description}: Removes trailing blank characters of a string. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = TRIM(STRING)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}. @end multitable @item @emph{Return value}: A scalar of type @code{CHARACTER} which length is that of @var{STRING} less the number of trailing blanks. @item @emph{Example}: @smallexample PROGRAM test_trim CHARACTER(len=10), PARAMETER :: s = "GFORTRAN " WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks END PROGRAM @end smallexample @item @emph{See also}: @ref{ADJUSTL}, @ref{ADJUSTR} @end table @node TTYNAM @section @code{TTYNAM} --- Get the name of a terminal device. @fnindex TTYNAM @cindex system, terminal @table @asis @item @emph{Description}: Get the name of a terminal device. For more information, see @code{ttyname(3)}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL TTYNAM(UNIT, NAME)} @item @code{NAME = TTYNAM(UNIT)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}. @item @var{NAME} @tab Shall be of type @code{CHARACTER}. @end multitable @item @emph{Example}: @smallexample PROGRAM test_ttynam INTEGER :: unit DO unit = 1, 10 IF (isatty(unit=unit)) write(*,*) ttynam(unit) END DO END PROGRAM @end smallexample @item @emph{See also}: @ref{ISATTY} @end table @node UBOUND @section @code{UBOUND} --- Upper dimension bounds of an array @fnindex UBOUND @cindex array, upper bound @table @asis @item @emph{Description}: Returns the upper bounds of an array, or a single upper bound along the @var{DIM} dimension. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an array, of any type. @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. If @var{DIM} is absent, the result is an array of the upper bounds of @var{ARRAY}. If @var{DIM} is present, the result is a scalar corresponding to the upper bound of the array along that dimension. If @var{ARRAY} is an expression rather than a whole array or array structure component, or if it has a zero extent along the relevant dimension, the upper bound is taken to be the number of elements along the relevant dimension. @item @emph{See also}: @ref{LBOUND}, @ref{LCOBOUND} @end table @node UCOBOUND @section @code{UCOBOUND} --- Upper codimension bounds of an array @fnindex UCOBOUND @cindex coarray, upper bound @table @asis @item @emph{Description}: Returns the upper cobounds of a coarray, or a single upper cobound along the @var{DIM} codimension. @item @emph{Standard}: Fortran 2008 and later @item @emph{Class}: Inquiry function @item @emph{Syntax}: @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{ARRAY} @tab Shall be an coarray, of any type. @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. If @var{DIM} is absent, the result is an array of the lower cobounds of @var{COARRAY}. If @var{DIM} is present, the result is a scalar corresponding to the lower cobound of the array along that codimension. @item @emph{See also}: @ref{LCOBOUND}, @ref{LBOUND} @end table @node UMASK @section @code{UMASK} --- Set the file creation mask @fnindex UMASK @cindex file system, file creation mask @table @asis @item @emph{Description}: Sets the file creation mask to @var{MASK}. If called as a function, it returns the old value. If called as a subroutine and argument @var{OLD} if it is supplied, it is set to the old value. See @code{umask(2)}. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL UMASK(MASK [, OLD])} @item @code{OLD = UMASK(MASK)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}. @item @var{OLD} @tab (Optional) Shall be a scalar of type @code{INTEGER}. @end multitable @end table @node UNLINK @section @code{UNLINK} --- Remove a file from the file system @fnindex UNLINK @cindex file system, remove file @table @asis @item @emph{Description}: Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be used to mark the end of the name in @var{PATH}; otherwise, trailing blanks in the file name are ignored. If the @var{STATUS} argument is supplied, it contains 0 on success or a nonzero error code upon return; see @code{unlink(2)}. This intrinsic is provided in both subroutine and function forms; however, only one form can be used in any given program unit. @item @emph{Standard}: GNU extension @item @emph{Class}: Subroutine, function @item @emph{Syntax}: @multitable @columnfractions .80 @item @code{CALL UNLINK(PATH [, STATUS])} @item @code{STATUS = UNLINK(PATH)} @end multitable @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type. @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type. @end multitable @item @emph{See also}: @ref{LINK}, @ref{SYMLNK} @end table @node UNPACK @section @code{UNPACK} --- Unpack an array of rank one into an array @fnindex UNPACK @cindex array, unpacking @cindex array, increase dimension @cindex array, scatter elements @table @asis @item @emph{Description}: Store the elements of @var{VECTOR} in an array of higher rank. @item @emph{Standard}: Fortran 95 and later @item @emph{Class}: Transformational function @item @emph{Syntax}: @code{RESULT = UNPACK(VECTOR, MASK, FIELD)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It shall have at least as many elements as @var{MASK} has @code{TRUE} values. @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}. @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have the same shape as @var{MASK}. @end multitable @item @emph{Return value}: The resulting array corresponds to @var{FIELD} with @code{TRUE} elements of @var{MASK} replaced by values from @var{VECTOR} in array element order. @item @emph{Example}: @smallexample PROGRAM test_unpack integer :: vector(2) = (/1,1/) logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /) integer :: field(2,2) = 0, unity(2,2) ! result: unity matrix unity = unpack(vector, reshape(mask, (/2,2/)), field) END PROGRAM @end smallexample @item @emph{See also}: @ref{PACK}, @ref{SPREAD} @end table @node VERIFY @section @code{VERIFY} --- Scan a string for characters not a given set @fnindex VERIFY @cindex string, find missing set @table @asis @item @emph{Description}: Verifies that all the characters in @var{STRING} belong to the set of characters in @var{SET}. If @var{BACK} is either absent or equals @code{FALSE}, this function returns the position of the leftmost character of @var{STRING} that is not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position is returned. If all characters of @var{STRING} are found in @var{SET}, the result is zero. @item @emph{Standard}: Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later @item @emph{Class}: Elemental function @item @emph{Syntax}: @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{STRING} @tab Shall be of type @code{CHARACTER}. @item @var{SET} @tab Shall be of type @code{CHARACTER}. @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}. @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization expression indicating the kind parameter of the result. @end multitable @item @emph{Return value}: The return value is of type @code{INTEGER} and of kind @var{KIND}. If @var{KIND} is absent, the return value is of default integer kind. @item @emph{Example}: @smallexample PROGRAM test_verify WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F' WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R' WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F' WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N' WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none END PROGRAM @end smallexample @item @emph{See also}: @ref{SCAN}, @ref{INDEX intrinsic} @end table @node XOR @section @code{XOR} --- Bitwise logical exclusive OR @fnindex XOR @cindex bitwise logical exclusive or @cindex logical exclusive or, bitwise @table @asis @item @emph{Description}: Bitwise logical exclusive or. This intrinsic routine is provided for backwards compatibility with GNU Fortran 77. For integer arguments, programmers should consider the use of the @ref{IEOR} intrinsic and for logical arguments the @code{.NEQV.} operator, which are both defined by the Fortran standard. @item @emph{Standard}: GNU extension @item @emph{Class}: Function @item @emph{Syntax}: @code{RESULT = XOR(I, J)} @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{I} @tab The type shall be either a scalar @code{INTEGER} type or a scalar @code{LOGICAL} type. @item @var{J} @tab The type shall be the same as the type of @var{I}. @end multitable @item @emph{Return value}: The return type is either a scalar @code{INTEGER} or a scalar @code{LOGICAL}. If the kind type parameters differ, then the smaller kind type is implicitly converted to larger kind, and the return has the larger kind. @item @emph{Example}: @smallexample PROGRAM test_xor LOGICAL :: T = .TRUE., F = .FALSE. INTEGER :: a, b DATA a / Z'F' /, b / Z'3' / WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F) WRITE (*,*) XOR(a, b) END PROGRAM @end smallexample @item @emph{See also}: Fortran 95 elemental function: @ref{IEOR} @end table @node Intrinsic Modules @chapter Intrinsic Modules @cindex intrinsic Modules @menu * ISO_FORTRAN_ENV:: * ISO_C_BINDING:: * IEEE modules:: * OpenMP Modules OMP_LIB and OMP_LIB_KINDS:: * OpenACC Module OPENACC:: @end menu @node ISO_FORTRAN_ENV @section @code{ISO_FORTRAN_ENV} @table @asis @item @emph{Standard}: Fortran 2003 and later, except when otherwise noted @end table The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer named constants: @table @asis @item @code{ATOMIC_INT_KIND}: Default-kind integer constant to be used as kind parameter when defining integer variables used in atomic operations. (Fortran 2008 or later.) @item @code{ATOMIC_LOGICAL_KIND}: Default-kind integer constant to be used as kind parameter when defining logical variables used in atomic operations. (Fortran 2008 or later.) @item @code{CHARACTER_KINDS}: Default-kind integer constant array of rank one containing the supported kind parameters of the @code{CHARACTER} type. (Fortran 2008 or later.) @item @code{CHARACTER_STORAGE_SIZE}: Size in bits of the character storage unit. @item @code{ERROR_UNIT}: Identifies the preconnected unit used for error reporting. @item @code{FILE_STORAGE_SIZE}: Size in bits of the file-storage unit. @item @code{INPUT_UNIT}: Identifies the preconnected unit identified by the asterisk (@code{*}) in @code{READ} statement. @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}: Kind type parameters to specify an INTEGER type with a storage size of 16, 32, and 64 bits. It is negative if a target platform does not support the particular kind. (Fortran 2008 or later.) @item @code{INTEGER_KINDS}: Default-kind integer constant array of rank one containing the supported kind parameters of the @code{INTEGER} type. (Fortran 2008 or later.) @item @code{IOSTAT_END}: The value assigned to the variable passed to the @code{IOSTAT=} specifier of an input/output statement if an end-of-file condition occurred. @item @code{IOSTAT_EOR}: The value assigned to the variable passed to the @code{IOSTAT=} specifier of an input/output statement if an end-of-record condition occurred. @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}: Scalar default-integer constant, used by @code{INQUIRE} for the @code{IOSTAT=} specifier to denote an that a unit number identifies an internal unit. (Fortran 2008 or later.) @item @code{NUMERIC_STORAGE_SIZE}: The size in bits of the numeric storage unit. @item @code{LOGICAL_KINDS}: Default-kind integer constant array of rank one containing the supported kind parameters of the @code{LOGICAL} type. (Fortran 2008 or later.) @item @code{OUTPUT_UNIT}: Identifies the preconnected unit identified by the asterisk (@code{*}) in @code{WRITE} statement. @item @code{REAL32}, @code{REAL64}, @code{REAL128}: Kind type parameters to specify a REAL type with a storage size of 32, 64, and 128 bits. It is negative if a target platform does not support the particular kind. (Fortran 2008 or later.) @item @code{REAL_KINDS}: Default-kind integer constant array of rank one containing the supported kind parameters of the @code{REAL} type. (Fortran 2008 or later.) @item @code{STAT_LOCKED}: Scalar default-integer constant used as STAT= return value by @code{LOCK} to denote that the lock variable is locked by the executing image. (Fortran 2008 or later.) @item @code{STAT_LOCKED_OTHER_IMAGE}: Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to denote that the lock variable is locked by another image. (Fortran 2008 or later.) @item @code{STAT_STOPPED_IMAGE}: Positive, scalar default-integer constant used as STAT= return value if the argument in the statement requires synchronisation with an image, which has initiated the termination of the execution. (Fortran 2008 or later.) @item @code{STAT_FAILED_IMAGE}: Positive, scalar default-integer constant used as STAT= return value if the argument in the statement requires communication with an image, which has is in the failed state. (TS 18508 or later.) @item @code{STAT_UNLOCKED}: Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to denote that the lock variable is unlocked. (Fortran 2008 or later.) @end table The module provides the following derived type: @table @asis @item @code{LOCK_TYPE}: Derived type with private components to be use with the @code{LOCK} and @code{UNLOCK} statement. A variable of its type has to be always declared as coarray and may not appear in a variable-definition context. (Fortran 2008 or later.) @end table The module also provides the following intrinsic procedures: @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}. @node ISO_C_BINDING @section @code{ISO_C_BINDING} @table @asis @item @emph{Standard}: Fortran 2003 and later, GNU extensions @end table The following intrinsic procedures are provided by the module; their definition can be found in the section Intrinsic Procedures of this manual. @table @asis @item @code{C_ASSOCIATED} @item @code{C_F_POINTER} @item @code{C_F_PROCPOINTER} @item @code{C_FUNLOC} @item @code{C_LOC} @item @code{C_SIZEOF} @end table @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF, @c don't really know why. The @code{ISO_C_BINDING} module provides the following named constants of type default integer, which can be used as KIND type parameters. In addition to the integer named constants required by the Fortran 2003 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an extension named constants for the 128-bit integer types supported by the C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}. Furthermore, if @code{__float128} is supported in C, the named constants @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined. @multitable @columnfractions .15 .35 .35 .35 @item Fortran Type @tab Named constant @tab C type @tab Extension @item @code{INTEGER}@tab @code{C_INT} @tab @code{int} @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int} @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int} @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int} @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char} @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t} @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t} @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t} @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t} @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t} @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext. @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t} @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t} @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t} @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t} @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext. @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t} @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t} @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t} @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t} @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext. @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t} @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t} @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float} @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double} @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double} @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext. @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex} @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex} @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex} @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext. @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool} @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char} @end multitable Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)} are defined. @multitable @columnfractions .20 .45 .15 @item Name @tab C definition @tab Value @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'} @item @code{C_ALERT} @tab alert @tab @code{'\a'} @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'} @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'} @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'} @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'} @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'} @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'} @end multitable Moreover, the following two named constants are defined: @multitable @columnfractions .20 .80 @item Name @tab Type @item @code{C_NULL_PTR} @tab @code{C_PTR} @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR} @end multitable Both are equivalent to the value @code{NULL} in C. @node IEEE modules @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} @table @asis @item @emph{Standard}: Fortran 2003 and later @end table The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES} intrinsic modules provide support for exceptions and IEEE arithmetic, as defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard (@emph{Binary floating-point arithmetic for microprocessor systems}). These modules are only provided on the following supported platforms: @itemize @bullet @item i386 and x86_64 processors @item platforms which use the GNU C Library (glibc) @item platforms with support for SysV/386 routines for floating point interface (including Solaris and BSDs) @item platforms with the AIX OS @end itemize For full compliance with the Fortran standards, code using the @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled with the following options: @code{-fno-unsafe-math-optimizations -frounding-math -fsignaling-nans}. @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS} @table @asis @item @emph{Standard}: OpenMP Application Program Interface v4.0 @end table The OpenMP Fortran runtime library routines are provided both in a form of two Fortran 90 modules, named @code{OMP_LIB} and @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing Runtime Library} manual, the named constants defined in the modules are listed below. For details refer to the actual @uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf, OpenMP Application Program Interface v4.0}. @code{OMP_LIB_KINDS} provides the following scalar default-integer named constants: @table @asis @item @code{omp_lock_kind} @item @code{omp_nest_lock_kind} @item @code{omp_proc_bind_kind} @item @code{omp_sched_kind} @end table @code{OMP_LIB} provides the scalar default-integer named constant @code{openmp_version} with a value of the form @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month of the OpenMP version; for OpenMP v4.0 the value is @code{201307}. The following scalar integer named constants of the kind @code{omp_sched_kind}: @table @asis @item @code{omp_sched_static} @item @code{omp_sched_dynamic} @item @code{omp_sched_guided} @item @code{omp_sched_auto} @end table And the following scalar integer named constants of the kind @code{omp_proc_bind_kind}: @table @asis @item @code{omp_proc_bind_false} @item @code{omp_proc_bind_true} @item @code{omp_proc_bind_master} @item @code{omp_proc_bind_close} @item @code{omp_proc_bind_spread} @end table @node OpenACC Module OPENACC @section OpenACC Module @code{OPENACC} @table @asis @item @emph{Standard}: OpenACC Application Programming Interface v2.0 @end table The OpenACC Fortran runtime library routines are provided both in a form of a Fortran 90 module, named @code{OPENACC}, and in form of a Fortran @code{include} file named @file{openacc_lib.h}. The procedures provided by @code{OPENACC} can be found in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing Runtime Library} manual, the named constants defined in the modules are listed below. For details refer to the actual @uref{http://www.openacc.org/, OpenACC Application Programming Interface v2.0}. @code{OPENACC} provides the scalar default-integer named constant @code{openacc_version} with a value of the form @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.