2 Class. Elemental function. 3 Arguments. A shall be of type real.4 Restriction. IEEE_SIGNALING_NE (A, B) shall not be invoked if IEEE_SUPPORT_DATATYPE (A) hasB shall be of the same type and kind type parameter as A.
the value false.5 Result Characteristics. Default logical.
6 Result Value. The result has the value specified for the compareSignalingNotEqual operation in ISO/IEC/IEEE 60559:2011; that is, it is true if and only if A compares not equal to B. If A or B is a NaN, the result will be true7 Example. IEEE_SIGNALING_NE (1.0, IEEE_VALUE (IEEE_QUIET_NAN)) has the value true and signalsand IEEE_INVALID signals; otherwise, no exception is signaled.
IEEE_INVALID.1 Description. Test sign bit.17.11.47 IEEE_SIGNBIT (X)
2 Class. Elemental function. 3 Argument. X shall be of type real. ⃝c ISO/IEC 2017 – All rights reserved 4694 Restriction. IEEE_SIGNBIT (X) shall not be invoked if IEEE_SUPPORT_DATATYPE (X) has the value
ISO/IEC DIS 1539-1:2017 (E)
false.5 Result Characteristics. Default logical.
6 Result Value. The result has the value specified for the isSignMinus operation in ISO/IEC/IEEE 60559:2011; that is, it is true if and only if the sign bit of X is nonzero. No exception is signaled even if X is a signaling NaN.7 Example. IEEE_SIGNBIT (−1.0) has the value true.
17.11.48 IEEE_SUPPORT_DATATYPE () or1 Description. Query IEEE arithmetic support.IEEE_SUPPORT_DATATYPE (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. The result has the value true if the processor supports IEEE arithmetic for all reals (X does not appear) or for real variables of the same kind type parameter as X; otherwise, it has the value false. Here,6 Example. If default real kind conforms to ISO/IEC/IEEE 60559:2011 except that underflow values flush to zerosupport is as defined in the first paragraph of 17.9.
instead of being subnormal, IEEE_SUPPORT_DATATYPE (1.0) has the value true.1 Description. Query subnormal number support.17.11.49 IEEE_SUPPORT_DENORMAL () or
IEEE_SUPPORT_DENORMAL (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. Case (i): IEEE_SUPPORT_DENORMAL (X) has the value true if IEEE_SUPPORT_DATATYPE (X) has6 Example. IEEE_SUPPORT_DENORMAL (X) has the value true if the processor supports subnormal valuesthe value true and the processor supports arithmetic operations and assignments with subnormal
numbers (biased exponent e = 0 and fraction f ̸= 0, see subclause 3.2 of ISO/IEC/IEEE 60559:2011)
for real variables of the same kind type parameter as X; otherwise, it has the value false.
Case (ii): IEEE_SUPPORT_DENORMAL () has the value true if IEEE_SUPPORT_DENORMAL (X) has
the value true for all real X; otherwise, it has the value false.
for X.1 Description. Query IEEE division support.NOTE 17.12
A reference to IEEE_SUPPORT_DENORMAL will have the same result value as a reference to IEEE_-
SUPPORT_SUBNORMAL with the same argument list.
470 ⃝
c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
17.11.50 IEEE_SUPPORT_DIVIDE () or IEEE_SUPPORT_DIVIDE (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. Case (i): IEEE_SUPPORT_DIVIDE (X) has the value true if the processor supports division with the6 Example. IEEE_SUPPORT_DIVIDE (X) has the value true if division of operands with the same kind as Xaccuracy specified by ISO/IEC/IEEE 60559:2011 for real variables of the same kind type parameter
as X; otherwise, it has the value false.
Case (ii): IEEE_SUPPORT_DIVIDE () has the value true if IEEE_SUPPORT_DIVIDE (X) has the value
true for all real X; otherwise, it has the value false.
conforms to ISO/IEC/IEEE 60559:2011.1 Description. Query exception support.17.11.51 IEEE_SUPPORT_FLAG (FLAG) or IEEE_SUPPORT_FLAG (FLAG,
X)
2 Class. Transformational function. 3 Arguments. FLAG shall be a scalar of type IEEE_FLAG_TYPE. Its value shall be one of IEEE_INVALID, IEEE_-4 Result Characteristics. Default logical scalar.OVERFLOW, IEEE_DIVIDE_BY_ZERO, IEEE_UNDERFLOW, or IEEE_INEXACT.
X shall be of type real. It may be a scalar or an array.
5 Result Value. Case (i): IEEE_SUPPORT_FLAG (FLAG, X) has the value true if the processor supports detection of the6 Example. IEEE_SUPPORT_FLAG (IEEE_INEXACT) has the value true if the processor supports the inexactspecified exception for real variables of the same kind type parameter as X; otherwise, it has the
value false.
Case (ii): IEEE_SUPPORT_FLAG (FLAG) has the value true if IEEE_SUPPORT_FLAG (FLAG, X) has
the value true for all real X; otherwise, it has the value false.
exception.1 Description. Query halting mode support.17.11.52 IEEE_SUPPORT_HALTING (FLAG)
2 Class. Transformational function. 3 Argument. FLAG shall be a scalar of type IEEE_FLAG_TYPE. Its value shall be one of IEEE_INVALID, IEEE_OVERFLOW, IEEE_DIVIDE_BY_ZERO, IEEE_UNDERFLOW, or IEEE_INEXACT.4 Result Characteristics. Default logical scalar.
5 Result Value. The result has the value true if the processor supports the ability to control during program execution whether to abort or continue execution after the exception specified by FLAG; otherwise, it has the6 Example. IEEE_SUPPORT_HALTING (IEEE_OVERFLOW) has the value true if the processor supportsvalue false. Support includes the ability to change the mode by CALL IEEE_SET_HALTING_MODE (FLAG).
⃝c ISO/IEC 2017 – All rights reserved 471
ISO/IEC DIS 1539-1:2017 (E)
control of halting after an overflow.1 Description. Query IEEE infinity support.17.11.53 IEEE_SUPPORT_INF () or IEEE_SUPPORT_INF (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. Case (i): IEEE_SUPPORT_INF (X) has the value true if the processor supports IEEE infinities (positive6 Example. IEEE_SUPPORT_INF (X) has the value true if the processor supports IEEE infinities for X.and negative) for real variables of the same kind type parameter as X; otherwise, it has the value
false.
Case (ii): IEEE_SUPPORT_INF () has the value true if IEEE_SUPPORT_INF (X) has the value true for
all real X; otherwise, it has the value false.
17.11.54 IEEE_SUPPORT_IO () or IEEE_SUPPORT_IO (X)1 Description. Query IEEE formatting support.
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. Case (i): IEEE_SUPPORT_IO (X) has the value true if base conversion during formatted input/output6 Example. IEEE_SUPPORT_IO (X) has the value true if formatted input/output base conversions conform to(<IP_ADDRESS>, <IP_ADDRESS>, <IP_ADDRESS>.8) conforms to ISO/IEC/IEEE 60559:2011 for the modes UP, DOWN,
ZERO, and NEAREST for real variables of the same kind type parameter as X; otherwise, it has
the value false.
Case (ii): IEEE_SUPPORT_IO () has the value true if IEEE_SUPPORT_IO (X) has the value true for all
real X; otherwise, it has the value false.
ISO/IEC/IEEE 60559:2011.1 Description. Query IEEE NaN support.17.11.55 IEEE_SUPPORT_NAN () or IEEE_SUPPORT_NAN (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. Case (i): IEEE_SUPPORT_NAN (X) has the value true if the processor supports IEEE NaNs for real6 Example. IEEE_SUPPORT_NAN (X) has the value true if the processor supports IEEE NaNs for X.variables of the same kind type parameter as X; otherwise, it has the value false.
Case (ii): IEEE_SUPPORT_NAN () has the value true if IEEE_SUPPORT_NAN (X) has the value true
for all real X; otherwise, it has the value false.
472 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
17.11.56 IEEE_SUPPORT_ROUNDING (ROUND_VALUE) or1 Description. Query IEEE rounding support.IEEE_SUPPORT_ROUNDING (ROUND_VALUE, X)
2 Class. Transformational function. 3 Arguments. ROUND_VALUE shall be of type IEEE_ROUND_TYPE.4 Result Characteristics. Default logical scalar.X shall be of type real. It may be a scalar or an array.
5 Result Value. Case (i): IEEE_SUPPORT_ROUNDING (ROUND_VALUE, X) has the value true if the processor supports6 Example. IEEE_SUPPORT_ROUNDING (IEEE_TO_ZERO) has the value true if the processor supportsthe rounding mode defined by ROUND_VALUE for real variables of the same kind type parameter
as X; otherwise, it has the value false. Support includes the ability to change the mode by CALL
IEEE_SET_ROUNDING_MODE (ROUND_VALUE).
Case (ii): IEEE_SUPPORT_ROUNDING (ROUND_VALUE) has the value true if IEEE_SUPPORT_-
ROUNDING (ROUND_VALUE, X) has the value true for all real X; otherwise, it has the value
false.
rounding to zero for all reals.1 Description. Query IEEE square root support.17.11.57 IEEE_SUPPORT_SQRT () or IEEE_SUPPORT_SQRT (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. Case (i): IEEE_SUPPORT_SQRT (X) has the value true if the intrinsic function SQRT conforms to6 Example. If IEEE_SUPPORT_SQRT (1.0) has the value true, SQRT (−0.0) will have the value −0.0.ISO/IEC/IEEE 60559:2011 for real variables of the same kind type parameter as X; otherwise,
it has the value false.
Case (ii): IEEE_SUPPORT_SQRT () has the value true if IEEE_SUPPORT_SQRT (X) has the value true
for all real X; otherwise, it has the value false.
17.11.58 IEEE_SUPPORT_STANDARD () or1 Description. Query IEEE standard support.IEEE_SUPPORT_STANDARD (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. ⃝c ISO/IEC 2017 – All rights reserved 4735 Result Value.
ISO/IEC DIS 1539-1:2017 (E)
Case (i): IEEE_SUPPORT_STANDARD (X) has the value true if the results of all the func-6 Example. IEEE_SUPPORT_STANDARD () has the value false if some but not all kinds of reals conform totions IEEE_SUPPORT_DATATYPE (X), IEEE_SUPPORT_DIVIDE (X), IEEE_SUPPORT_-
FLAG (FLAG, X) for valid FLAG, IEEE_SUPPORT_HALTING (FLAG) for valid FLAG, IEEE_-
SUPPORT_INF (X), IEEE_SUPPORT_NAN (X), IEEE_SUPPORT_ROUNDING (ROUND_-
VALUE, X) for valid ROUND_VALUE, IEEE_SUPPORT_SQRT (X), and IEEE_SUPPORT_-
SUBNORMAL (X) are all true; otherwise, it has the value false.
Case (ii): IEEE_SUPPORT_STANDARD () has the value true if IEEE_SUPPORT_STANDARD (X) has
the value true for all real X; otherwise, it has the value false.
ISO/IEC/IEEE 60559:2011.1 Description. Query subnormal number support.17.11.59 IEEE_SUPPORT_SUBNORMAL () or
IEEE_SUPPORT_SUBNORMAL (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. Case (i): IEEE_SUPPORT_SUBNORMAL (X) has the value true if IEEE_SUPPORT_DATATYPE (X)6 Example. IEEE_SUPPORT_SUBNORMAL (X) has the value true if the processor supports subnormal valueshas the value true and the processor supports arithmetic operations and assignments with subnormal
numbers (biased exponent e = 0 and fraction f ̸= 0, see subclause 3.2 of ISO/IEC/IEEE 60559:2011)
for real variables of the same kind type parameter as X; otherwise, it has the value false.
Case (ii): IEEE_SUPPORT_SUBNORMAL () has the value true if IEEE_SUPPORT_SUBNORMAL (X)
has the value true for all real X; otherwise, it has the value false.
for X.1 Description. Query underflow control support.NOTE 17.13
The subnormal numbers are not included in the 16.4 model for real numbers; they satisfy the inequality
ABS (X) < TINY (X). They usually occur as a result of an arithmetic operation whose exact result is
less than TINY (X). Such an operation causes IEEE_UNDERFLOW to signal unless the result is exact.
IEEE_SUPPORT_SUBNORMAL (X) is false if the processor never returns a subnormal number as the
result of an arithmetic operation.
17.11.60 IEEE_SUPPORT_UNDERFLOW_CONTROL () or
IEEE_SUPPORT_UNDERFLOW_CONTROL (X)
2 Class. Inquiry function. 3 Argument. X shall be of type real. It may be a scalar or an array. 4 Result Characteristics. Default logical scalar. 5 Result Value. Case (i): IEEE_SUPPORT_UNDERFLOW_CONTROL (X) has the value true if the processor supports6 Example. IEEE_SUPPORT_UNDERFLOW_CONTROL (2.5) has the value true if the processor supportscontrol of the underflow mode for floating-point calculations with the same type as X, and false
otherwise.
474 ⃝
c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
Case (ii): IEEE_SUPPORT_UNDERFLOW_CONTROL () has the value true if the processor supports
control of the underflow mode for all floating-point calculations, and false otherwise.
underflow mode control for default real calculations.1 Description. Whether two values are unordered.17.11.61 IEEE_UNORDERED (X, Y)
2 Class. Elemental function. 3 Arguments. The arguments shall be of type real. 4 Restriction. IEEE_UNORDERED (X, Y) shall not be invoked if IEEE_SUPPORT_DATATYPE (X) or IEEE_SUPPORT_DATATYPE (Y) has the value false.5 Result Characteristics. Default logical.
6 Result Value. The result has the value true if X or Y is a NaN or both are NaNs; otherwise, it has the value false. If X or Y is a signaling NaN, IEEE_INVALID may signal.7 Example. IEEE_UNORDERED (0.0, SQRT (−1.0)) has the value true if IEEE_SUPPORT_SQRT (1.0) has
the value true.1 Description. Return number in a class.17.11.62 IEEE_VALUE (X, CLASS)
2 Class. Elemental function. 3 Arguments. X shall be of type real.4 Restriction. IEEE_VALUE (X, CLASS) shall not be invoked if IEEE_SUPPORT_DATATYPE (X) has theCLASS shall be of type IEEE_CLASS_TYPE. The value is permitted to be: IEEE_SIGNALING_NAN or
IEEE_QUIET_NAN if IEEE_SUPPORT_NAN (X) has the value true, IEEE_NEGATIVE_INF
or IEEE_POSITIVE_INF if IEEE_SUPPORT_INF (X) has the value true, IEEE_NEGATIVE_-
SUBNORMAL or IEEE_POSITIVE_SUBNORMAL if IEEE_SUPPORT_SUBNORMAL (X) has
the value true, IEEE_NEGATIVE_NORMAL, IEEE_NEGATIVE_ZERO, IEEE_POSITIVE_-
ZERO or IEEE_POSITIVE_NORMAL.
value false.5 Result Characteristics. Same as X.
6 Result Value. The result value is an IEEE value as specified by CLASS. Although in most cases the value is processor dependent, the value shall not vary between invocations for any particular X kind type parameter and7 Example. IEEE_VALUE (1.0, IEEE_NEGATIVE_INF) has the value −infinity.CLASS value.
8 Whenever IEEE_VALUE returns a signaling NaN, it is processor dependent whether or not invalid is raised and processor dependent whether or not the signaling NaN is converted into a quiet NaN.ISO/IEC DIS 1539-1:2017 (E)NOTE 17.14
If the expr in an assignment statement is a reference to the IEEE_VALUE function that returns a signaling
NaN and the variable is of the same type and kind as the function result, it is recommended that the
signaling NaN be preserved.
⃝c ISO/IEC 2017 – All rights reserved 475
17.12 Examples NOTE 17.15
MODULE DOT
! Module for dot product of two real arrays of rank 1.
! The caller needs to ensure that exceptions do not cause halting.
USE, INTRINSIC :: IEEE_EXCEPTIONS
LOGICAL :: MATRIX_ERROR = .FALSE.
INTERFACE OPERATOR(.dot.)
MODULE PROCEDURE MULT
END INTERFACE
CONTAINS
REAL FUNCTION MULT (A, B)
REAL, INTENT (IN) :: A(:), B(:)
INTEGER I
LOGICAL OVERFLOW
IF (SIZE(A) /= SIZE(B)) THEN
MATRIX_ERROR = .TRUE.
RETURN
END IF
! The processor ensures that IEEE_OVERFLOW is quiet.
MULT = 0.0
DO I = 1, SIZE (A)
MULT = MULT + A(I)*B(I)
END DO
CALL IEEE_GET_FLAG (IEEE_OVERFLOW, OVERFLOW)
IF (OVERFLOW) MATRIX_ERROR = .TRUE.
END FUNCTION MULT
END MODULE DOT
This module provides a function that computes the dot product of two real arrays of rank 1. If the sizes
of the arrays are different, an immediate return occurs with MATRIX_ERROR true. If overflow occurs
during the actual calculation, the IEEE_OVERFLOW flag will signal and MATRIX_ERROR will be true.
NOTE 17.16
USE, INTRINSIC :: IEEE_EXCEPTIONSUSE, INTRINSIC :: IEEE_FEATURES, ONLY: IEEE_INVALID_FLAG
! The other exceptions of IEEE_USUAL (IEEE_OVERFLOW and
! IEEE_DIVIDE_BY_ZERO) are always available with IEEE_EXCEPTIONS
TYPE (IEEE_STATUS_TYPE) STATUS_VALUE
LOGICAL, DIMENSION(3) :: FLAG_VALUE
...
CALL IEEE_GET_STATUS (STATUS_VALUE)
CALL IEEE_SET_HALTING_MODE (IEEE_USUAL, .FALSE.) ! Needed in case the
! default on the processor is to halt on exceptions
CALL IEEE_SET_FLAG (IEEE_USUAL, .FALSE.)
476 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)NOTE 17.16 (cont.)
! First try the "fast" algorithm for inverting a matrix:MATRIX1 = FAST_INV (MATRIX) ! This shall not alter MATRIX.
CALL IEEE_GET_FLAG (IEEE_USUAL, FLAG_VALUE)
IF (ANY(FLAG_VALUE)) THEN
! "Fast" algorithm failed; try "slow" one:
CALL IEEE_SET_FLAG (IEEE_USUAL, .FALSE.)
MATRIX1 = SLOW_INV (MATRIX)
CALL IEEE_GET_FLAG (IEEE_USUAL, FLAG_VALUE)
IF (ANY (FLAG_VALUE)) THEN
WRITE (*, *) ’Cannot invert matrix’
STOP
END IF
END IF
CALL IEEE_SET_STATUS (STATUS_VALUE)
In this example, the function FAST_INV might cause a condition to signal. If it does, another try is made
with SLOW_INV. If this still fails, a message is printed and the program stops. Note, also, that it is
important to set the flags quiet before the second try. The state of all the flags is stored and restored.
NOTE 17.17
USE, INTRINSIC :: IEEE_EXCEPTIONS
LOGICAL FLAG_VALUE
...
CALL IEEE_SET_HALTING_MODE (IEEE_OVERFLOW, .FALSE.)
! First try a fast algorithm for inverting a matrix.
CALL IEEE_SET_FLAG (IEEE_OVERFLOW, .FALSE.)
DO K = 1, N
...CALL IEEE_GET_FLAG (IEEE_OVERFLOW, FLAG_VALUE)
IF (FLAG_VALUE) EXIT
END DO
IF (FLAG_VALUE) THEN
! Alternative code which knows that K-1 steps have executed normally.
...
END IF
Here the code for matrix inversion is in line and the transfer is made more precise by adding extra tests of
the flag.
⃝
c ISO/IEC 2017 – All rights reserved 477
ISO/IEC DIS 1539-1:2017 (E)
(Blank page)
1 Fortran provides a means of referencing procedures that are defined by means of the C programming language
478 c ISO/IEC 2017 – All rights reserved18 Interoperability with C
ISO/IEC DIS 1539-1:2017 (E)
18.1 General
or procedures that can be described by C prototypes as defined in <IP_ADDRESS> of ISO/IEC 9899:2011, even if they2 The ISO_C_BINDING module provides access to named constants that represent kind type parameters of dataare not actually defined by means of C. Conversely, there is a means of specifying that a procedure defined by a
Fortran subprogram can be referenced from a function defined by means of C. In addition, there is a means of
declaring global variables that are associated with C variables whose names have external linkage as defined in
6.2.2 of ISO/IEC 9899:2011.
representations compatible with C types. Fortran also provides facilities for defining derived types (7.5) and3 The source file ISO_Fortran_binding.h provides definitions and prototypes to enable a C function to interoperateenumerations (7.6) that correspond to C types.
with a Fortran procedure that has a dummy data object that is allocatable, assumed-shape, assumed-rank, pointer,1 The processor shall provide the intrinsic module ISO_C_BINDING. This module shall make accessible theor is of type character with an assumed length.
18.2 The ISO_C_BINDING intrinsic module
18.2.1 Summary of contents
following entities: the named constants C_NULL_PTR, C_NULL_FUNPTR, and those with names listed in1 The entities listed in the second column of Table 18.2 shall be default integer named constants.the first column of Table 18.1 and the second column of Table 18.2, the types C_PTR and C_FUNPTR, and the
procedures in 18.2.3. A processor may provide other public entities in the ISO_C_BINDING intrinsic module
in addition to those listed here.
18.2.2 Named constants and derived types in the module
2 A Fortran intrinsic type whose kind type parameter is one of the values in the module shall have the same
representation as the C type with which it interoperates, for each value that a variable of that type can have.3 The value of C_INT shall be a valid value for an integer kind parameter on the processor. The values ofFor C_BOOL, the internal representation of .TRUE._C_BOOL and .FALSE._C_BOOL shall be the same as those of
the C values (_Bool)1 and (_Bool)0 respectively.
C_SHORT, C_LONG, C_LONG_LONG, C_SIGNED_CHAR, C_SIZE_T, C_INT8_T, C_INT16_T, C_-4 The values of C_FLOAT, C_DOUBLE, and C_LONG_DOUBLE shall each be a valid value for a real kindINT32_T, C_INT64_T, C_INT_LEAST8_T, C_INT_LEAST16_T, C_INT_LEAST32_T, C_INT_LEAST-
64_T, C_INT_FAST8_T, C_INT_FAST16_T, C_INT_FAST32_T, C_INT_FAST64_T, C_INTMAX_T,
and C_INTPTR_T shall each be a valid value for an integer kind type parameter on the processor or shall be
−1 if the companion processor (5.5.7) defines the corresponding C type and there is no interoperating Fortran
processor kind, or −2 if the companion processor does not define the corresponding C type.
type parameter on the processor or shall be −1 if the companion processor’s type does not have a precision equal5 The value of C_BOOL shall be a valid value for a logical kind parameter on the processor or shall be −1.to the precision of any of the Fortran processor’s real kinds, −2 if the companion processor’s type does not have
a range equal to the range of any of the Fortran processor’s real kinds, −3 if the companion processor’s type
⃝c ISO/IEC 2017 – All rights reserved 479
ISO/IEC DIS 1539-1:2017 (E)
has neither the precision nor range of any of the Fortran processor’s real kinds, and equal to −4 if there is no
interoperating Fortran processor kind for other reasons. The values of C_FLOAT_COMPLEX, C_DOUBLE_-
COMPLEX, and C_LONG_DOUBLE_COMPLEX shall be the same as those of C_FLOAT, C_DOUBLE, and
C_LONG_DOUBLE, respectively.
6 The value of C_CHAR shall be a valid value for a character kind type parameter on the processor or shall be −1.
If the value of C_CHAR is nonnegative, the character kind specified is the C character kind; otherwise, there is7 The following entities shall be named constants of type character with a length parameter of one. The kindno C character kind.
parameter value shall be equal to the value of C_CHAR unless C_CHAR = −1, in which case the kind parameter8 The entities C_PTR and C_FUNPTR are described in 18.3.3.value shall be the same as for default kind. The values of these constants are specified in Table 18.1. In the case
that C_CHAR ̸= −1 the value is specified using C syntax. The semantics of these values are explained in 5.2.1
and 5.2.2 of ISO/IEC 9899:2011.
Table 18.1: Names of C characters with special semantics
Value
Name C definition C_CHAR = −1 C_CHAR ̸= −1
C_NULL_CHAR null character CHAR(0) ’\0’
C_ALERT alert ACHAR(7) ’\a’
C_BACKSPACE backspace ACHAR(8) ’\b’
C_FORM_FEED form feed ACHAR(12) ’\f’
C_NEW_LINE new line ACHAR(10) ’\n’
C_CARRIAGE_RETURN carriage return ACHAR(13) ’\r’
C_HORIZONTAL_TAB horizontal tab ACHAR(9) ’\t’
C_VERTICAL_TAB vertical tab ACHAR(11) ’\v’
9 The entity C_NULL_PTR shall be a named constant of type C_PTR. The value of C_NULL_PTR shall be the
same as the value NULL in C. The entity C_NULL_FUNPTR shall be a named constant of type C_FUNPTR.1 In the detailed descriptions below, procedure names are generic and not specific. The C_F_POINTER subroutineThe value of C_NULL_FUNPTR shall be that of a null pointer to a function in C.
NOTE 18.1
The value of NEW_LINE(C_NEW_LINE) is C_NEW_LINE (16.9.140).
18.2.3 Procedures in the module
<IP_ADDRESS> General
is impure; all other procedures in the module are pure.1 Description. Query C pointer status.<IP_ADDRESS> C_ASSOCIATED (C_PTR_1 [, C_PTR_2])
2 Class. Transformational function.
3 Arguments.
C_PTR_1 shall be a scalar of type C_PTR or C_FUNPTR.4 Result Characteristics. Default logical scalar.C_PTR_2 (optional) shall be a scalar of the same type as C_PTR_1.
480 ⃝
c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
5 Result Value.
Case (i): If C_PTR_2 is absent, the result is false if C_PTR_1 is a C null pointer and true otherwise.Case (ii): If C_PTR_2 is present, the result is false if C_PTR_1 is a C null pointer. If C_PTR_1 is not a
C null pointer, the result is true if C_PTR_1 compares equal to C_PTR_2 in the sense of <IP_ADDRESS>
and 6.5.9 of ISO/IEC 9899:2011, and false otherwise.
NOTE 18.2
The following example illustrates the use of C_LOC and C_ASSOCIATED.
USE, INTRINSIC :: ISO_C_BINDING, ONLY: C_PTR, C_FLOAT, C_ASSOCIATED, C_LOC
INTERFACE
SUBROUTINE FOO(GAMMA) BIND(C)
IMPORT C_PTR
TYPE(C_PTR), VALUE :: GAMMA
END SUBROUTINE FOO
END INTERFACE
REAL(C_FLOAT), TARGET, DIMENSION(100) :: ALPHA
TYPE(C_PTR) :: BETA
...
IF (.NOT. C_ASSOCIATED(BETA)) THEN
BETA = C_LOC(ALPHA)
ENDIF
CALL FOO(BETA)
<IP_ADDRESS> C_F_POINTER (CPTR, FPTR [, SHAPE]) 1 Description. Associate a data pointer with the target of a C pointer and specify its shape.
2 Class. Subroutine.
3 Arguments.
CPTR shall be a scalar of type C_PTR. It is an INTENT (IN) argument. Its value shall be4 Examples.• the C address of an interoperable data entity,
• the result of a reference to C_LOC with a noninteroperable argument, or
• the C address of a storage sequence that is not in use by any other Fortran entity.
The value of CPTR shall not be the C address of a Fortran variable that does not have the TARGET
attribute.
FPTR shall be a pointer, shall not have a deferred type parameter, and shall not be a coindexed object.
It is an INTENT (OUT) argument. If FPTR is an array, its shape is specified by SHAPE and each
lower bound is equal to 1.
Case (i): If the value of CPTR is the C address of an interoperable data entity, FPTR
shall be a data pointer with type and type parameter values interoperable with
the type of the entity. If the target T of CPTR is scalar, FPTR becomes pointer
associated with T; if FPTR is an array, SHAPE shall specify a size of 1. If T is
an array, and FPTR is scalar, FPTR becomes associated with the first element of
T. If both T and FPTR are arrays, SHAPE shall specify a size that is less than or
equal to the size of T, and FPTR becomes associated with the first PRODUCT
(SHAPE) elements of T (this could be the entirety of T).
⃝c ISO/IEC 2017 – All rights reserved 481
ISO/IEC DIS 1539-1:2017 (E)
Case (ii): If the value of CPTR is the result of a reference to C_LOC with a noninter-
operable effective argument X, FPTR shall be a nonpolymorphic pointer with
the same type and type parameters as X. In this case, X shall not have been
deallocated or have become undefined due to execution of a RETURN or END
statement since the reference. If X is scalar, FPTR becomes pointer associated
with X; if FPTR is an array, SHAPE shall specify a size of 1. If X is an array and
FPTR is scalar, FPTR becomes associated with the first element of X. If both X
and FPTR are arrays, SHAPE shall specify a size that is less than or equal to
the size of X, and FPTR becomes associated with the first PRODUCT (SHAPE)
elements of X (this could be the entirety of X).
Case (iii): If the value of CPTR is the C address of a storage sequence that is not in use by
any other Fortran entity, FPTR becomes associated with that storage sequence.
If FPTR is an array, its shape is specified by SHAPE and each lower bound
is 1. The storage sequence shall be large enough to contain the target object
described by FPTR and shall satisfy any other processor-dependent requirement
for association.
SHAPE (optional) shall be a rank-one integer array. It is an INTENT (IN) argument. SHAPE shall be present
if and only if FPTR is an array; its size shall be equal to the rank of FPTR.
Case (i): extern double c_x;1 Description. Associate a procedure pointer with the target of a C function pointer.void *address_of_x (void)
{
return &c_x;
}
! Assume interface to "address_of_x" is available.
Real (C_double), Pointer :: xp
Call C_F_Pointer (address_of_x (), xp)
Case (ii): Type t
Real, Allocatable :: v(:,:)
End Type
Type(t), Target :: x
Type(C_ptr) :: xloc
xloc = C_Loc (x)
...
Type(t), Pointer :: y
Call C_F_Pointer (xloc, y)
Case (iii): void *getmem (int nbits)
{
return malloc ((nbits+CHAR_BIT-1)/CHAR_BIT);
}
! Assume interface to "getmem" is available,
! and there is a derived type "mytype" accessible.
Type(mytype), Pointer :: x
Call C_F_Pointer (getmem (Storage_Size (x)), x)
482 ⃝
c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
The following statements illustrate the use of C_F_POINTER when the pointer to be set has a deferred type
parameter:
Character(42), Pointer :: C1
Character(:), Pointer :: C2
Call C_F_Pointer (CPTR, C1)
C2 => C1
This will associate C2 with the entity at the C address specified by CPTR, and specify its length to be the same
as that of C1.
NOTE 18.3
In the case of associating FPTR with a storage sequence, there might be processor-dependent requirements
such as alignment of the memory address or placement in memory.
<IP_ADDRESS> C_F_PROCPOINTER (CPTR, FPTR)
2 Class. Pure subroutine.
3 Arguments.
CPTR shall be a scalar of type C_FUNPTR. It is an INTENT (IN) argument. Its value shall be the C1 Description. C address of the argument.address of a procedure that is interoperable, or the result of a reference to the function C_FUNLOC
from the intrinsic module ISO_C_BINDING.
FPTR shall be a procedure pointer, and shall not be a component of a coindexed object. It is an INTENT
(OUT) argument. If the target of CPTR is interoperable, the interface for FPTR shall be interoper-
able with the prototype that describes the target of CPTR; otherwise, the interface for FPTR shall
have the same characteristics as that target. FPTR becomes pointer associated with the target of
CPTR.
NOTE 18.4
The term “target” in the descriptions of C_F_POINTER and C_F_PROCPOINTER denotes the entity
referenced by a C pointer, as described in 6.2.5 of ISO/IEC 9899:2011.
<IP_ADDRESS> C_FUNLOC (X)
2 Class. Transformational function.
3 Argument. X shall be a procedure; if it is a procedure pointer it shall be associated. It shall not be a coindexed
object.4 Result Characteristics. Scalar of type C_FUNPTR.
5 Result Value. The result value is described using the result name FUNPTR. The result is determined as if
C_FUNPTR were a derived type containing a procedure pointer component PX with an implicit interface and6 The result is a value that can be used as an actual CPTR argument in a call to C_F_PROCPOINTER wherethe pointer assignment FUNPTR%PX => X were executed.
the FPTR argument has attributes that would allow the pointer assignment FPTR => X. Such a call to C_F_-1 Description. C address of the argument.PROCPOINTER shall have the effect of the pointer assignment FPTR => X.
⃝c ISO/IEC 2017 – All rights reserved 483
ISO/IEC DIS 1539-1:2017 (E)
<IP_ADDRESS> C_LOC (X)
2 Class. Transformational function.
3 Argument. X 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 nonpolymorphic variable4 Result Characteristics. Scalar of type C_PTR.with no length type parameters. If it is allocatable, it shall be allocated. If it is a pointer, it shall be associated.
If it is an array, it shall be contiguous and have nonzero size. It shall not be a zero-length string.
5 Result Value. The result value is described using the result name CPTR.
6 If X is a scalar data entity, the result is determined as if C_PTR were a derived type containing a scalar pointer
component PX of the type and type parameters of X and the pointer assignment CPTR%PX => X were executed.7 If X is an array data entity, the result is determined as if C_PTR were a derived type containing a scalar pointer
component PX of the type and type parameters of X and the pointer assignment of CPTR%PX to the first8 If X is a data entity that is interoperable or has interoperable type and type parameters, the result is the valueelement of X were executed.
that the C processor returns as the result of applying the unary “&” operator (as defined in ISO/IEC 9899:2011,9 The result is a value that can be used as an actual CPTR argument in a call to C_F_POINTER where FPTR<IP_ADDRESS>) to the target of CPTR%PX.
has attributes that would allow the pointer assignment FPTR => X. Such a call to C_F_POINTER shall have1 Description. Size of X in bytes.the effect of the pointer assignment FPTR => X.
NOTE 18.5
Where the actual argument is of noninteroperable type or type parameters, the result of C_LOC provides
an opaque “handle” for it. In an actual implementation, this handle might be the C address of the argument;
however, only a C function that treats it as a void (generic) C pointer that cannot be dereferenced (<IP_ADDRESS>
in ISO/IEC 9899:2011) is likely to be portable.
<IP_ADDRESS> C_SIZEOF (X)
2 Class. Inquiry function.
3 Argument. X shall be an interoperable data entity that is not an assumed-size array or an assumed-rank array
that is associated with an assumed-size array.4 Result Characteristics. Scalar integer of kind C_SIZE_T (18.3.2).
5 Result Value. If X is scalar, the result value is the value that the companion processor returns as the result
of applying the sizeof operator (ISO/IEC 9899:2011, subclause <IP_ADDRESS>) to an object of a type that interoperates6 If X is an array, the result value is the value that the companion processor returns as the result of applying thewith the type and type parameters of X.
sizeof operator to an object of a type that interoperates with the type and type parameters of X, multiplied by1 Subclause 18.3 defines the conditions under which a Fortran entity is interoperable. If a Fortran entity is inter-the number of elements in X.
484 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
18.3 Interoperability between Fortran and C entities
18.3.1 General
operable, an equivalent entity could be defined by means of C and the Fortran entity would interoperate with the1 Table 18.2 shows the interoperability between Fortran intrinsic types and C types. A Fortran intrinsic type withC entity. There does not have to be such an interoperating C entity.
NOTE 18.6
A Fortran entity can be interoperable with more than one C entity.
18.3.2 Interoperability of intrinsic types
particular type parameter values is interoperable with a C type if the type and kind type parameter value are listed2 The second column of the table refers to the named constants made accessible by the ISO_C_BINDING intrinsicin the table on the same row as that C type. If the type is character, the length type parameter is interoperable
if and only if its value is one. A combination of Fortran type and type parameters that is interoperable with a
C type listed in the table is also interoperable with any unqualified C type that is compatible with the listed C
type.
module. If the value of any of these named constants is negative, there is no combination of Fortran type and3 A combination of intrinsic type and type parameters is interoperable if it is interoperable with a C type. The Ctype parameters interoperable with the C type shown in that row.
types mentioned in table 18.2 are defined in subclauses 6.2.5, 7.19, and 7.20.1 of ISO/IEC 9899:2011.Table 18.2: Interoperability between Fortran and C types
Named constant from the ISO_C_BINDING module
Fortran type C type
(kind type parameter if value is positive)
C_INT int
C_SHORT short int
C_LONG long int
C_LONG_LONG long long int
signed char
C_SIGNED_CHAR
unsigned char
1 C_PTR and C_FUNPTR shall be derived types with only private components. No direct component of either
C_SIZE_T size_t
C_INT8_T int8_t C_INT16_T int16_t C_INT32_T int32_t C_INT64_T int64_t C_INT_LEAST8_T int_least8_t C_INT_LEAST16_T int_least16_t C_INT_LEAST32_T int_least32_t INTEGER C_INT_LEAST64_T int_least64_t C_INT_FAST8_T int_fast8_tC_INT_FAST16_T int_fast16_t
C_INT_FAST32_T int_fast32_t
C_INT_FAST64_T int_fast64_t
C_INTMAX_T intmax_t
⃝c ISO/IEC 2017 – All rights reserved 485
ISO/IEC DIS 1539-1:2017 (E)
Interoperability between Fortran and C types (cont.)Named constant from the ISO_C_BINDING module
Fortran type C type (kind type parameter if value is positive)C_INTPTR_T intptr_t
C_PTRDIFF_T ptrdiff_t
C_FLOAT float
REAL C_DOUBLE double C_LONG_DOUBLE long doubleC_FLOAT_COMPLEX float _Complex
COMPLEX C_DOUBLE_COMPLEX double _Complex C_LONG_DOUBLE_COMPLEX long double _Complex
LOGICAL C_BOOL _Bool CHARACTER C_CHAR char NOTE 18.7
ISO/IEC 9899:2011 specifies that the representations for nonnegative signed integers are the same as the
corresponding values of unsigned integers. Because Fortran does not provide direct support for unsigned
kinds of integers, the ISO_C_BINDING module does not make accessible named constants for their kind
type parameter values. A user can use the signed kinds of integers to interoperate with the unsigned types
and all their qualified versions as well. This has the potentially surprising side effect that the C type
unsigned char is interoperable with the type integer with a kind type parameter of C_SIGNED_CHAR.
18.3.3 Interoperability with C pointer types
of these types is allocatable or a pointer. C_PTR is interoperable with any C object pointer type. C_FUNPTR1 Interoperability between a derived type in Fortran and a struct type in C is provided by the BIND attribute onis interoperable with any C function pointer type.
NOTE 18.8
This means that only a C processor with the same representation method for all C object pointer types,
and the same representation method for all C function pointer types, can be the target of interoperability
of a Fortran processor. ISO/IEC 9899:2011 does not require this to be the case.
NOTE 18.9
The function C_LOC can be used to return a value of type C_PTR that is the C address of an allocated
allocatable variable. The function C_FUNLOC can be used to return a value of type C_FUNPTR that is
the C address of a procedure. For C_LOC and C_FUNLOC the returned value is of an interoperable type
and thus can be used in contexts where the procedure or allocatable variable is not directly allowed. For
example, it could be passed as an actual argument to a C function.
Similarly, type C_FUNPTR or C_PTR can be used in a dummy argument or structure component and
can have a value that is the C address of a procedure or allocatable variable, even in contexts where a
procedure or allocatable variable is not directly allowed.
18.3.4 Interoperability of derived types and C struct types
the Fortran type.2 A derived type is interoperable with a C struct type if and only if the derived type has the BIND attribute (7.5.2),C1801 (R726) A derived type with the BIND attribute shall not have the SEQUENCE attribute.
486 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
C1802 (R726) A derived type with the BIND attribute shall not have type parameters.
C1803 (R726) A derived type with the BIND attribute shall not have the EXTENDS attribute.
C1804 (R726) A derived-type-def that defines a derived type with the BIND attribute shall not have a type-
bound-procedure-part.
C1805 (R726) A derived type with the BIND attribute shall have at least one component.
C1806 (R726) Each component of a derived type with the BIND attribute shall be a nonpointer, nonallocatable
data component with interoperable type and type parameters.
NOTE 18.10
The syntax rules and their constraints require that a derived type that is interoperable with a C struct
type have components that are all data entities that are interoperable. No component is permitted to be
allocatable or a pointer, but the value of a component of type C_FUNPTR or C_PTR can be the C address
of such an entity.
the derived type and the C struct type have the same number of components, and the components of the derived3 There is no Fortran type that is interoperable with a C struct type that contains a bit field or that contains atype would interoperate with corresponding components of the C struct type as described in 18.3.5 and 18.3.6 if
the components were variables. A component of a derived type and a component of a C struct type correspond
if they are declared in the same relative position in their respective type definitions.
NOTE 18.11
The names of the corresponding components of the derived type and the C struct type need not be the
same.
flexible array member. There is no Fortran type that is interoperable with a C union type.NOTE 18.12
For example, the C type myctype, declared below, is interoperable with the Fortran type myftype, declared
below.
typedef struct {
int m, n;
float r;
} myctype;
USE, INTRINSIC :: ISO_C_BINDING
TYPE, BIND(C) :: MYFTYPE
INTEGER(C_INT) :: I, J
REAL(C_FLOAT) :: S
END TYPE MYFTYPE
The names of the types and the names of the components are not significant for the purposes of determining
whether a Fortran derived type is interoperable with a C struct type.
NOTE 18.13
ISO/IEC 9899:2011 requires the names and component names to be the same in order for the types to be
compatible (ISO/IEC 9899:2011, subclause 6.2.7). This is similar to Fortran’s rule describing when different
derived type definitions describe the same sequence type. This rule was not extended to determine whether
3 A formal parameter of a C function prototype corresponds to a dummy argument of a Fortran interface if they
⃝c ISO/IEC 2017 – All rights reserved 487
ISO/IEC DIS 1539-1:2017 (E)
NOTE 18.13 (cont.)a Fortran derived type is interoperable with a C struct type because the case of identifiers is significant in
C but not in Fortran.
18.3.5 Interoperability of scalar variables 1 A named scalar Fortran variable is interoperable if and only if its type and type parameters are interoperable, it is not a coarray, it has neither the ALLOCATABLE nor the POINTER attribute, and if it is of type character2 An interoperable scalar Fortran variable is interoperable with a scalar C entity if their types and type parametersits length is not assumed or declared by an expression that is not a constant expression.
are interoperable.1 A Fortran variable that is a named array is interoperable if and only if its type and type parameters are interop-18.3.6 Interoperability of array variables
erable, it is not a coarray, it is of explicit shape or assumed size, and if it is of type character its length is not2 An explicit-shape or assumed-size array of rank r, with a shape of e1 . . . er is interoperable with a C arrayassumed or declared by an expression that is not a constant expression.
if its size is nonzero and1 A Fortran procedure is interoperable if and only if it has the BIND attribute, that is, if its interface is specified(1) either
(a) the array is assumed-size, and the C array does not specify a size, or
(b) the array is an explicit-shape array, and the extent of the last dimension (er ) is the same as
the size of the C array, and
(2) either
(a) r is equal to one, and an element of the array is interoperable with an element of the C array,
or
(b) r is greater than one, and an explicit-shape array with shape of e1 . . . er−1 , with the
same type and type parameters as the original array, is interoperable with a C array of a type
equal to the element type of the original C array.
NOTE 18.14
An element of a multi-dimensional C array is an array type, so a Fortran array of rank one is not interop-
erable with a multidimensional C array.
NOTE 18.15
An allocatable array or array pointer is never interoperable. Such an array does not meet the requirement
of being an explicit-shape or assumed-size array.
NOTE 18.16
For example, a Fortran array declared as
INTEGER(C_INT) :: A(18, 3:7, *)
is interoperable with a C array declared as
int b[][5][18];
488 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
NOTE 18.17
The C programming language defines null-terminated strings, which are actually arrays of the C type char
that have a C null character in them to indicate the last valid element. A Fortran array of type character
with a kind type parameter equal to C_CHAR is interoperable with a C string.
Fortran’s rules of sequence association (<IP_ADDRESS>) permit a character scalar actual argument to correspond
to a dummy argument array. This makes it possible to argument associate a Fortran character string with
a C string.
NOTE 18.21 has an example of interoperation between Fortran and C strings.
18.3.7 Interoperability of procedures and procedure interfaces
with a proc-language-binding-spec.2 A Fortran procedure interface is interoperable with a C function prototype if
(1) the interface has the BIND attribute,NOTE 18.18(2) either
(a) the interface describes a function whose result is a scalar variable that is interoperable with
the result of the prototype or
(b) the interface describes a subroutine and the prototype has a result type of void,
(3) the number of dummy arguments of the interface is equal to the number of formal parameters of the
prototype,
(4) any scalar dummy argument with the VALUE attribute is interoperable with the corresponding
formal parameter of the prototype,
(5) any dummy argument without the VALUE attribute corresponds to a formal parameter of the pro-
totype that is of a pointer type, and either
• the dummy argument is interoperable with an entity of the referenced type (ISO/IEC 9899:2011,
6.2.5, 7.19, and 7.20.1) of the formal parameter,
• the dummy argument is a nonallocatable nonpointer variable of type CHARACTER with
assumed character length and the formal parameter is a pointer to CFI_cdesc_t,
• the dummy argument is allocatable, assumed-shape, assumed-rank, or a pointer without the
CONTIGUOUS attribute, and the formal parameter is a pointer to CFI_cdesc_t, or
• the dummy argument is assumed-type and not allocatable, assumed-shape, assumed-rank, or
a pointer, and the formal parameter is a pointer to void,
(6) each allocatable or pointer dummy argument of type CHARACTER has deferred character length,
and
(7) the prototype does not have variable arguments as denoted by the ellipsis (...).
The referenced type of a C pointer type is the C type of the object that the C pointer type points to.
For example, the referenced type of the pointer type int * is int.
NOTE 18.19
The C language allows specification of a C function that can take a variable number of arguments (ISO/IEC
9899:2011, 7.16). This document does not provide a mechanism for Fortran procedures to interoperate with
such C functions.
are in the same relative positions in the C parameter list and the dummy argument list, respectively.4 In a reference from C to a Fortran procedure with an interoperable interface, a C actual argument shall be the⃝c ISO/IEC 2017 – All rights reserved 489
ISO/IEC DIS 1539-1:2017 (E)
address of a C descriptor for the intended effective argument if the corresponding dummy argument interoperates5 When an interoperable Fortran procedure with a simply contiguous dummy argument is invoked from C and thewith a C formal parameter that is a pointer to CFI_cdesc_t. In this C descriptor, the members other than
attribute and type shall describe an object with the same characteristics as the intended effective argument.
The value of the attribute member of the C descriptor shall be compatible with the characteristics of the dummy
argument. The type member shall have a value that depends on the intended effective argument as follows:
• if the dynamic type of the intended effective argument is an interoperable type listed in Table 18.4, the
corresponding value for that type;
• if the dynamic type of the intended effective argument is an intrinsic type for which the processor defines
a nonnegative type specifier value not listed in Table 18.4, that type specifier value;
• otherwise, CFI_type_other.
actual argument is the address of a C descriptor for a discontiguous object, the Fortran processor shall handle6 When an interoperable C procedure whose Fortran interface has a simply contiguous dummy argument is invokedthe difference in contiguity.
from Fortran and the effective argument is discontiguous, the Fortran processor shall ensure that the C procedure7 When an interoperable C procedure whose Fortran interface has a simply contiguous dummy argument is invokedreceives a descriptor for a contiguous object.
from C, and the actual argument is the address of a C descriptor for a discontiguous object, the C code within8 If an interoperable procedure defined by means other than Fortran has an optional dummy argument, and thethe procedure shall be prepared to handle the discontiguous argument.
corresponding actual argument in a reference from Fortran is absent, the procedure is invoked with a null pointerfor that argument. If an interoperable procedure defined by means of Fortran is invoked by a C function, an
optional dummy argument is absent if and only if the corresponding argument in the invocation is a null pointer.
NOTE 18.20
For example, a Fortran procedure interface described by
INTERFACE
FUNCTION FUNC(I, J, K, L, M) BIND(C)
USE, INTRINSIC :: ISO_C_BINDINGINTEGER(C_SHORT) :: FUNC
INTEGER(C_INT), VALUE :: I
REAL(C_DOUBLE) :: J
INTEGER(C_INT) :: K, L(10)
TYPE(C_PTR), VALUE :: M
END FUNCTION FUNC
END INTERFACE
is interoperable with the C function prototype
short func(int i, double *j, int *k, int l[10], void *m);
A C pointer can correspond to a Fortran dummy argument of type C_PTR with the VALUE attribute or
to a Fortran scalar that does not have the VALUE attribute. In the above example, the C pointers j and
k correspond to the Fortran scalars J and K, respectively, and the C pointer m corresponds to the Fortran
dummy argument M of type C_PTR.
490 c ISO/IEC 2017 – All rights reservedNOTE 18.21
ISO/IEC DIS 1539-1:2017 (E)
The interoperability of Fortran procedure interfaces with C function prototypes is only one part of invocation
of a C function from Fortran. There are four pieces to consider in such an invocation: the procedure
reference, the Fortran procedure interface, the C function prototype, and the C function. Conversely,
the invocation of a Fortran procedure from C involves the function reference, the C function prototype,
the Fortran procedure interface, and the Fortran procedure. In order to determine whether a reference is
allowed, it is necessary to consider all four pieces.
For example, consider a C function that can be described by the C function prototype
void copy(char in[], char out[]);
Such a function can be invoked from Fortran as follows:
USE, INTRINSIC :: ISO_C_BINDING, ONLY: C_CHAR, C_NULL_CHAR
INTERFACE
SUBROUTINE COPY(IN, OUT) BIND(C)
IMPORT C_CHAR
CHARACTER(KIND=C_CHAR), DIMENSION(*) :: IN, OUT
END SUBROUTINE COPY
END INTERFACE
CHARACTER(LEN=10, KIND=C_CHAR) :: &
& DIGIT_STRING = C_CHAR_’123456789’ // C_NULL_CHAR CHARACTER(KIND=C_CHAR) :: DIGIT_ARR(10)CALL COPY(DIGIT_STRING, DIGIT_ARR)
PRINT ’(1X, A1)’, DIGIT_ARR(1:9)
END
The procedure reference has character string actual arguments. These correspond to character array dummy
arguments in the procedure interface body as allowed by Fortran’s rules of sequence association (<IP_ADDRESS>).
Those array dummy arguments in the procedure interface are interoperable with the formal parameters of
the C function prototype. The C function is not shown here, but is assumed to be compatible with the C
function prototype.
NOTE 18.22
The requirements on the Fortran processor when a discontiguous actual argument is being passed to a
simply contiguous dummy argument are such that the C programmer has the same functionality (and
safety) as the Fortran programmer, when either the calling or called procedure are Fortran procedures. The
requirements on the C procedure, in the case when both the called and calling procedure are C procedures,
effectively require that the C procedure not access memory through the descriptor that is not described by
the descriptor; otherwise the program will not conform to this document. A dummy argument is simply
contiguous if it has the CONTIGUOUS attribute or is an array that is not assumed-shape, assumed-rank,
or a pointer.
18.4 C descriptors 1 A C descriptor is a C structure of type CFI_cdesc_t. Together with library functions that have standard
prototypes, it provides a means for describing and manipulating Fortran data objects from within a C function.1 The source file ISO_Fortran_binding.h shall contain the C structure definitions, typedef declarations, macroThis C structure is defined in the source file ISO_Fortran_binding.h.
⃝c ISO/IEC 2017 – All rights reserved 491
ISO/IEC DIS 1539-1:2017 (E)
18.5 The source file ISO_Fortran_binding.h
18.5.1 Summary of contents
definitions, and function prototypes specified in subclauses 18.5.2 to 18.5.5. The definitions and declarations in2 The source file ISO_Fortran_binding.h may be included in any order relative to the standard C headers, andISO_Fortran_binding.h can be used by a C function to interpret and manipulate a C descriptor. These provide
a means to specify a C prototype that interoperates with a Fortran interface that has a non-interoperable dummy
variable (18.3.7).
may be included more than once in a given scope, with no effect different from being included only once, other3 A C source file that includes the ISO_Fortran_binding.h header file shall not use any names starting withthan the effect on line numbers.
CFI_ that are not defined in the header, and shall not define any of the structure names defined in the header1 CFI_dim_t is a typedef name for a C structure. It is used to represent lower bound, extent, and memory strideas macro names. All names other than structure member names defined in the header begin with CFI_ or an
underscore character, or are defined by a standard C header that it includes.
18.5.2 The CFI_dim_t structure type
information for one dimension of an array. The type CFI_index_t is described in 18.5.4. CFI_dim_t contains1 CFI_cdesc_t is a typedef name for a C structure, which contains a flexible array member. It shall contain at leastat least the following members in any order.
CFI_index_t lower_bound; The value is equal to the value of the lower bound for the dimension being
described.
CFI_index_t extent; The value is equal to the number of elements in the dimension being described, or −1
for the final dimension of an assumed-size array.
CFI_index_t sm; The value is equal to the memory stride for a dimension; this is the difference in bytes
between the addresses of successive elements in the dimension being described.
18.5.3 The CFI_cdesc_t structure type
the members described in this subclause. The values of these members of a structure of type CFI_cdesc_t that2 The first three members of the structure shall be base_addr, elem_len, and version in that order. The finalis produced by the functions and macros specified in this document, or received by a C function when invoked
by a Fortran procedure, shall have the properties described in this subclause.
member shall be dim. All other members shall be between version and dim, in any order. The types CFI_-3 For a C descriptor of an array pointer or allocatable array, the value of the lower_bound member of each elementattribute_t, CFI_rank_t, and CFI_type_t are described in 18.5.4. The type CFI_dim_t is described in 18.5.2.
void * base_addr; If the object is an unallocated allocatable variable or a pointer that is disassociated, the
value is a null pointer. If the object has zero size, the value is not a null pointer but is otherwise processor-
dependent. Otherwise, the value is the base address of the object being described. The base address of a
scalar is its C address. The base address of an array is the C address of the first element in Fortran array
element order.
size_t elem_len; If the object is scalar, the value is the storage size in bytes of the object; otherwise, the value
is the storage size in bytes of an element of the object.
int version; The value is equal to the value of CFI_VERSION in the source file ISO_Fortran_binding.h that
defined the format and meaning of this C descriptor when the descriptor was established.
492 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
CFI_rank_t rank; The value is equal to the number of dimensions of the Fortran object being described; if
the object is scalar, the value is zero.
CFI_type_t type; The value is equal to the specifier for the type of the object. Each interoperable intrinsic C
type has a specifier. Specifiers are also provided to indicate that the type of the object is an interoperable
structure, or is unknown. The macros listed in Table 18.4 provide values that correspond to each specifier.
CFI_attribute_t attribute; The value is equal to the value of an attribute code that indicates whether the
object described is allocatable, a data pointer, or a nonallocatable nonpointer data object. The macros
listed in Table 18.3 provide values that correspond to each code.
CFI_dim_t dim; The number of elements in the dim array is equal to the rank of the object. Each element of
the array contains the lower bound, extent, and memory stride information for the corresponding dimension
of the Fortran object.
of the dim member of the descriptor is determined by argument association, allocation, or pointer association.4 There shall be an ordering of the dimensions such that the absolute value of the sm member of the first dimensionFor a C descriptor of a nonallocatable nonpointer object, the value of the lower_bound member of each element
of the dim member of the descriptor is zero.
is not less than the elem_len member of the C descriptor and the absolute value of the sm member of each5 In a C descriptor of an assumed-size array, the extent member of the last element of the dim member has thesubsequent dimension is not less than the absolute value of the sm member of the previous dimension multiplied
by the extent of the previous dimension.
value −1.1 Except for CFI_CDESC_T, each macro defined in ISO_Fortran_binding.h expands to an integer constantNOTE 18.23
The reason for the restriction on the absolute values of the sm members is to ensure that there is no overlap
between the elements of the array that is being described, while allowing for the reordering of subscripts.
Within Fortran, such a reordering can be achieved with the intrinsic function TRANSPOSE or the intrinsic
function RESHAPE with the optional argument ORDER, and an optimizing compiler can accommodate it
without making a copy by constructing the appropriate descriptor whenever it can determine that a copy
is not needed.
NOTE 18.24
The value of elem_len for a Fortran CHARACTER object is equal to the character length times the number
of bytes of a single character of that kind. If the kind is C_CHAR, this value will be equal to the character
length.
18.5.4 Macros and typedefs in ISO_Fortran_binding.h
expression that is either a single token or a parenthesized expression that is suitable for use in #if preprocessing2 CFI_CDESC_T is a function-like macro that takes one argument, which is the rank of the C descriptor to create,directives.
and evaluates to an unqualified type of suitable size and alignment for defining a variable to use as a C descriptor3 CFI_index_t is a typedef name for a standard signed integer type capable of representing the result of subtractingof that rank. The argument shall be an integer constant expression with a value that is greater than or equal to
zero and less than or equal to CFI_MAX_RANK. A pointer to a variable declared using CFI_CDESC_T can
be cast to CFI_cdesc_t *. A variable declared using CFI_CDESC_T shall not have an initializer.
⃝c ISO/IEC 2017 – All rights reserved 493
ISO/IEC DIS 1539-1:2017 (E)
NOTE 18.25
The CFI_CDESC_T macro provides the memory for a C descriptor. The address of an entity declared
using the macro is not usable as an actual argument corresponding to a formal parameter of type CFI_-
cdesc_t * without an explicit cast. For example, the following code uses CFI_CDESC_T to declare a C
descriptor of rank 5 and pass it to CFI_deallocate (<IP_ADDRESS>).
CFI_CDESC_T(5) object;
int ind;
... code to define and use C descriptor ...
ind = CFI_deallocate((CFI_cdesc_t *)&object);
two pointers.4 The CFI_MAX_RANK macro has a processor-dependent value equal to the largest rank supported. The value
shall be greater than or equal to 15. CFI_rank_t is a typedef name for a standard integer type capable of5 The CFI_VERSION macro has a processor-dependent value that encodes the version of the ISO_Fortran_-representing the largest supported rank.
binding.h source file containing this macro. This value should be increased if a new version of the source file is6 The macros in Table 18.3 are for use as attribute codes. The values shall be nonnegative and distinct. CFI_-incompatible with the previous version.
attribute_t is a typedef name for a standard integer type capable of representing the values of the attribute7 CFI_attribute_pointer specifies a data object with the Fortran POINTER attribute. CFI_attribute_allocatablecodes.
Table 18.3: ISO_Fortran_binding.h macros for attribute codes
Macro name Attribute
CFI_attribute_pointer data pointer
CFI_attribute_allocatable allocatable
CFI_attribute_other nonallocatable nonpointer
specifies an object with the Fortran ALLOCATABLE attribute. CFI_attribute_other specifies a nonallocatable8 The macros in Table 18.4 are for use as type specifiers. The value for CFI_type_other shall be negative andnonpointer object.
distinct from all other type specifiers. CFI_type_struct specifies a C structure that is interoperable with a9 If the processor supports interoperability of a Fortran intrinsic type with a C type not listed in Table 18.4,Fortran derived type; its value shall be positive and distinct from all other type specifiers. If a C type is not
interoperable with a Fortran type and kind supported by the Fortran processor, its macro shall evaluate to a
negative value. Otherwise, the value for an intrinsic type shall be positive.
the processor shall define a type specifier value for that type which is positive and distinct from all other type10 CFI_type_t is a typedef name for a standard integer type capable of representing the values for the supportedspecifiers.
type specifiers.11 The macros in Table 18.5 are for use as error codes. The macro CFI_SUCCESS shall be defined to be the integerTable 18.4: ISO_Fortran_binding.h macros for type codes
Macro name C Type
CFI_type_signed_char signed char
CFI_type_short short int
494 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
ISO_Fortran_binding.h macros for type codes (cont.)
Macro name C Type
CFI_type_int int
CFI_type_long long int
CFI_type_long_long long long int
CFI_type_size_t size_t
CFI_type_int8_t int8_t
CFI_type_int16_t int16_t
CFI_type_int32_t int32_t
CFI_type_int64_t int64_t
CFI_type_int_least8_t int_least8_t
CFI_type_int_least16_t int_least16_t
CFI_type_int_least32_t int_least32_t
CFI_type_int_least64_t int_least64_t
CFI_type_int_fast8_t int_fast8_t
CFI_type_int_fast16_t int_fast16_t
CFI_type_int_fast32_t int_fast32_t
CFI_type_int_fast64_t int_fast64_t
CFI_type_intmax_t intmax_t
CFI_type_intptr_t intptr_t
CFI_type_ptrdiff_t ptrdiff_t
CFI_type_float float
CFI_type_double double
CFI_type_long_double long double
CFI_type_float_Complex float _Complex
CFI_type_double_Complex double _Complex
CFI_type_long_double_Complex long double _Complex
CFI_type_Bool _Bool
CFI_type_char char
CFI_type_cptr void *
CFI_type_struct interoperable C structure
CFI_type_other Not otherwise specified
NOTE 18.26
The values for different C types can be the same; for example, CFI_type_int and CFI_type_int32_t might
have the same value.
constant 0. The value of each macro other than CFI_SUCCESS shall be nonzero and shall be different from the12 The values of the macros in Table 18.5 indicate the error condition described.values of the other macros specified in this subclause. Error conditions other than those listed in this subclause
should be indicated by error codes different from the values of the macros named in this subclause.
Table 18.5: ISO_Fortran_binding.h macros for error codes
Macro name Error condition CFI_SUCCESS No error detected. CFI_ERROR_BASE_ADDR_NULL The base address member of a C descriptor is a null pointer in a context that requires a non-null pointer value.CFI_ERROR_BASE_ADDR_NOT_NULL In a context that requires a null pointer value, the base
address member of a C descriptor is not a null pointer.
CFI_INVALID_ELEM_LEN The value supplied for the element length member of a C descriptor is not valid.
⃝c ISO/IEC 2017 – All rights reserved 495
ISO/IEC DIS 1539-1:2017 (E)
ISO_Fortran_binding.h macros for error codes (cont.)
Macro name Error condition CFI_INVALID_RANK The value supplied for the rank member of a C descriptor is not valid.
CFI_INVALID_TYPE The value supplied for the type member of a C descriptor is not valid.
CFI_INVALID_ATTRIBUTE The value supplied for the attribute member of a C descriptor is not valid.
CFI_INVALID_EXTENT The value supplied for the extent member of a CFI_dim_t structure is not valid.
CFI_INVALID_DESCRIPTOR A C descriptor is invalid in some way. CFI_ERROR_MEM_ALLOCATION Memory allocation failed. CFI_ERROR_OUT_OF_BOUNDS A reference is out of bounds.
18.5.5 Functions declared in ISO_Fortran_binding.h <IP_ADDRESS> Arguments and results of the functions 1 Some of the functions described in 18.5.5 return an error indicator; this is an integer value that indicates whether an error condition was detected. The value zero indicates that no error condition was detected, and a nonzero2 In function arguments representing subscripts, bounds, extents, or strides, the ordering of the elements is thevalue indicates which error condition was detected. Table 18.5 lists standard error conditions and macro names
for their corresponding error codes. A processor is permitted to detect other error conditions. If an invocation of
a function defined in 18.5.5 could detect more than one error condition and an error condition is detected, which
error condition is detected is processor dependent.
same as the ordering of the elements of the dim member of a C descriptor.3 Prototypes for these functions, or equivalent macros, are provided in the ISO_Fortran_binding.h file as described
in 18.5.5. It is unspecified whether the functions defined by this header are macros or identifiers declared with1 Synopsis. C address of an object described by a C descriptor.external linkage. If a macro definition is suppressed in order to access an actual function, the behavior is undefined.
NOTE 18.27
These functions are allowed to be macros to provide extra implementation flexibility. For example, CFI_-
establish could include the value of CFI_VERSION in the header used to compile the call to CFI_establish
as an extra argument of the actual function used to establish the C descriptor.
<IP_ADDRESS> The CFI_address function
void *CFI_address(const CFI_cdesc_t *dv, const CFI_index_t subscripts[]);2 Formal Parameters.
dv shall be the address of a C descriptor describing the object. The object shall not be an unallocated3 Result Value. If the object is an array of rank n, the result is the C address of the element of the object thatallocatable variable or a pointer that is not associated.
subscripts shall be a null pointer or the address of an array of type CFI_index_t. If the object is an array,
subscripts shall be the address of an array of CFI_index_t with at least n elements, where n
is the rank of the object. The value of subscripts[i] shall be within the bounds of dimension i
specified by the dim member of the C descriptor except for the last dimension of a C descriptor for
an assumed-size array. For the C descriptor of an assumed-size array, the value of the subscript for
the last dimension shall not be less than the lower bound, and the subscript order value specified
by the subscripts shall not exceed the size of the array.
496 ⃝
c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
the first n elements of the subscripts argument would specify if used as subscripts. If the object is scalar, the4 Example. If dv is the address of a C descriptor for the Fortran array A declared asresult is its C address.
REAL(C_FLOAT) :: A(100, 100)the following code calculates the C address of A(5, 10):
CFI_index_t subscripts[2];float *address;
subscripts[0] = 4;
subscripts[1] = 9;
address = (float *) CFI_address(dv, subscripts );
<IP_ADDRESS> The CFI_allocate function 1 Synopsis. Allocate memory for an object described by a C descriptor. int CFI_allocate(CFI_cdesc_t *dv, const CFI_index_t lower_bounds[],2 Formal Parameters.const CFI_index_t upper_bounds[], size_t elem_len);
dv shall be the address of a C descriptor specifying the rank and type of the object. The base_-addr member of the C descriptor shall be a null pointer. If the type is not a character type, the
elem_len member shall specify the element length. The attribute member shall have a value of
CFI_attribute_allocatable or CFI_attribute_pointer.
lower_bounds shall be the address of an array with at least dv->rank elements, if dv->rank>0.
upper_bounds shall be the address of an array with at least dv->rank elements, if dv->rank>0.
elem_len If the type specified in the C descriptor type is a Fortran character type, the value of elem_len
shall be the storage size in bytes of an element of the object; otherwise, elem_len is ignored.
3 Description. Successful execution of CFI_allocate allocates memory for the object described by the C descriptor with the address dv using the same mechanism as the Fortran ALLOCATE statement, and assigns the4 Result Value. The result is an error indicator.address of that memory to dv->base_addr. The first dv->rank elements of the lower_bounds and upper_bounds
arguments provide the lower and upper Fortran bounds, respectively, for each corresponding dimension of the
object. The supplied lower and upper bounds override any current dimension information in the C descriptor.
If the rank is zero, the lower_bounds and upper_bounds arguments are ignored. If the type specified in the C
descriptor is a character type, the supplied element length overrides the current element-length information in
the descriptor.
If an error is detected, the C descriptor is not modified.
5 Example. If dv is the address of a C descriptor for the Fortran array A declared as REAL, ALLOCATABLE :: A(:, :)and the array is not allocated, the following code allocates it to be of shape [100, 500]:
CFI_index_t lower[2], upper[2];int ind;
⃝c ISO/IEC 2017 – All rights reserved 497
ISO/IEC DIS 1539-1:2017 (E)
lower[0] = 1; lower[1] = 1;upper[0] = 100; upper[1] = 500;
ind = CFI_allocate(dv, lower, upper, 0);
<IP_ADDRESS> The CFI_deallocate function 1 Synopsis. Deallocate memory for an object described by a C descriptor. int CFI_deallocate(CFI_cdesc_t *dv);2 Formal Parameter. dv shall be the address of a C descriptor describing the object. It shall have been allocated
using the same mechanism as the Fortran ALLOCATE statement. If the object is a pointer, it shall be associated3 Description. Successful execution of CFI_deallocate deallocates memory for the object using the same mech-with a target satisfying the conditions for successful deallocation by the Fortran DEALLOCATE statement
(9.7.3).
anism as the Fortran DEALLOCATE statement, and the base_addr member of the C descriptor becomes a null4 Result Value. The result is an error indicator.pointer.
If an error is detected, the C descriptor is not modified.
5 Example. If dv is the address of a C descriptor for the Fortran array A declared as
REAL, ALLOCATABLE :: A(:, :)and the array is allocated, the following code deallocates it:
int ind;ind = CFI_deallocate(dv);
<IP_ADDRESS> The CFI_establish function 1 Synopsis. Establish a C descriptor.
int CFI_establish(CFI_cdesc_t *dv, void *base_addr, CFI_attribute_t attribute,2 Formal Parameters.CFI_type_t type, size_t elem_len, CFI_rank_t rank,
const CFI_index_t extents[]);
dv shall be the address of a data object large enough to hold a C descriptor of the rank specified by3 Description. Successful execution of CFI_establish updates the object with the address dv to be an establishedrank. It shall not have the same value as either a C formal parameter that corresponds to a Fortran
actual argument or a C actual argument that corresponds to a Fortran dummy argument. It shall
not be the address of a C descriptor that describes an allocated allocatable object.
base_addr shall be a null pointer or the base address of the object to be described. If it is not a null pointer,
it shall be the address of a contiguous storage sequence that is appropriately aligned (ISO/IEC
9899:2011 3.2) for an object of the type specified by type.
attribute shall be one of the attribute codes in Table 18.3. If it is CFI_attribute_allocatable, base_addr
shall be a null pointer.
type shall be one of the type codes in Table 18.4.
498 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
elem_len If the type is equal to CFI_type_struct, CFI_type_other, or a Fortran character type code, elem_-
len shall be greater than zero and equal to the storage size in bytes of an element of the object.
Otherwise, elem_len will be ignored.
rank shall have a value in the range 0 ≤ rank ≤ CFI_MAX_RANK. It specifies the rank of the object.
extents is ignored if rank is equal to zero or if base_addr is a null pointer. Otherwise, it shall be the address
of an array with rank elements; the value of each element shall be nonnegative, and extents[i]
specifies the extent of dimension i of the object.
C descriptor for a nonallocatable nonpointer data object of known shape, an unallocated allocatable object, or a4 Result Value. The result is an error indicator.data pointer. If base_addr is not a null pointer, it is for a nonallocatable entity that is a scalar or a contiguous
array; if the attribute argument has the value CFI_attribute_pointer, the lower bounds of the object described
by dv are set to zero. If base_addr is a null pointer, the established C descriptor is for an unallocated allocatable,
a disassociated pointer, or is a C descriptor that has the attribute CFI_attribute_other but does not describe
a data object. If base_addr is the C address of a Fortran data object, the type and elem_len arguments shall be
consistent with the type and type parameters of the Fortran data object. The remaining properties of the object
are given by the other arguments.
If an error is detected, the object with the address dv is not modified.
NOTE 18.285 Examples.CFI_establish is used to initialize a C descriptor declared in C with CFI_CDESC_T before passing it to
any other functions as an actual argument, in order to set the rank, attribute, type and element length.
NOTE 18.29
A C descriptor with attribute CFI_attribute_other and base_addr a null pointer can be used as the
argument result in calls to CFI_section or CFI_select_part, which will produce a C descriptor for a
nonallocatable nonpointer data object.
Case (i): The following code fragment establishes a C descriptor for an unallocated rank-one allocatable arraythat can be passed to Fortran for allocation there.
CFI_rank_t rank;
CFI_CDESC_T(1) field;
int ind;
rank = 1;
ind = CFI_establish((CFI_cdesc_t *)&field, NULL, CFI_attribute_allocatable,
CFI_type_double, 0, rank, NULL);
Case (ii): Given the Fortran type definition
TYPE, BIND(C) :: T
REAL(C_DOUBLE) :: X
COMPLEX(C_DOUBLE_COMPLEX) :: Y
END TYPE
and a Fortran subprogram that has an assumed-shape dummy argument of type T, the following
code fragment creates a descriptor a_fortran for an array of size 100 that can be used as the actual
argument in an invocation of the subprogram from C:
typedef struct {double x; double _Complex y;} t;t a_c[100];
CFI_CDESC_T(1) a_fortran;
⃝c ISO/IEC 2017 – All rights reserved 499
ISO/IEC DIS 1539-1:2017 (E)
int ind;CFI_index_t extent[1];
extent[0] = 100;
ind = CFI_establish((CFI_cdesc_t *)&a_fortran, a_c, CFI_attribute_other,
CFI_type_struct, sizeof(t), 1, extent);
<IP_ADDRESS> The CFI_is_contiguous function 1 Synopsis. Test contiguity of an array. int CFI_is_contiguous(const CFI_cdesc_t * dv);2 Formal Parameter. dv shall be the address of a C descriptor describing an array. The base_addr member of
the C descriptor shall not be a null pointer.3 Result Value. The value of the result is 1 if the array described by dv is contiguous, and 0 otherwise.
NOTE 18.30Assumed-size and allocatable arrays are always contiguous, and therefore the result of CFI_is_contiguous
on a C descriptor for such an array will be equal to 1.
<IP_ADDRESS> The CFI_section function 1 Synopsis. Update a C descriptor for an array section for which each element is an element of a given array. int CFI_section(CFI_cdesc_t *result, const CFI_cdesc_t *source,2 Formal Parameters.const CFI_index_t lower_bounds[], const CFI_index_t upper_bounds[],
const CFI_index_t strides[]);
result shall be the address of a C descriptor with rank equal to the rank of source minus the number of3 Description. Successful execution of CFI_section updates the base_addr and dim members of the C descriptorzero strides. The attribute member shall have the value CFI_attribute_other or CFI_attribute_-
pointer. If the value of result is the same as either a C formal parameter that corresponds to a
Fortran actual argument or a C actual argument that corresponds to a Fortran dummy argument,
the attribute member shall have the value CFI_attribute_pointer.
source shall be the address of a C descriptor that describes a nonallocatable nonpointer array, an allocated
allocatable array, or an associated array pointer. The elem_len and type members of source shall
have the same values as the corresponding members of result.
lower_bounds shall be a null pointer or the address of an array with at least source->rank elements. If it is not
a null pointer, and stridei is zero or (upperi − lower_bounds[i] + stridei )/stridei > 0, the value
of lower_bounds[i] shall be within the bounds of dimension i of SOURCE.
upper_bounds shall be a null pointer or the address of an array with at least source->rank elements. If source
describes an assumed-size array, upper_bounds shall not be a null pointer. If it is not a null pointer
and stridei is zero or (upper_bounds[i] − loweri + stridei )/stridei > 0, the value of upper_-
bounds[i] shall be within the bounds of dimension i of SOURCE.
strides shall be a null pointer or the address of an array with at least source->rank elements.
with the address result to describe the array section determined by source, lower_bounds, upper_bounds, and4 Result Value. The result is an error indicator.strides, as follows.
500 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
The array section is equivalent to the Fortran array section SOURCE(sectsub1 , sectsub2 , ... sectsubn ), where
SOURCE is the array described by source, n is the rank of that array, and sectsubi is the subscript loweri if
stridei is zero, and the section subscript loweri : upperi : stridei otherwise. The value of loweri is the lower
bound of dimension i of SOURCE if lower_bounds is a null pointer and lower_bounds[i] otherwise. The value
of upperi is the upper bound of dimension i of SOURCE if upper_bounds is a null pointer and upper_bounds[i]
otherwise. The value of stridei is 1 if strides is a null pointer and strides[i] otherwise. If stridei has the
value zero, loweri shall have the same value as upperi .
If an error is detected, the C descriptor with the address result is not modified.
5 Examples.
Case (i): If source is already the address of a C descriptor for the rank-one Fortran array A, the lower1 Synopsis. Update a C descriptor for an array section for which each element is a part of the correspondingbounds of A are equal to 1, and the lower bounds in the C descriptor are equal to 0, the following
code fragment establishes a new C descriptor section and updates it to describe the array section
A(3::5):
CFI_index_t lower[1], strides[1];
CFI_CDESC_T(1) section;
int ind;
lower[0] = 2;
strides[0] = 5;
ind = CFI_establish((CFI_cdesc_t *)§ion, NULL, CFI_attribute_other,
CFI_type_float, 0, 1, NULL);
ind = CFI_section((CFI_cdesc_t *)§ion, source, lower, NULL, strides);
Case (ii): If source is already the address of a C descriptor for a rank-two Fortran assumed-shape array A
with lower bounds equal to 1, the following code fragment establishes a C descriptor and updates
it to describe the rank-one array section A(:, 42).
CFI_index_t lower[2], upper[2], strides[2];
CFI_CDESC_T(1) section;
int ind;
lower[0] = source->dim[0].lower_bound;
upper[0] = source->dim[0].lower_bound + source->dim[0].extent - 1;
strides[0] = 1;
lower[1] = upper[1] = source->dim[1].lower_bound + 41;
strides[1] = 0;
ind = CFI_establish((CFI_cdesc_t *)§ion, NULL, CFI_attribute_other,
CFI_type_float, 0, 1, NULL);
ind = CFI_section((CFI_cdesc_t *)§ion, source, lower, upper, strides);
<IP_ADDRESS> The CFI_select_part function
element of an array.2 Formal Parameters.int CFI_select_part(CFI_cdesc_t *result, const CFI_cdesc_t *source, size_t displacement,
size_t elem_len);
result shall be the address of a C descriptor; result->rank shall have the same value as source->rank3 Description. Successful execution of CFI_select_part updates the base_addr, dim, and elem_len members ofand result->attribute shall have the value CFI_attribute_other or CFI_attribute_pointer. If
⃝c ISO/IEC 2017 – All rights reserved 501
ISO/IEC DIS 1539-1:2017 (E)
the address specified by result is the value of a C formal parameter that corresponds to a For-
tran actual argument or of a C actual argument that corresponds to a Fortran dummy argument,
result->attribute shall have the value CFI_attribute_pointer. The value of result->type spe-
cifies the type of the array section.
source shall be the address of a C descriptor for an allocated allocatable array, an associated array pointer,
or a nonallocatable nonpointer array that is not assumed-size.
displacement shall have a value 0 ≤ displacement ≤ source->elem_len −1, and the sum of the displacement
and the size in bytes of an element of the array section shall be less than or equal to source->elem_-
len. The address displacement bytes greater than the value of source->base_addr is the base of
the array section and shall be appropriately aligned (ISO/IEC 9899:2011, 3.2) for an object of the
type of the array section.
elem_len shall have a value equal to the storage size in bytes of an element of the array section if result->type
specifies a Fortran character type; otherwise, elem_len is ignored.
the C descriptor with the address result for an array section for which each element is a part of the corresponding4 Result Value. The result is an error indicator.element of the array described by the C descriptor with the address source. The part shall be a component of a
structure, a substring, or the real or imaginary part of a complex value.
If an error is detected, the C descriptor with the address result is not modified.
5 Example. If source is already the address of a C descriptor for the Fortran array A declared with
TYPE, BIND(C) :: TREAL(C_DOUBLE) :: X
COMPLEX(C_DOUBLE_COMPLEX) :: Y
END TYPE
TYPE(T) A(100)
the following code fragment establishes a C descriptor for the array A%Y:
typedef struct {double x; double _Complex y;
} t;
CFI_CDESC_T(1) component;
CFI_cdesc_t * comp_cdesc = (CFI_cdesc_t *)&component;
CFI_index_t extent[] = { 100 };
(void)CFI_establish(comp_cdesc, NULL, CFI_attribute_other, CFI_type_double_Complex,
sizeof(double _Complex), 1, extent);
(void)CFI_select_part(comp_cdesc, source, offsetof(t,y), 0);
<IP_ADDRESS> The CFI_setpointer function 1 Synopsis. Update a C descriptor for a Fortran pointer to be associated with the whole of a given object or to
be disassociated.2 Formal Parameters.int CFI_setpointer(CFI_cdesc_t *result, CFI_cdesc_t *source,
const CFI_index_t lower_bounds[]);
502 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
result shall be the address of a C descriptor for a Fortran pointer. It is updated using information fromthe source and lower_bounds arguments.
source shall be a null pointer or the address of a C descriptor for an allocated allocatable object, a data
pointer object, or a nonallocatable nonpointer data object that is not an assumed-size array. If
source is not a null pointer, the corresponding values of the elem_len, rank, and type members
shall be the same in the C descriptors with the addresses source and result.
lower_bounds If source is not a null pointer and source->rank is nonzero, lower_bounds shall be a null pointer
or the address of an array with at least source->rank elements.
3 Description. Successful execution of CFI_setpointer updates the base_addr and dim members of the C descriptor with the address result as follows:4 Result Value. The result is an error indicator.• if source is a null pointer or the address of a C descriptor for a disassociated pointer, the updated C
descriptor describes a disassociated pointer;
• otherwise, the C descriptor with the address result becomes a C descriptor for the object described by
the C descriptor with the address source, except that if source->rank is nonzero and lower_bounds is
not a null pointer, the lower bounds are replaced by the values of the first source->rank elements of the
lower_bounds array.
If an error is detected, the C descriptor with the address result is not modified.
5 Example. If ptr is already the address of a C descriptor for an array pointer of rank 1, the following code updates it to be a C descriptor for a pointer to the same array with lower bound 0.1 A C descriptor shall not be initialized, updated, or copied other than by calling the functions specified in 18.5.5.CFI_index_t lower_bounds[1];
int ind;
lower_bounds[0] = 0;
ind = CFI_setpointer(ptr, ptr, lower_bounds);
18.6 Restrictions on C descriptors
2 If the address of a C descriptor is a formal parameter that corresponds to a Fortran actual argument or a C
actual argument that corresponds to a Fortran dummy argument,3 If the address of a C descriptor is a C actual argument that corresponds to an assumed-shape Fortran dummy• the C descriptor shall not be modified if either the corresponding dummy argument in the Fortran interface
has the INTENT (IN) attribute or the C descriptor is for a nonallocatable nonpointer object, and
• the base_addr member of the C descriptor shall not be accessed before it is given a value if the corresponding
dummy argument in the Fortran interface has the POINTER and INTENT (OUT) attributes.
NOTE 18.31
In this context, modification refers to any change to the location or contents of the C descriptor, including
establishment and update. The intent of these restrictions is that C descriptors remain intact at all times
they are accessible to an active Fortran procedure, so that the Fortran code is not required to copy them.
argument, that descriptor shall not be for an assumed-size array.1 Within a C function, an allocatable object shall be allocated or deallocated only by execution of the CFI_-⃝c ISO/IEC 2017 – All rights reserved 503
ISO/IEC DIS 1539-1:2017 (E)
18.7 Restrictions on formal parameters
allocate and CFI_deallocate functions. A Fortran pointer can become associated with a target by execution of2 Calling CFI_allocate or CFI_deallocate for a C descriptor changes the allocation status of the Fortran variablethe CFI_allocate function.
it describes.3 If the address of an object is the value of a formal parameter that corresponds to a nonpointer dummy argument
in an interface with the BIND attribute, then4 If a formal parameter that is a pointer to CFI_cdesc_t corresponds to a dummy argument in an interoperable• if the dummy argument has the INTENT (IN) attribute, the object shall not be defined or become undefined,
and
• if the dummy argument has the INTENT (OUT) attribute, the object shall not be referenced before it is
defined.
procedure interface, a pointer based on the base_addr in that C descriptor shall not be used to access memory1 A C descriptor of, or C pointer to, any part of a Fortran object becomes undefined under the same conditionsthat is not part of the object described by the C descriptor.
18.8 Restrictions on lifetimes
that the association status of a Fortran pointer associated with that object would become undefined, and any2 A C descriptor whose address is a formal parameter that corresponds to a Fortran dummy argument becomesfurther use of it is undefined behavior (ISO/IEC 9899:2011, 3.4.3).
undefined on return from a call to the function from Fortran. If the dummy argument does not have either the3 If the address of a C descriptor is passed as an actual argument to a Fortran procedure, the lifetime (ISO/IECTARGET or ASYNCHRONOUS attribute, all C pointers to any part of the object described by the C descriptor
become undefined on return from the call, and any further use of them is undefined behavior.
9899:2011, 6.2.4) of the C descriptor shall not end before the return from the procedure call. If an object is passed4 If the lifetime of a C descriptor for an allocatable object that was established by C ends before the program exits,to a Fortran procedure as a nonallocatable, nonpointer dummy argument, its lifetime shall not end before the
return from the procedure call.
the object shall be unallocated at that time.5 If a Fortran pointer becomes associated with a data object defined by the companion processor, the association
status of the Fortran pointer becomes undefined when the lifetime of that data object ends.NOTE 18.32
The following example illustrates how a C descriptor becomes undefined upon returning from a call to a C
function.
REAL, TARGET :: X(1000), B
INTERFACE
REAL FUNCTION CFUN(ARRAY) BIND(C, NAME="Cfun")
REAL ARRAY(:)
END FUNCTION
END INTERFACE
B = CFUN(X)
1 A C variable whose name has external linkage may interoperate with a common block or with a variable declared in
504 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)NOTE 18.32 (cont.)
Cfun is a C function. Before or during the invocation of Cfun, the processor will create a C descriptor
for the array x. On return from Cfun, that C descriptor will become undefined. In addition, because the
dummy argument ARRAY does not have the TARGET or ASYNCHRONOUS attribute, a C pointer whose
value was set during execution of Cfun to be the address of any part of X will become undefined.
18.9 Interoperation with C global variables
18.9.1 General
the scope of a module. The common block or variable shall be specified to have the BIND attribute.2 At most one variable that is associated with a particular C variable whose name has external linkage is permitted
to be declared within all the Fortran program units of a program. A variable shall not be initially defined by3 If a common block is specified in a BIND statement, it shall be specified in a BIND statement with the same binding label in eachmore than one processor.
scoping unit in which it is declared. A C variable whose name has external linkage interoperates with a common block that has been4 There does not have to be an associated C entity for a Fortran entity with the BIND attribute.specified in a BIND statement if
• the C variable is of a struct type and the variables that are members of the common block are interoperable with corresponding
components of the struct type, or
• the common block contains a single variable, and the variable is interoperable with the C variable.
NOTE 18.33The following are examples of the usage of the BIND attribute for variables and for a common block. The
Fortran variables, C_EXTERN and C2, interoperate with the C variables, c_extern and myVariable,
respectively. The Fortran common blocks, COM and SINGLE, interoperate with the C variables, com and single, respectively.
MODULE LINK_TO_C_VARS
USE, INTRINSIC :: ISO_C_BINDING
INTEGER(C_INT), BIND(C) :: C_EXTERN
INTEGER(C_LONG) :: C2
BIND(C, NAME=’myVariable’) :: C2
COMMON /COM/ R, S
REAL(C_FLOAT) :: R, S, T
BIND(C) :: /COM/, /SINGLE/
COMMON /SINGLE/ T
END MODULE LINK_TO_C_VARS
/* Global variables. */
int c_extern;
long myVariable;
struct { float r, s; } com;
float single;
1 The binding label of a variable or common block is a default character value that specifies the name by which the
⃝c ISO/IEC 2017 – All rights reserved 505
ISO/IEC DIS 1539-1:2017 (E)
18.9.2 Binding labels for common blocks and variables
variable or common block is known to the companion processor.2 If a variable or common block has the BIND attribute with the NAME= specifier and the value of its expression,
after discarding leading and trailing blanks, has nonzero length, the variable or common block has this as its binding3 The binding label of a C variable whose name has external linkage is the same as the name of the C variable. Alabel. The case of letters in the binding label is significant. If a variable or common block has the BIND attribute
specified without a NAME= specifier, the binding label is the same as the name of the entity using lower case
letters. Otherwise, the variable or common block has no binding label.
Fortran variable or common block with the BIND attribute that has the same binding label as a C variable whose1 A procedure that is interoperable may be defined either by means other than Fortran or by means of a Fortranname has external linkage is linkage associated (<IP_ADDRESS>) with that variable.
18.10 Interoperation with C functions
18.10.1 Definition and reference of interoperable procedures
subprogram, but not both. A C function that has an inline definition and no external definition is not considered2 If the procedure is defined by means other than Fortran,to be defined in this sense.
• it shall be describable by a C prototype that is interoperable with the interface, and3 A reference to such a procedure causes the function described by the C prototype to be called as specified in• if it is accessed using its binding label, it shall
– have a name that has external linkage as defined by 6.2.2 of ISO/IEC 9899:2011, and
– have the same binding label as the interface.
ISO/IEC 9899:2011.4 A reference in C to a procedure that has the BIND attribute, has the same binding label, and is defined by means
of Fortran, causes the Fortran procedure to be invoked. A C function shall not invoke a function pointer whose5 A procedure defined by means of Fortran shall not invoke setjmp or longjmp (ISO/IEC 9899:2011, 7.13). If avalue is the result of a reference to C_FUNLOC with a noninteroperable argument.
procedure defined by means other than Fortran invokes setjmp or longjmp, that procedure shall not cause any6 If a procedure defined by means of Fortran and a procedure defined by means other than Fortran performprocedure defined by means of Fortran to be invoked. A procedure defined by means of Fortran shall not be
invoked as a signal handler (ISO/IEC 9899:2011, 7.14.1).
input/output operations on the same external file, the results are processor dependent (12.5.4).7 If the value of a C function pointer will be the result of a reference to C_FUNLOC with a noninteroperable
argument, it is recommended that the C function pointer be declared to have the type void (*)().1 The binding label of a procedure is a default character value that specifies the name by which a procedure with18.10.2 Binding labels for procedures
the BIND attribute is known to the companion processor.2 If a procedure has the BIND attribute with the NAME= specifier and the value of its expression, after discarding
leading and trailing blanks, has nonzero length, the procedure has this as its binding label. The case of letters3 The binding label for a C function whose name has external linkage is the same as the C function name.in the binding label is significant. If a procedure has the BIND attribute with no NAME= specifier, and the
506 ⃝
c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
procedure is not a dummy procedure, internal procedure, or procedure pointer, then the binding label of the
procedure is the same as the name of the procedure using lower case letters. Otherwise, the procedure has no
binding label.
C1807 A procedure defined in a submodule shall not have a binding label unless its interface is declared in the
ancestor module.
NOTE 18.34In the following sample, the binding label of C_SUB is "c_sub", and the binding label of C_FUNC is
"C_funC".
SUBROUTINE C_SUB() BIND(C)
...
END SUBROUTINE C_SUB
INTEGER(C_INT) FUNCTION C_FUNC() BIND(C, NAME="C_funC")
USE, INTRINSIC :: ISO_C_BINDING...
END FUNCTION C_FUNC
ISO/IEC 9899:2011 permits functions to have names that are not permitted as Fortran names; it also
distinguishes between names that would be considered as the same name in Fortran. For example, a C
name can begin with an underscore, and C names that differ in case are distinct names.
The specification of a binding label allows a program to use a Fortran name to refer to a procedure defined
by a companion processor.
18.10.3 Exceptions and IEEE arithmetic procedures 1 A procedure defined by means other than Fortran shall not use signal (ISO/IEC 9899:2011, 7.14.1) to change the
handling of any exception that is being handled by the Fortran processor.2 A procedure defined by means other than Fortran shall not alter the floating-point status (17.7) other than by
setting an exception flag to signaling.3 The values of the floating-point exception flags on entry to a procedure defined by means other than Fortran are
processor dependent.1 Asynchronous communication for a Fortran variable with the ASYNCHRONOUS attribute occurs through the18.10.4 Asynchronous communication
action of procedures defined by means other than Fortran. It is initiated by execution of an asynchronous2 Asynchronous communication is either input communication or output communication. For input communication,communication initiation procedure and completed by execution of an asynchronous communication completion
procedure. Between the execution of the initiation and completion procedures, any variable of which any part
is associated with any part of the asynchronous communication variable is a pending communication affector.
Whether a procedure is an asynchronous communication initiation or completion procedure is processor depend-
ent.
a pending communication affector shall not be referenced, become defined, become undefined, become associatedISO/IEC DIS 1539-1:2017 (E)with a dummy argument that has the VALUE attribute, or have its pointer association status changed. For
output communication, a pending communication affector shall not be redefined, become undefined, or have its
pointer association status changed. The restrictions for asynchronous input communication are the same as for
⃝c ISO/IEC 2017 – All rights reserved 507
asynchronous input data transfer. The restrictions for asynchronous output communication are the same as for
asynchronous output data transfer.
NOTE 18.35Asynchronous communication can be used for nonblocking MPI calls such as MPI_IRECV and MPI_-
ISEND. For example,
REAL :: BUF(100,100)
... ! Code that involves BUF
BLOCK
ASYNCHRONOUS :: BUF
CALL MPI_IRECV(BUF,...REQ,...)
... ! Code that does not involve BUFCALL MPI_WAIT(REQ,...)
END BLOCK
... ! Code that involves BUF
In this example, there is asynchronous input communication and BUF is a pending communication affector
between the two calls. MPI_IRECV can return while the communication (reading values into BUF) is still
underway. The intent is that the code between MPI_IRECV and MPI_WAIT can execute without waiting
for this communication to complete.
Similar code with the call of MPI_IRECV replaced by a call of MPI_ISEND is asynchronous output
communication.
508 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)19 Scope, association, and definition
19.1 Scopes, identifiers, and entities 1 An entity is identified by an identifier. 2 The scope of
• a global identifier is a program (5.2.2),excluding any nested scope where the identifier is treated as the identifier of a different entity (19.3, 19.4), or• a local identifier is an inclusive scope,
• an identifier of a construct entity is that construct (10.2.4, 11.1), and
• an identifier of a statement entity is that statement or part of that statement (6.3),
where an IMPORT statement (8.8) makes the identifier inaccessible.
3 An entity may be identified by
• an image index (3.85),4 By means of association, an entity may be referred to by the same identifier or a different identifier in a different• a name (3.103),
• a statement label (3.135),
• an external input/output unit number (12.5),
• an identifier of a pending data transfer operation (<IP_ADDRESS>, 12.7),
• a submodule identifier (14.2.3),
• a generic identifier (3.79), or
• a binding label (3.15).
scope, or by a different identifier in the same scope.1 Program units, common blocks, external procedures, entities with binding labels, external input/output units,19.2 Global identifiers
pending data transfer operations, and images are global entities of a program. The name of a common block with2 The global identifier of an entity shall not be the same as the global identifier of any other entity. Furthermore, ano binding label, external procedure with no binding label, or program unit that is not a submodule is a global
identifier. The submodule identifier of a submodule is a global identifier. A binding label of an entity of the
program is a global identifier. An entity of the program shall not be identified by more than one binding label.
binding label shall not be the same as the global identifier of any other global entity, ignoring differences in case.1 Identifiers of entities, other than statement or construct entities (19.4), in the classesA processor may assign a global identifier to an entity that is not specified by this document to have a global
identifier (such as an intrinsic procedure); in such a case, the processor shall ensure that this assigned global
identifier differs from all other global identifiers in the program.
NOTE 19.1
An intrinsic module is not a program unit, so a global identifier can be the same as the name of an intrinsic
module.
⃝c ISO/IEC 2017 – All rights reserved 509
ISO/IEC DIS 1539-1:2017 (E)
NOTE 19.2
Submodule identifiers are global identifiers, but because they consist of a module name and a descendant
submodule name, the name of a submodule can be the same as the name of another submodule so long as
they do not have the same ancestor module.
19.3 Local identifiers
19.3.1 Classes of local identifiers
(1) named variables, named constants, named procedure pointers, named constructs, statement functions,are local identifiers.internal procedures, module procedures, dummy procedures, intrinsic procedures, external procedures
that have binding labels, intrinsic modules, abstract interfaces, generic interfaces, derived types,
namelist groups, external procedures accessed via USE, and statement labels,
(2) type parameters, components, and type-bound procedure bindings, in a separate class for each type,
(3) argument keywords, in a separate class for each procedure with an explicit interface, and
(4) common blocks that have binding labels
2 Within its scope, a local identifier of an entity of class (1) or class (4) shall not be the same as a global identifier
used in that scope unless the global identifier3 Within its scope, a local identifier of one class shall not be the same as another local identifier of the same class,• is used only as the use-name of a rename in a USE statement,
• is a common block name (19.3.2),
• is an external procedure name that is also a generic name, or
• is an external function name and the inclusive scope is its defining subprogram (19.3.3).
except that a generic name may be the same as the name of a procedure as explained in <IP_ADDRESS> or the same asthe name of a derived type (7.5.10). A local identifier of one class may be the same as a local identifier of another
class.
NOTE 19.3
An intrinsic procedure is inaccessible by its own name in a scoping unit that uses the same name as a local
identifier of class (1) for a different entity. For example, in the program fragment
SUBROUTINE SUB
...
A = SIN (K)
...
CONTAINS
FUNCTION SIN (X)
...
END FUNCTION SIN
END SUBROUTINE SUB
any reference to function SIN in subroutine SUB refers to the internal function SIN, not to the intrinsic
function of the same name.
4 A local identifier identifies an entity in a scope and may be used to identify an entity in another scope except in
the following cases.1 A name that identifies a common block in a scoping unit shall not be used to identify a constant or an intrinsic procedure in that510 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
• The name that appears as a subroutine-name in a subroutine-stmt has limited use within the scope estab-
lished by the subroutine-stmt. It can be used to identify recursive references of the subroutine or to identify
a common block (the latter is possible only for internal and module subroutines).
• The name that appears as a function-name in a function-stmt has limited use within the scope established
by that function-stmt. It can be used to identify the function result, to identify recursive references of the
function, or to identify a common block (the latter is possible only for internal and module functions).
• The name that appears as an entry-name in an entry-stmt has limited use within the scope of the subprogram in which
the entry-stmt appears. It can be used to identify the function result if the subprogram is a function, to identify recursive
references, or to identify a common block (the latter is possible only if the entry-stmt is in a module subprogram).
19.3.2 Local identifiers that are the same as common block names
scoping unit. If a local identifier of class (1) is also the name of a common block, the appearance of that name in any context other1 For each FUNCTION statement or ENTRY statement in a function subprogram, there is a function result. A functionthan as a common block name in a BIND, COMMON, or SAVE statement is an appearance of the local identifier.
19.3.3 Function results
result is either a variable or a procedure pointer, and thus the name of a function result is a local identifier of1 A component name has the scope of its derived-type definition. Outside the type definition, it may also appearclass (1).
19.3.4 Components, type parameters, and bindings
within a designator of a component of a structure of that type or as a component keyword in a structure2 A type parameter name has the scope of its derived-type definition. Outside the derived-type definition, it mayconstructor for that type.
also appear as a type parameter keyword in a derived-type-spec for the type or as the type-param-name of a3 The binding name (7.5.5) of a type-bound procedure has the scope of its derived-type definition. Outside of thetype-param-inquiry.
derived-type definition, it may also appear as the binding-name in a procedure reference.4 A generic binding for which the generic-spec is not a generic-name has a scope that consists of all scoping units
in which an entity of the type is accessible.5 A component name or binding name may appear only in a scope in which it is accessible.
6 The accessibility of components and bindings is specified in <IP_ADDRESS> and 7.5.5.
19.3.5 Argument keywords1 As an argument keyword, a dummy argument name in an internal procedure, module procedure, or an interface
body has a scope of the scoping unit of the host of the procedure or interface body. As an argument keyword,2 A dummy argument name in an intrinsic procedure has a scope as an argument keyword of the scoping unitthe name of a dummy argument of a procedure declared by a procedure declaration statement that specifies an
explicit interface has a scope of the scoping unit containing the procedure declaration statement. It may appear
only in a procedure reference for the procedure of which it is a dummy argument. If the procedure is accessible
in another scoping unit by use or host association (<IP_ADDRESS>, <IP_ADDRESS>), the argument keyword is accessible for
procedure references for that procedure in that scoping unit.
⃝c ISO/IEC 2017 – All rights reserved 511
ISO/IEC DIS 1539-1:2017 (E)
in which the reference to the procedure occurs. As an argument keyword, it may appear only in a procedure1 A variable that appears as a data-i-do-variable in a DATA statement or an ac-do-variable in an array constructor,reference for the procedure of which it is a dummy argument.
19.4 Statement and construct entities
as a dummy argument in a statement function statement, or as an index-name in a FORALL statement is a statement entity. A2 Even if the name of a statement entity is the same as another identifier and the statement is in the scope of thatvariable that appears as an index-name in a FORALL or DO CONCURRENT, as an associate-name in a SELECT
TYPE or ASSOCIATE construct, or as a coarray-name in a codimension-decl in a CHANGE TEAM construct is
a construct entity. A variable that has LOCAL or LOCAL_INIT locality in a DO CONCURRENT construct is a
construct entity. An entity that is explicitly declared in the specification part of a BLOCK construct, other than
only in ASYNCHRONOUS and VOLATILE statements, is a construct entity. A USE statement in a BLOCK
construct explicitly declares the entities accessed by use association to be construct entities. Two construct
entities of the same construct shall not have the same identifier.
identifier, within the scope of the statement entity the name is interpreted as that of the statement entity.3 The name of a statement entity shall not be the same as an accessible global identifier or local identifier of class
(1) (19.3.1), except for a common block name or a scalar variable name. Within the scope of a statement entity,4 The name of a data-i-do-variable in a DATA statement or an ac-do-variable in an array constructor has a scopeanother statement entity shall not have the same name.
of its data-implied-do or ac-implied-do. It is a scalar variable. If integer-type-spec appears in data-implied-do or5 The name of a variable that appears as an index-name in a DO CONCURRENT construct, FORALL statement, orac-implied-do-control it has the specified type and type parameters; otherwise it has the type and type parameters
that it would have if it were the name of a variable in the innermost executable construct or scoping unit that
includes the DATA statement or array constructor, and this type shall be integer type. It has no other attributes.
The appearance of a name as a data-i-do-variable of an implied DO in a DATA statement or an ac-do-variable
in an array constructor is not an implicit declaration of a variable whose scope is the scoping unit that contains
the statement.
FORALL construct has a scope of the statement or construct. It is a scalar variable. If integer-type-spec appears in6 A variable that has LOCAL or LOCAL_INIT locality in a DO CONCURRENT construct has the scope of thatconcurrent-header it has the specified type and type parameters; otherwise it has the type and type parameters
that it would have if it were the name of a variable in the innermost executable construct or scoping unit that
includes the DO CONCURRENT or FORALL, and this type shall be integer type. It has no other attributes.
The appearance of a name as an index-name in a DO CONCURRENT construct, FORALL statement, or FORALL
construct is not an implicit declaration of a variable whose scope is the scoping unit that contains the statement or
construct.
construct. Its attributes are specified in <IP_ADDRESS>.7 If integer-type-spec does not appear in a concurrent-header, an index-name shall not be the same as an accessible
global identifier, local identifier, or identifier of an outer construct entity, except for a common block name or8 The associate name of a SELECT TYPE construct has a separate scope for each block of the construct. Withina scalar variable name. An index-name of a contained DO CONCURRENT construct, FORALL statement, or
FORALL construct shall not be the same as an index-name of any of its containing DO CONCURRENT or FORALL
constructs.
512 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
each block, it has the declared type, dynamic type, type parameters, rank, and bounds specified in <IP_ADDRESS>.9 The associate names of an ASSOCIATE construct have the scope of the block. They have the declared type,
dynamic type, type parameters, rank, and bounds specified in <IP_ADDRESS>.10 The associate names of a CHANGE TEAM construct have the scope of the block. They have the declared type,
dynamic type, type parameters, rank, corank, bounds, and cobounds specified in <IP_ADDRESS> The name of a variable that appears as a dummy argument in a statement function statement has a scope of the statement in which
it appears. It is a scalar that has the type and type parameters that it would have if it were the name of a variable in the scoping1 There are five forms of name association: argument association, use association, host association, linkage asso-unit that includes the statement function; it has no other attributes.
19.5 Association
19.5.1 Name association
<IP_ADDRESS> Forms of name association
ciation, and construct association. Argument, use, and host association provide mechanisms by which entities1 The rules governing argument association are given in Clause 15. As explained in 15.5, execution of a procedureknown in one scope may be accessed in another scope.
<IP_ADDRESS> Argument association
reference establishes a correspondence between each actual argument and a dummy argument and thus an associ-2 The name of the dummy argument may be different from the name, if any, of its effective argument. The dummyation between each present dummy argument and its effective argument. Argument association can be sequence
association (<IP_ADDRESS>).
argument name is the name by which the effective argument is known, and by which it may be accessed, in the3 Upon termination of execution of a procedure reference, all argument associations established by that referencereferenced procedure.
NOTE 19.4
An effective argument can be a nameless data entity, such as the result of evaluating an expression that is
not simply a variable or constant.
are terminated. A dummy argument of that procedure can be associated with an entirely different effective1 Use association is the association of names in different scopes specified by a USE statement. The rules governingargument in a subsequent invocation of the procedure.
<IP_ADDRESS> Use association
use association are given in 14.2.2. They allow for renaming of entities being accessed. Use association allowsISO/IEC DIS 1539-1:2017 (E)access in one scope to entities defined or declared in another scope; it remains in effect throughout the execution
of the program.
⃝c ISO/IEC 2017 – All rights reserved 513
<IP_ADDRESS> Host association 1 A nested scoping unit has access to named entities from its host as specified in 8.8. A host-associated variable is
considered to have been previously declared; any other host-associated entity is considered to have been previously2 If an entity that is accessed by use association has the same nongeneric name as a host entity, the host entity isdefined. In the case of an internal subprogram, the access is to the entities in its host instance. The accessed
entities are identified by the same identifier and have the same attributes as in the host, except that a local entity
may have the ASYNCHRONOUS attribute even if the host entity does not, and a noncoarray local entity may
have the VOLATILE attribute even if the host entity does not. The accessed entities are named data objects,
derived types, abstract interfaces, procedures, generic identifiers, and namelist groups.
inaccessible by that name. The name of an external procedure that is given the EXTERNAL attribute (8.5.9)3 If a host entity is inaccessible only because a local variable with the same name is wholly or partially initializedwithin the scoping unit, or a name that appears within the scoping unit as a module-name in a use-stmt is a
global identifier; any entity of the host that has this as its nongeneric name is inaccessible by that name. A name
that appears in the scoping unit as
(1) a function-name in a stmt-function-stmt or in an entity-decl in a type-declaration-stmt, unless it is a
global identifier,
(2) an object-name in an entity-decl in a type-declaration-stmt, in a pointer-stmt, in a save-stmt, in an
allocatable-stmt, or in a target-stmt,
(3) a type-param-name in a derived-type-stmt,
(4) a named-constant in a named-constant-def in a parameter-stmt,
(5) a coarray-name in a codimension-stmt,
(6) an array-name in a dimension-stmt,
(7) a variable-name in a common-block-object in a common-stmt,
(8) a procedure pointer given the EXTERNAL attribute in the scoping unit,
(9) the name of a variable that is wholly or partially initialized in a data-stmt,
(10) the name of an object that is wholly or partially equivalenced in an equivalence-stmt,
(11) a dummy-arg-name in a function-stmt, in a subroutine-stmt, in an entry-stmt, or in a stmt-function-stmt ,
(12) a result-name in a function-stmt or in an entry-stmt ,
(13) the name of an entity declared by an interface body, unless it is a global identifier,
(14) an intrinsic-procedure-name in an intrinsic-stmt,
(15) a namelist-group-name in a namelist-stmt,
(16) a generic-name in a generic-spec in an interface-stmt, or
(17) the name of a named construct
is a local identifier in the scoping unit and any entity of the host that has this as its nongeneric name is inaccessible
by that name by host association. If a scoping unit is the host of a derived-type definition or a subprogram that
does not define a separate module procedure, the name of the derived type or of any procedure defined by the
subprogram is a local identifier in the scoping unit; any entity of the host that has this as its nongeneric name is
inaccessible by that name. Local identifiers of a subprogram are not accessible to its host.
NOTE 19.5
A name that appears in an ASYNCHRONOUS or VOLATILE statement is not necessarily the name of a
local variable. In an internal or module procedure, if a variable that is accessible via host association is spe-
cified in an ASYNCHRONOUS or VOLATILE statement, that host variable is given the ASYNCHRONOUS
or VOLATILE attribute in the local scope.
514 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
in a DATA statement, the local variable shall not be referenced or defined prior to the DATA statement.4 If a derived-type name of a host is inaccessible, data entities of that type or subobjects of such data entities still
can be accessible.5 If an external or dummy procedure with an implicit interface is accessed via host association, then it shall haveNOTE 19.6
An interface body that is not a module procedure interface body accesses by host association only those
entities made accessible by IMPORT statements.
the EXTERNAL attribute in the host scoping unit; if it is invoked as a function in the inner scoping unit, its type6 If an intrinsic procedure is accessed via host association, then it shall be established to be intrinsic in the hostand type parameters shall be established in the host scoping unit. The type and type parameters of a function
with the EXTERNAL attribute are established in a scoping unit if that scoping unit explicitly declares them,
invokes the function, accesses the function from a module, or accesses the function from its host where its type
and type parameters are established.
scoping unit. An intrinsic procedure is established to be intrinsic in a scoping unit if that scoping unit explicitlygives it the INTRINSIC attribute, invokes it as an intrinsic procedure, accesses it from a module, or accesses it
from its host where it is established to be intrinsic.
NOTE 19.7
A host subprogram and an internal subprogram can contain the same and differing use-associated entities,
as illustrated in the following example.

CONTAINS
SUBROUTINE INNER_PROC (Q)
USE C ! Not neededUSE B, ONLY: BX ! Entities accessible are BX, IX, and JX
! if no other IX or JX
! is accessible to INNER_PROC
!  Entities accessible are DX, DY, and DZ
! X is local name for DX in INNER_PROC
! X and DX denote same entity if no other
! entity DX is local to INNER_PROC
USE E, ONLY: EX ! EX is accessible in INNER_PROC, not in program A
⃝c ISO/IEC 2017 – All rights reserved 515
ISO/IEC DIS 1539-1:2017 (E)
NOTE 19.7 (cont.)! EY and EZ are not accessible in INNER_PROC
! or in program A
USE G ! FX and GX are accessible in INNER_PROC
...
END SUBROUTINE INNER_PROC
END PROGRAM A
Because program A contains the statement
USE B
all of the entities in module B, except for Q, are accessible in INNER_PROC, even though INNER_PROC
contains the statement
USE B, ONLY: BX
The USE statement with the ONLY option means that this particular statement brings in only the entity
named, not that this is the only variable from the module accessible in this scoping unit.
NOTE 19.8
For more examples of host association, see subclause C.13.
<IP_ADDRESS> Linkage association 1 Linkage association occurs between a module variable that has the BIND attribute and the C variable with which
it interoperates, or between a Fortran common block and the C variable with which it interoperates (18.9). Such association1 Execution of a SELECT RANK or SELECT TYPE statement establishes an association between the selector andremains in effect throughout the execution of the program.
<IP_ADDRESS> Construct association
the associate name of the construct. Execution of an ASSOCIATE or CHANGE TEAM statement statement2 In an ASSOCIATE or SELECT TYPE construct, the following rules apply.establishes an association between each selector and the corresponding associate name of the construct.
• If a selector is allocatable, it shall be allocated; the associate name is associated with the data object and3 If the selector is a variable other than an array section having a vector subscript, the association is with the datadoes not have the ALLOCATABLE attribute.
• If a selector has the POINTER attribute, it shall be associated; the associate name is associated with the
target of the pointer and does not have the POINTER attribute.
object specified by the selector; otherwise, the association is with the value of the selector expression, which is4 Each associate name remains associated with the corresponding selector throughout the execution of the executedevaluated prior to execution of the block.
block. Within the block, each selector is known by and may be accessed by the corresponding associate name.1 Pointer association between a pointer and a target allows the target to be referenced by a reference to the pointer.On completion of execution of the construct, the association is terminated.
516 ⃝c ISO/IEC 2017 – All rights reserved
ISO/IEC DIS 1539-1:2017 (E)
NOTE 19.9
The association between the associate name and a data object is established prior to execution of the block
and is not affected by subsequent changes to variables that were used in subscripts or substring ranges in
the selector.
19.5.2 Pointer association
<IP_ADDRESS> General
At different times during the execution of a program, a pointer may be undefined, associated with different targets1 A pointer may have a pointer association status of associated, disassociated, or undefined. Its association statuson its own image, or be disassociated. If a pointer is associated with a target, the definition status of the pointer
is either defined or undefined, depending on the definition status of the target. If the pointer has deferred type
parameters or shape, their values are assumed from the target. If the pointer is polymorphic, its dynamic type
is assumed from the dynamic type of the target.
<IP_ADDRESS> Pointer association status
may change during execution of a program. Unless a pointer is initialized (explicitly or by default), it has an1 A pointer becomes associated when any of the following events occur.initial association status of undefined. A pointer may be initialized to have an association status of disassociated
or associated.
NOTE 19.10
A pointer from a module program unit might be accessible in a subprogram via use association. Such
pointers have a lifetime that is greater than targets that are declared in the subprogram, unless such targets
are saved. Therefore, if such a pointer is associated with a local target, there is the possibility that when
a procedure defined by the subprogram completes execution, the target will cease to exist, leaving the
pointer “dangling”. This document considers such pointers to have an undefined association status. They
are neither associated nor disassociated. They cannot be used again in the program until their status has
been reestablished. A processor is not required to detect when a pointer target ceases to exist.
<IP_ADDRESS> Events that cause pointers to become associated
(1) The pointer is allocated (9.7.1) as the result of the successful execution of an ALLOCATE statementreferencing the pointer.
(2) The pointer is pointer-assigned to a target (10.2.2) that is associated or is specified with the TARGET
attribute and, if allocatable, is allocated.
(3) The pointer is a subobject of an object that is allocated by an ALLOCATE statement in which
SOURCE= appears and the corresponding subobject of source-expr is associated.
(4) The pointer is a dummy argument and its corresponding actual argument is not a pointer.
(5) The pointer is a default-initialized subcomponent of an object, the corresponding initializer is not a
reference to the intrinsic function NULL, and
(a) a procedure is invoked with this object as an actual argument corresponding to a nonpointer
nonallocatable dummy argument with INTENT (OUT),
⃝c ISO/IEC 2017 – All rights reserved 517
ISO/IEC DIS 1539-1:2017 (E)
(b) a procedure with this object as an unsaved nonpointer nonallocatable local variable is invoked,(c) a BLOCK construct is entered and this object is an unsaved local nonpointer nonallocatable
local variable of the BLOCK construct,
or
(d) this object is allocated other than by an ALLOCATE statement in which SOURCE= appears.
<IP_ADDRESS> Events that cause pointers to become disassociated 1 A pointer becomes disassociated when (1) the pointer is nullified (9.7.2),(2) the pointer is deallocated (9.7.3),
(3) the pointer is pointer-assigned (10.2.2) to a disassociated pointer,
(4) the pointer is a subobject of an object that is allocated by an ALLOCATE statement in which
SOURCE= appears and the corresponding subobject of source-expr is disassociated,
or
(5) the pointer is a default-initialized subcomponent of an object, the corresponding initializer is a
reference to the intrinsic function NULL, and
(a) a procedure is invoked with this object as an actual argument corresponding to a nonpointer
nonallocatable dummy argument with INTENT (OUT),
(b) a procedure with this object as an unsaved nonpointer nonallocatable local variable is invoked,
(c) a BLOCK construct is entered and this object is an unsaved local nonpointer nonallocatable
local variable of the BLOCK construct,
or
(d) this object is allocated other than by an ALLOCATE statement in which SOURCE= appears.
<IP_ADDRESS> Events that cause the association status of pointers to become undefined 1 The association status of a pointer becomes undefined when (1) the pointer is pointer-assigned to a target that has an undefined association status,(2) the pointer is pointer-assigned to a target on a different image,
(3) the target of the pointer is deallocated other than through the pointer,
(4) the target of the pointer is a data object defined by the companion processor and the lifetime of that
data object ends,