Mercurial > hg > CbC > CbC_gcc
diff gcc/fortran/intrinsic.texi @ 111:04ced10e8804
gcc 7
author | kono |
---|---|
date | Fri, 27 Oct 2017 22:46:09 +0900 |
parents | |
children | 84e7813d76e9 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/gcc/fortran/intrinsic.texi Fri Oct 27 22:46:09 2017 +0900 @@ -0,0 +1,14875 @@ +@ignore +Copyright (C) 2005-2017 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\acosd{\mathop{\rm acosd}\nolimits} +\gdef\asind{\mathop{\rm asind}\nolimits} +\gdef\atand{\mathop{\rm atand}\nolimits} +\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} +\gdef\cosd{\mathop{\rm cosd}\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{ACOSD}: ACOSD, Arccosine function, degrees +* @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{ASIND}: ASIND, Arcsine function, degrees +* @code{ASINH}: ASINH, Inverse hyperbolic sine function +* @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair +* @code{ATAN}: ATAN, Arctangent function +* @code{ATAND}: ATAND, Arctangent function, degrees +* @code{ATAN2}: ATAN2, Arctangent function +* @code{ATAN2D}: ATAN2D, Arctangent function, degrees +* @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{COSD}: COSD, Cosine function, degrees +* @code{COSH}: COSH, Hyperbolic cosine function +* @code{COTAN}: COTAN, Cotangent function +* @code{COTAND}: COTAND, Cotangent function, degrees +* @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{SIND}: SIND, Sine function, degrees +* @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{TAND}: TAND, Tangent function, degrees +* @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 +@fnindex BABS +@fnindex IIABS +@fnindex JIABS +@fnindex KIABS +@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{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@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} +Degrees function: @ref{ACOSD} + +@end table + + + +@node ACOSD +@section @code{ACOSD} --- Arccosine function, degrees +@fnindex ACOSD +@fnindex DACOSD +@cindex trigonometric function, cosine, inverse, degrees +@cindex cosine, inverse, degrees + +@table @asis +@item @emph{Description}: +@code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of +@code{COSD(X)}). + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math} + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = ACOSD(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 degrees and lies in the range +@math{0 \leq \Re \acos(x) \leq 180}. + +@item @emph{Example}: +@smallexample +program test_acosd + real(8) :: x = 0.866_8 + x = acosd(x) +end program test_acosd +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension +@end multitable + +@item @emph{See also}: +Inverse function: @ref{COSD} +Radians function: @ref{ACOS} + +@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} +Degrees function: @ref{ASIND} + +@end table + + + +@node ASIND +@section @code{ASIND} --- Arcsine function, degrees +@fnindex ASIND +@fnindex DASIND +@cindex trigonometric function, sine, inverse, degrees +@cindex sine, inverse, degrees + +@table @asis +@item @emph{Description}: +@code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of +@code{SIND(X)}). + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math}. + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = ASIND(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 degrees and lies in the range +@math{-90 \leq \Re \asin(x) \leq 90}. + +@item @emph{Example}: +@smallexample +program test_asind + real(8) :: x = 0.866_8 + x = asind(x) +end program test_asind +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension +@end multitable + +@item @emph{See also}: +Inverse function: @ref{SIND} +Radians function: @ref{ASIN} + +@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} +Degrees function: @ref{ATAND} + +@end table + + + +@node ATAND +@section @code{ATAND} --- Arctangent function, degrees +@fnindex ATAND +@fnindex DATAND +@cindex trigonometric function, tangent, inverse, degrees +@cindex tangent, inverse, degrees + +@table @asis +@item @emph{Description}: +@code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of +@ref{TAND}). + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math}. + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@multitable @columnfractions .80 +@item @code{RESULT = ATAND(X)} +@item @code{RESULT = ATAND(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{ATAND2(Y,X)}. +Otherwise, it is the arcus tangent of @var{X}, where the real part of +the result is in degrees and lies in the range +@math{-90 \leq \Re \atand(x) \leq 90}. + +@item @emph{Example}: +@smallexample +program test_atand + real(8) :: x = 2.866_8 + x = atand(x) +end program test_atand +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension +@end multitable + +@item @emph{See also}: +Inverse function: @ref{TAND} +Radians function: @ref{ATAN} + +@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 + +@item @emph{See also}: +Alias: @ref{ATAN} +Degrees function: @ref{ATAN2D} + +@end table + + + +@node ATAN2D +@section @code{ATAN2D} --- Arctangent function, degrees +@fnindex ATAN2D +@fnindex DATAN2D +@cindex trigonometric function, tangent, inverse, degrees +@cindex tangent, inverse, degrees + +@table @asis +@item @emph{Description}: +@code{ATAN2D(Y, X)} computes the principal value of the argument +function of the complex number @math{X + i Y} in degrees. This function can +be used to transform from Cartesian into polar coordinates and +allows to determine the angle in the correct quadrant. + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math}. + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = ATAN2D(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{-180 \le \atan (x) \leq 180}. +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{180} if +@var{X} is negative and @var{Y} is positive zero (or the processor does +not handle signed zeros), and @math{-180} 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{90}. + +@item @emph{Example}: +@smallexample +program test_atan2d + real(4) :: x = 1.e0_4, y = 0.5e0_4 + x = atan2d(y,x) +end program test_atan2d +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension +@end multitable + +@item @emph{See also}: +Alias: @ref{ATAND} +Radians function: @ref{ATAN2} + +@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 invocation was +successful, it is assigned the value 0. If it is present and the invocation +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 invocation was successful, it is assigned the value 0. If it is present +and the invocation 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 invocation +was successful, it is assigned the value 0. If it is present and the invocation +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 invocation was +successful, it is assigned the value 0. If it is present and the invocation +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 invocation was +successful, it is assigned the value 0. If it is present and the invocation +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 invocation was +successful, it is assigned the value 0. If it is present and the invocation 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 invocation was +successful, it is assigned the value 0. If it is present and the invocation 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 invocation was +successful, it is assigned the value 0. If it is present and the invocation 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 invocation was successful, it is assigned the value 0. If it is present +and the invocation 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 +invocation was successful, it is assigned the value 0. If it is present and the +invocation 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 invocation was successful, it is assigned the value 0. If it is present +and the invocation 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 +@fnindex BBTEST +@fnindex BITEST +@fnindex BJTEST +@fnindex BKTEST +@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, has overloads that are GNU extensions + +@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 + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later +@item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension +@item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension +@item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension +@item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension +@end multitable +@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} +Degrees function: @ref{COSD} + +@end table + + + +@node COSD +@section @code{COSD} --- Cosine function, degrees +@fnindex COSD +@fnindex DCOSD +@fnindex CCOSD +@fnindex ZCOSD +@fnindex CDCOSD +@cindex trigonometric function, cosine, degrees +@cindex cosine, degrees + +@table @asis +@item @emph{Description}: +@code{COSD(X)} computes the cosine of @var{X} in degrees. + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math}. + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = COSD(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 degrees. If @var{X} is of the type @code{REAL}, +the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}. + +@item @emph{Example}: +@smallexample +program test_cosd + real :: x = 0.0 + x = cosd(x) +end program test_cosd +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension +@item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension +@item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension +@item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension +@end multitable + +@item @emph{See also}: +Inverse function: @ref{ACOSD} +Radians function: @ref{COS} + +@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 COTAN +@section @code{COTAN} --- Cotangent function +@fnindex COTAN +@fnindex DCOTAN +@cindex trigonometric function, cotangent +@cindex cotangent + +@table @asis +@item @emph{Description}: +@code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)} +divided by @code{SIN(x)}, or @code{1 / TAN(x)}. + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math}. + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = COTAN(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}, and its value is in radians. + +@item @emph{Example}: +@smallexample +program test_cotan + real(8) :: x = 0.165_8 + x = cotan(x) +end program test_cotan +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension +@end multitable + +@item @emph{See also}: +Converse function: @ref{TAN} +Degrees function: @ref{COTAND} +@end table + + + +@node COTAND +@section @code{COTAND} --- Cotangent function, degrees +@fnindex COTAND +@fnindex DCOTAND +@cindex trigonometric function, cotangent, degrees +@cindex cotangent, degrees + +@table @asis +@item @emph{Description}: +@code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to +@code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math}. + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = COTAND(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}, and its value is in degrees. + +@item @emph{Example}: +@smallexample +program test_cotand + real(8) :: x = 0.165_8 + x = cotand(x) +end program test_cotand +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension +@end multitable + +@item @emph{See also}: +Converse function: @ref{TAND} +Radians function: @ref{COTAN} + +@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 +@ref{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 invocation was successful, +it is assigned the value 0. If it is present and the invocation 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 +@ref{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 @ref{TIME} +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)}. + +This intrinsic routine is provided for backwards compatibility with +GNU Fortran 77. In new code, programmers should consider the use of +the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 +standard. + +@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 1--31 +@item Number of months since January, range 0--11 +@item Years since 1900 +@item Number of days since Sunday, range 0--6 +@item Days since January 1, range 0--365 +@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{DATE_AND_TIME}, @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 +@fnindex BIAND +@fnindex IIAND +@fnindex JIAND +@fnindex KIAND +@cindex bitwise logical and +@cindex logical and, bitwise + +@table @asis +@item @emph{Description}: +Bitwise logical @code{AND}. + +@item @emph{Standard}: +Fortran 95 and later, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@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 +@fnindex BBCLR +@fnindex IIBCLR +@fnindex JIBCLR +@fnindex KIBCLR +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@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 +@fnindex BBITS +@fnindex IIBITS +@fnindex JIBITS +@fnindex KIBITS +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@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 +@fnindex BBSET +@fnindex IIBSET +@fnindex JIBSET +@fnindex KIBSET +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@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. + +This intrinsic routine is provided for backwards compatibility with +GNU Fortran 77. In new code, programmers should consider the use of +the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 +standard. + +@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 + +@item @emph{See also}: +@ref{DATE_AND_TIME} +@end table + + +@node IEOR +@section @code{IEOR} --- Bitwise logical exclusive or +@fnindex IEOR +@fnindex BIEOR +@fnindex IIEOR +@fnindex JIEOR +@fnindex KIEOR +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@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 +@fnindex BIOR +@fnindex IIOR +@fnindex JIOR +@fnindex KIOR +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@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 +@fnindex BSHFT +@fnindex IISHFT +@fnindex JISHFT +@fnindex KISHFT +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@item @emph{See also}: +@ref{ISHFTC} +@end table + + + +@node ISHFTC +@section @code{ISHFTC} --- Shift bits circularly +@fnindex ISHFTC +@fnindex BSHFTC +@fnindex IISHFTC +@fnindex JISHFTC +@fnindex KISHFTC +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@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{ITIME(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. + +This intrinsic routine is provided for backwards compatibility with +GNU Fortran 77. In new code, programmers should consider the use of +the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 +standard. + +@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 + +@item @emph{See also}: +@ref{DATE_AND_TIME} +@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 @ref{TIME} +intrinsic), fills @var{VALUES} with values extracted from it appropriate +to the local time zone using @code{localtime(3)}. + +This intrinsic routine is provided for backwards compatibility with +GNU Fortran 77. In new code, programmers should consider the use of +the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95 +standard. + +@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 1--31 +@item Number of months since January, range 0--11 +@item Years since 1900 +@item Number of days since Sunday, range 0--6 +@item Days since January 1, range 0--365 +@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{DATE_AND_TIME}, @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 +@fnindex BMOD +@fnindex IMOD +@fnindex JMOD +@fnindex KMOD +@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, has overloads that are GNU extensions + +@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 +@item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension +@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 +@fnindex BMVBITS +@fnindex IMVBITS +@fnindex JMVBITS +@fnindex KMVBITS +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@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 +@fnindex BNOT +@fnindex INOT +@fnindex JNOT +@fnindex KNOT +@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, has overloads that are GNU extensions + +@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{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later +@item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension +@item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension +@item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension +@item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension +@end multitable + +@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 the xorshift1024* random number +generator (RNG). This generator has a period of @math{2^{1024} - 1}, +and when using multiple threads up to @math{2^{512}} threads can each +generate @math{2^{512}} random numbers before any aliasing occurs. + +Note that in a multi-threaded program (e.g. using OpenMP directives), +each thread will have its own random number state. For details of the +seeding procedure, see the documentation for the @code{RANDOM_SEED} +intrinsic. + + +@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 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 seeded with +random data retrieved from the operating system. + +As an extension to the Fortran standard, the GFortran +@code{RANDOM_NUMBER} supports multiple threads. Each thread in a +multi-threaded program has its own seed. When @code{RANDOM_SEED} is +called either without arguments or with the @var{PUT} argument, the +given seed is copied into a master seed as well as the seed of the +current thread. When a new thread uses @code{RANDOM_NUMBER} for the +first time, the seed is copied from the master seed, and forwarded +@math{N * 2^{512}} steps to guarantee that the random stream does not +alias any other stream in the system, where @var{N} is the number of +threads that have used @code{RANDOM_NUMBER} so far during the program +execution. + +@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 +program test_random_seed + implicit none + integer, allocatable :: seed(:) + integer :: n + + call random_seed(size = n) + allocate(seed(n)) + call random_seed(get=seed) + write (*, *) seed +end program test_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 FLOATI +@fnindex FLOATJ +@fnindex FLOATK +@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{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension +@item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension +@item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @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}: +Inverse function: @ref{ASIN} +Degrees function: @ref{SIND} +@end table + + + +@node SIND +@section @code{SIND} --- Sine function, degrees +@fnindex SIND +@fnindex DSIND +@fnindex CSIND +@fnindex ZSIND +@fnindex CDSIND +@cindex trigonometric function, sine, degrees +@cindex sine, degrees + +@table @asis +@item @emph{Description}: +@code{SIND(X)} computes the sine of @var{X} in degrees. + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math}. + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = SIND(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}, and its value is in degrees. + +@item @emph{Example}: +@smallexample +program test_sind + real :: x = 0.0 + x = sind(x) +end program test_sind +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension +@item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension +@item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension +@item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension +@end multitable + +@item @emph{See also}: +Inverse function: @ref{ASIND} +Radians function: @ref{SIN} + +@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}, and its value is in radians. + +@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}: +Inverse function: @ref{ATAN} +Degrees function: @ref{TAND} +@end table + + + +@node TAND +@section @code{TAND} --- Tangent function, degrees +@fnindex TAND +@fnindex DTAND +@cindex trigonometric function, tangent, degrees +@cindex tangent, degrees + +@table @asis +@item @emph{Description}: +@code{TAND(X)} computes the tangent of @var{X} in degrees. + +This function is for compatibility only and should be avoided in favor of +standard constructs wherever possible. + +@item @emph{Standard}: +GNU Extension, enabled with @option{-fdec-math}. + +@item @emph{Class}: +Elemental function + +@item @emph{Syntax}: +@code{RESULT = TAND(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}, and its value is in degrees. + +@item @emph{Example}: +@smallexample +program test_tand + real(8) :: x = 0.165_8 + x = tand(x) +end program test_tand +@end smallexample + +@item @emph{Specific names}: +@multitable @columnfractions .20 .20 .20 .25 +@item Name @tab Argument @tab Return type @tab Standard +@item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension +@item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension +@end multitable + +@item @emph{See also}: +Inverse function: @ref{ATAND} +Radians function: @ref{TAN} +@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 @ref{CTIME}, @ref{GMTIME}, and @ref{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{DATE_AND_TIME}, @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 @ref{CTIME}, @ref{GMTIME}, and @ref{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{DATE_AND_TIME}, @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{ptrdiff_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.5 +@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/wp-content/uploads/openmp-4.5.pdf, +OpenMP Application Program Interface v4.5}. + +@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.5 the value is @code{201511}. + +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}.