blob: 1b9a89dcd9a3d9c00a8462a0b6417b8a494ef800 [file] [log] [blame]
@ignore
Copyright (C) 2005-2021 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{FINDLOC}: FINDLOC, Search an array for a value
* @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_CONTIGUOUS}: IS_CONTIGUOUS, Test whether an array is contiguous
* @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_INIT}: RANDOM_INIT, Initialize pseudo-random number generator
* @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}, @gol
@ref{KILL}, @gol
@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
@headitem 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{REAL(8)} @tab GNU extension
@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(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. Trailing 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
@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}, @gol
@ref{IACHAR}, @gol
@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
@headitem 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: @gol
@ref{COS} @gol
Degrees function: @gol
@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
@headitem 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: @gol
@ref{COSD} @gol
Radians function: @gol
@ref{ACOS} @gol
@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
@headitem 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: @gol
@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}, @gol
@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 90 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}, @gol
@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
@headitem Name @tab Argument @tab Return type @tab Standard
@item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later
@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
@headitem 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 90 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 90 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 or a boz-literal-constant.
@item @var{J} @tab The type shall be the same as the type of @var{I} or
a boz-literal-constant. @var{I} and @var{J} shall not both be
boz-literal-constants. If either @var{I} or @var{J} is a
boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
@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. A boz-literal-constant is
converted to an @code{INTEGER} with the kind type parameter of
the other argument as-if a call to @ref{INT} occurred.
@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: @gol
@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
@headitem Name @tab Argument @tab Return type @tab Standard
@item @code{ANINT(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 90 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
@headitem 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: @gol
@ref{SIN} @gol
Degrees function: @gol
@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
@headitem 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: @gol
@ref{SIND} @gol
Radians function: @gol
@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
@headitem 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: @gol
@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 90 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} @tab The type and kind type parameter shall be the same 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
@headitem 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: @gol
@ref{TAN} @gol
Degrees function: @gol
@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} @tab The type and kind type parameter shall be the same 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
@headitem 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: @gol
@ref{TAND} @gol
Radians function: @gol
@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
@headitem 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: @gol
@ref{ATAN} @gol
Degrees function: @gol
@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
@headitem 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: @gol
@ref{ATAND} @gol
Radians function: @gol
@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
@headitem 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: @gol
@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{VALUE} 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}, @gol
@ref{ATOMIC_FETCH_ADD}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_AND}, @gol
@ref{ATOMIC_OR}, @gol
@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}, @gol
@ref{ATOMIC_FETCH_AND}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_ADD}, @gol
@ref{ATOMIC_OR}, @gol
@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}, @gol
@ref{ATOMIC_REF}, @gol
@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}, @gol
@ref{ATOMIC_CAS}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_ADD}, @gol
@ref{ATOMIC_AND}, @gol
@ref{ATOMIC_OR}, @gol
@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{VALUE} 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}, @gol
@ref{ATOMIC_ADD}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_FETCH_AND}, @gol
@ref{ATOMIC_FETCH_OR}, @gol
@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}, @gol
@ref{ATOMIC_AND}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_FETCH_ADD}, @gol
@ref{ATOMIC_FETCH_OR}, @gol
@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}, @gol
@ref{ATOMIC_OR}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_FETCH_ADD}, @gol
@ref{ATOMIC_FETCH_AND}, @gol
@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}, @gol
@ref{ATOMIC_XOR}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_FETCH_ADD}, @gol
@ref{ATOMIC_FETCH_AND}, @gol
@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}, @gol
@ref{ATOMIC_FETCH_OR}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_ADD}, @gol
@ref{ATOMIC_OR}, @gol
@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}, @gol
@ref{ATOMIC_CAS}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_FETCH_ADD}, @gol
@ref{ATOMIC_FETCH_AND}, @gol
@ref{ATOMIC_FETCH_OR}, @gol
@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}, @gol
@ref{ATOMIC_FETCH_XOR}, @gol
@ref{ISO_FORTRAN_ENV}, @gol
@ref{ATOMIC_ADD}, @gol
@ref{ATOMIC_OR}, @gol
@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
@headitem 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
@headitem 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
@headitem 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
@headitem 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
@headitem 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
@headitem 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}, @gol
@ref{BLE}, @gol
@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}, @gol
@ref{BLE}, @gol
@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 90 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}, @gol
@ref{BGE}, @gol
@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}, @gol
@ref{BGT}, @gol
@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 90 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
@headitem Name @tab Argument @tab Return type @tab Standard
@item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 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}, @gol
@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}, @gol
@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}, @gol
@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}, @gol
@ref{C_LOC}, @gol
@ref{C_F_POINTER}, @gol
@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}, @gol
@ref{C_FUNLOC}, @gol
@ref{C_F_POINTER}, @gol
@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{T} unless you are using a platform
where default @code{REAL} variables are unusually padded.
@item @emph{See also}:
@ref{SIZEOF}, @gol
@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}, @gol
@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 .18 .18 .24 .25
@headitem Name @tab Argument @tab Return type @tab Standard
@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 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}, @gol
@ref{IACHAR}, @gol
@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 .20 .65
@item @var{A} @tab INTENT(INOUT) argument; shall have the same
dynamic type and type parameters 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 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}, @gol
@ref{CO_MIN}, @gol
@ref{CO_SUM}, @gol
@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 .20 .65
@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 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