[UP]


Manual Reference Pages  - iso_c_binding (7)

NAME

iso_c_binding(7f) - [FORTRAN]standard intrinsic module which defines named constants, types, and procedures for C interoperability

CONTENTS

Synopsis
Standard
Intrinsic Procedures
Named Constants
Interoperability With C
General
The Iso_c_binding Intrinsic Module
     Named Constants And Derived Types In The Module
Procedures In The Module

SYNOPSIS

Interoperability with C 1 General 2 The ISO C BINDING intrinsic module 15.2.1 Summary of contents 15.2.2 Named constants and derived types in the module 15.2.3 Procedures in the module 3 Interoperability between Fortran and C entities 15.3.1 General 15.3.2 Interoperability of intrinsic types 15.3.3 Interoperability with C pointer types 15.3.4 Interoperability of derived types and C struct types 15.3.5 Interoperability of scalar variables 15.3.6 Interoperability of array variables 15.3.7 Interoperability of procedures and procedure interfaces 4 Interoperation with C global variables 15.4.1 General 15.4.2 Binding labels for common blocks and variables 5 Interoperation with C functions 15.5.1 Definition and reference of interoperable procedures 15.5.2 Binding labels for procedures 15.5.3 Exceptions and IEEE arithmetic procedures

STANDARD

[[Fortran 2003]] and later

INTRINSIC PROCEDURES

The following intrinsic procedures are provided by the module; their definition can be found in man(1) pages:
o c_associated
o c_f_pointer
o c_f_procpointer
o c_funloc
o c_loc
o c_sizeof

NAMED CONSTANTS

iso_c_binding(7f) module also provides the following named constants of type default integer, which can be used as ‘kind‘ type parameters.

   #-------------#-------------------------#-----------------------#----------#
   | Fortran Type| Named constant          | C type                | Note     |
   |-------------|-------------------------|-----------------------|----------|
   |  integer    |  c_int                  |  int                  |          |
   |  integer    |  c_short                |  short int            |          |
   |  integer    |  c_long                 |  long int             |          |
   |  integer    |  c_long_long            |  long long int        |          |
   |  integer    |  c_signed_char          |  signed char/         |          |
   |             |                         |  unsigned  char       |          |
   |  integer    |  c_size_t               |  size_t               |          |
   |  integer    |  c_int8_t               |  int8_t               |          |
   |  integer    |  c_int16_t              |  int16_t              |          |
   |  integer    |  c_int32_t              |  int32_t              |          |
   |  integer    |  c_int64_t              |  int64_t              |          |
   |  integer    |  c_int_least8_t         |  int_least8_t         |          |
   |  integer    |  c_int_least16_t        |  int_least16_t        |          |
   |  integer    |  c_int_least32_t        |  int_least32_t        |          |
   |  integer    |  c_int_least64_t        |  int_least64_t        |          |
   |  integer    |  c_int_fast8_t          |  int_fast8_t          |          |
   |  integer    |  c_int_fast16_t         |  int_fast16_t         |          |
   |  integer    |  c_int_fast32_t         |  int_fast32_t         |          |
   |  integer    |  c_int_fast64_t         |  int_fast64_t         |          |
   |  integer    |  c_intmax_t             |  intmax_t             |          |
   |  integer    |  c_intptr_t             |  intptr_t             |          |
   |  integer    |  c_ptrdiff_t            |  intptr_t             | TS 29113 |
   |  real       |  c_float                |  float                |          |
   |  real       |  c_double               |  double               |          |
   |  real       |  c_long_double          |  long double          |          |
   |  complex    |  c_float_complex        |  float _Complex       |          |
   |  complex    |  c_double_complex       |  double _Complex      |          |
   |  complex    |  c_long_double_complex  |  long double _Complex |          |
   |  logical    |  c_bool                 |  _Bool                |          |
   |  character  |  c_char                 |  char                 |          |
   #-------------#-------------------------#-----------------------#----------#

-1 if the companion processor defines the corresponding C type and there is no interoperating Fortran processor kind or -2 if the C processor does not define the corresponding C type.

Additionally, the following parameters of type ‘character(kind=c_char)‘ are defined.

   #---------------------#-----------------#--------#
   | Name                | C definition    | Value  |
   |---------------------|-----------------|--------|
   | ‘c_null_char‘       | null character  | ‘’\0’‘ |
   | ‘c_alert‘           | alert           | ‘’\a’‘ |
   | ‘c_backspace‘       | backspace       | ‘’\b’‘ |
   | ‘c_form_feed‘       | form feed       | ‘’\f’‘ |
   | ‘c_new_line‘        | new line        | ‘’\n’‘ |
   | ‘c_carriage_return‘ | carriage return | ‘’\r’‘ |
   | ‘c_horizontal_tab‘  | horizontal tab  | ‘’\t’‘ |
   | ‘c_vertical_tab‘    | vertical tab    | ‘’\v’‘ |
   #---------------------#-----------------#--------#

Moreover, the following two named constants are defined:

   #---------------#----------#
   | Name          | Type     |
   |---------------|----------|
   | c_null_ptr    | c_ptr    |
   | c_null_funptr | c_funptr |
   #---------------#----------#

Both are equivalent to the value ‘NULL‘ in C.

INTEROPERABILITY WITH C

GENERAL

15.1

  Fortran provides a means of referencing procedures that are defined by
  means of the C programming language or procedures that can be described
  by C prototypes as defined in 6.7.5.3 of the C International Standard,
  even if they are 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 the C International Standard.

The ISO C BINDING module provides access to named constants that represent kind type parameters of data representations compatible with C types. Fortran also provides facilities for defining derived types (4.5) and enumerations (4.6) that correspond to C types.

To avoid potential name conflicts with program entities, it is recommended that a program use the ONLY option in any USE statement that references the ISO C BINDING intrinsic module.

THE ISO_C_BINDING INTRINSIC MODULE

    NAMED CONSTANTS AND DERIVED TYPES IN THE MODULE

15.2.2

     The values of C_FLOAT, C_DOUBLE, and C_LONG_DOUBLE shall each be a
     valid value for a real kind type parameter on the processor or shall
     be -1 if the companion processor’s type does not have a precision
     equal 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 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.

The value of C_BOOL shall be a valid value for a logical kind parameter on the processor or shall be -1.

The value of C_CHAR shall be a valid value for a character kind type parameter on the processor or shall be -1. The value of C_CHAR is known as the C character kind.

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. The value of C_NULL_FUNPTR shall be that of a null pointer to a function in C.

NOTE 15.2 The value of NEW_LINE(C_NEW_LINE) is C_NEW_LINE (13.7.120).

PROCEDURES IN THE MODULE

15.2.3

    In the detailed descriptions below, procedure names are generic and
    not specific.

C_ASSOCIATED (C_PTR_1 [, C_PTR_2]) 15.2.3.2

   Description. True if and only if C_PTR_1 is associated with an entity and C_PTR_2 is absent, or if C_PTR_1
   and C_PTR_2 are associated with the same entity.

Class. Inquiry function.

Arguments.

C_PTR_1 shall be a scalar of type C_PTR or C_FUNPTR. C_PTR_2 (optional) shall be a scalar of the same type as C_PTR_1.

Result Characteristics. Default logical scalar.

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 6.3.2.3 and 6.5.9 of the C International Standard, and false otherwise.
NOTE 15.3

   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)

C_F_POINTER (CPTR, FPTR [, SHAPE]) 15.2.3.3

    Description. Associate a data pointer with the target of a C pointer and specify its shape.

Class. Subroutine.

Arguments.
CPTR shall be a scalar of type C_PTR. It is an INTENT(IN) argument. Its value shall be the C address of an interoperable data entity, or the result of a reference to C_LOC with a noninteroperable argument. 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, and shall not be a coindexed object. It is an INTENT (OUT) argument. If the value of CPTR is the C address of an interoperable data entity, FPTR shall be a data pointer with type and type parameters interoperable with the type of the entity. In this case, FPTR becomes pointer associated with the target of CPTR. If FPTR is an array, its shape is specified by SHAPE and each lower bound is 1. If the value of CPTR is the result of a reference to C LOC with a noninteroperable argument X, FPTR shall be a nonpolymorphic scalar pointer with the same type and type parameters as X. In this case, X or its target if it is a pointer shall not have been deallocated or have become undefined due to execution of a RETURN or END statement since the reference. FPTR becomes pointer associated with X or its target.
SHAPE (optional) shall be of type integer and rank one. 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.

C_F_PROCPOINTER (CPTR, FPTR) 15.2.3.4

  Description. Associate a procedure pointer with the target of a C function pointer.

Class. Subroutine.

Arguments.

CPTR shall be a scalar of type C_FUNPTR. It is an INTENT (IN) argument. Its value shall be the C address of a procedure that is interoperable. FPTR shall be a procedure pointer, and shall not be a component of a coindexed object. It is an INTENT (OUT) argument. The interface for FPTR shall be interoperable with the prototype that describes the target of CPTR. FPTR becomes pointer associated with the target of CPTR.

NOTE 15.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 the C International Standard.

C_FUNLOC (X) 15.2.3.5

  Description. C address of the argument.

Class. Inquiry function.

Argument. X shall either be a procedure that is interoperable, or a procedure pointer associated with an interoperable procedure. It shall not be a coindexed object.

Result Characteristics. Scalar of type C FUNPTR.

Result Value. The result value is described using the result name FPTR. The result is determined as if C - FUNPTR were a derived type containing an implicit-interface procedure pointer component PX and the pointer assignment FPTR%PX => X were executed.

The result is a value that can be used as an actual FPTR argument in a call to C F PROCPOINTER where FPTR has attributes that would allow the pointer assignment FPTR => X. Such a call to C F PROCPOINTER shall have the effect of the pointer assignment FPTR => X.

15.2.3.6 C LOC (X)

Description. C address of the argument.

Class. Inquiry function.

Argument. X shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a contiguous variable with interoperable type and type parameters, or be a scalar, nonpolymorphic variable 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 have nonzero size.

Result Characteristics. Scalar of type C PTR.

Result Value. The result value is described using the result name CPTR.

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.

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 first element of X were executed.

If X is a data entity that is interoperable or has interoperable type and type parameters, the result is the value that the C processor returns as the result of applying the unary "&" operator (as defined in the C International Standard, 6.5.3.2) to the target of CPTR%PX.

The result is a value that can be used as an actual CPTR argument in a call to C F POINTER where FPTR has attributes that would allow the pointer assignment FPTR => X. Such a call to C F POINTER shall have the effect of the pointer assignment FPTR => X.

NOTE 15.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, portable C functions should treat it as a void (generic) C pointer that cannot be dereferenced (6.5.3.2 in the C International Standard).

15.2.3.7
  C SIZEOF (X)
Description. Size of X in bytes.
Class. Inquiry function.
Argument. X shall be an interoperable data entity that is not an assumed-size array.
Result Characteristics. Scalar integer of kind C SIZE T (15.3.2).
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 (C International Standard, subclause 6.5.3.4) to an object of a type that interoperates with the type and type parameters of X.
If X is an array, the result value is the value that the companion processor returns as the result of applying the sizeof operator to an object of a type that interoperates with the type and type parameters of X, multiplied by the number of elements in X.
15.3 Interoperability between Fortran and C entities
15.3.1 General Subclause 15.3 defines the conditions under which a Fortran entity is interoperable. If a Fortran entity is inter- operable, an equivalent entity may be defined by means of C and the Fortran entity interoperates with the C entity. There does not have to be such an interoperating C entity.
       NOTE 15.6
       A Fortran entity can be interoperable with more than one C entity.

15.3.2 Interoperability of intrinsic types Table 15.2 shows the interoperability between Fortran intrinsic types and C types. A Fortran intrinsic type with particular type parameter values is interoperable with a C type if the type and kind type parameter value are listed in the table on the same row as that C type; if the type is character, interoperability also requires that the length type parameter be omitted or be specified by an initialization expression whose 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.
The second column of the table refers to the named constants made accessible by the ISO C BINDING intrinsic module. If the value of any of these named constants is negative, there is no combination of Fortran type and type parameters interoperable with the C type shown in that row.
A combination of intrinsic type and type parameters is interoperable if it is interoperable with a C type. The C types mentioned in table 15.2 are defined in subclauses 6.2.5, 7.17, and 7.18.1 of the C International Standard.
                         Table 15.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
C_SIGNED_CHAR
  signed char unsigned char
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 t
C_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_INTPTR_T
  intptr t
C_FLOAT
  float
REAL C_DOUBLE double
C_LONG_DOUBLE
  long double
C_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 15.7 For example, the type integer with a kind type parameter of C_SHORT is interoperable with the C type short or any C type derived (via typedef) from short.
 

NOTE 15.8 The C International Standard 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.

15.3.3 Interoperability with C pointer types C PTR and C FUNPTR shall be derived types with only private components. No direct component of either of these types is allocatable or a pointer. C PTR is interoperable with any C object pointer type. C FUNPTR is interoperable with any C function pointer type.
       NOTE 15.9
       This implies that a C processor is required to have the same representation method for all C object pointer
       types and the same representation method for all C function pointer types if the C processor is to be
       the target of interoperability of a Fortran processor. The C International Standard does not impose this
       requirement.

NOTE 15.10 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 may 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.

15.3.4 Interoperability of derived types and C struct types A Fortran derived type is interoperable if it has the BIND attribute.
C1501 (R425) A derived type with the BIND attribute shall not have the SEQUENCE attribute.
C1502 (R425) A derived type with the BIND attribute shall not have type parameters.
C1503 (R425) A derived type with the BIND attribute shall not have the EXTENDS attribute.
C1504 (R425) A derived type with the BIND attribute shall not have a type-bound-procedure-part.
C1505 (R425) Each component of a derived type with the BIND attribute shall be a nonpointer, nonallocatable data component with interoperable type and type parameters.
 

NOTE 15.11 The syntax rules and their constraints require that a derived type that is interoperable 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 may be the C address of such an entity.

A Fortran derived type is interoperable with a C struct type if the derived-type definition of the Fortran type specifies BIND(C) (4.5.2), the Fortran derived type and the C struct type have the same number of components, and the components of the Fortran derived type have types and type parameters that are interoperable with the types of the corresponding components of the C struct type. A component of a Fortran 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 15.12
       The names of the corresponding components of the derived type and the C struct type need not be the
       same.

There is no Fortran type that is interoperable with a C struct type that contains a bit field or that contains a flexible array member. There is no Fortran type that is interoperable with a C union type.

        NOTE 15.13
        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 15.14 The C International Standard requires the names and component names to be the same in order for the types to be compatible (C International Standard, 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 a Fortran derived type is interoperable with a C struct type because the case of identifiers is significant in C but not in Fortran.

15.3.5 Interoperability of scalar variables A scalar Fortran variable is interoperable if its type and type parameters are interoperable, it is not a coarray, and it has neither the ALLOCATABLE nor the POINTER attribute.

An interoperable scalar Fortran variable is interoperable with a scalar C entity if their types and type parameters are interoperable.
15.3.6 Interoperability of array variables An array Fortran variable is interoperable if its type and type parameters are interoperable, it is not a coarray, and it is of explicit shape or assumed size.
An explicit-shape or assumed-size array of rank r, with a shape of
  e1 ... er is interoperable with a C array if its size is nonzero and
(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 15.15 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 15.16 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 15.17 For example, a Fortran array declared as

INTEGER :: A(18, 3:7, *)

is interoperable with a C array declared as

int b[][5][18]

NOTE 15.18 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 (12.5.2.11) 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 15.22 has an example of interoperation between Fortran and C strings.

15.3.7 Interoperability of procedures and procedure interfaces A Fortran procedure is interoperable if it has the BIND attribute, that is, if its interface is specified with a proc-language-binding-spec.
A Fortran procedure interface is interoperable with a C function prototype if

        (1)    the interface has the BIND attribute,
        (2)    either
               (a)   the interface describes a function whose result variable is a scalar 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 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 the dummy argument is interoperable with an entity of the
               referenced type (C International Standard, 6.2.5, 7.17, and 7.18.1) of the formal parameter, and
        (6)    the prototype does not have variable arguments as denoted by the ellipsis (...).

NOTE 15.19 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 15.20 The C language allows specification of a C function that can take a variable number of arguments (C International Standard, 7.15). This part of ISO/IEC 1539 does not provide a mechanism for Fortran procedures to interoperate with such C functions.

A formal parameter of a C function prototype corresponds to a dummy argument of a Fortran interface if they are in the same relative positions in the C parameter list and the dummy argument list, respectively.

        NOTE 15.21
        For example, a Fortran procedure interface described by

    INTERFACE

FUNCTION FUNC(I, J, K, L, M) BIND(C) USE, INTRINSIC :: ISO_C_BINDING INTEGER(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 may 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.

NOTE 15.22 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 may 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 (12.5.2.11). 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.

15.4 Interoperation with C global variables
15.4.1 General A C variable whose name has external linkage may interoperate with a common block or with a variable declared in the scope of a module. The common block or variable shall be specified to have the BIND attribute.
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 by more than one processor.

If a common block is specified in a BIND statement, it shall be specified in a BIND statement with the same bind- ing label in each scoping unit in which it is declared. A C variable whose name has external linkage interoperates with a common block that has been 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 if the common block contains a single variable, and the variable is interoperable with the C variable.

There does not have to be an associated C entity for a Fortran entity with the BIND attribute.

       NOTE 15.23
       The 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

int c_extern; long myVariable; struct float r, s; com; float single;
15.4.2 Binding labels for common blocks and variables The binding label of a variable or common block is a default character value that specifies the name by which the variable or common block is known to the companion processor.

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 binding label. 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.

The binding label of a C variable whose name has external linkage is the same as the name of the C variable. A Fortran variable or common block with the BIND attribute that has the same binding label as a C variable whose name has external linkage is linkage associated (16.5.1.5) with that variable.
15.5 Interoperation with C functions
15.5.1 Definition and reference of interoperable procedures A procedure that is interoperable may be defined either by means other than Fortran or by means of a Fortran subprogram, but not both.
If the procedure is defined by means other than Fortran, it shall
        be describable by a C prototype that is interoperable with the interface,
        have a name that has external linkage as defined by 6.2.2 of the C International Standard, and
        have the same binding label as the interface.

A reference to such a procedure causes the function described by the C prototype to be called as specified in the C International Standard.
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 procedure defined by means of Fortran shall not invoke setjmp or longjmp (C International Standard, 7.13). If a procedure defined by means other than Fortran invokes setjmp or longjmp, that procedure shall not cause any procedure defined by means of Fortran to be invoked. A procedure defined by means of Fortran shall not be invoked as a signal handler (C International Standard, 7.14.1).
If a procedure defined by means of Fortran and a procedure defined by means other than Fortran perform input/output operations on the same external file, the results are processor dependent (9.5.4).
15.5.2 Binding labels for procedures The binding label of a procedure is a default character value that specifies the name by which a procedure with the BIND attribute is known to the companion processor.
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 letters in the binding label is significant. If a procedure has the BIND attribute with no NAME= specifier, and the 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.

C1506 A procedure defined in a submodule shall not have a binding label unless its interface is declared in the ancestor module.

The binding label for a C function whose name has external linkage is the same as the C function name.

       NOTE 15.24
       In 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

The C International Standard 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 may 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.

15.5.3 Exceptions and IEEE arithmetic procedures A procedure defined by means other than Fortran shall not use signal (C International Standard, 7.14.1) to change the handling of any exception that is being handled by the Fortran processor.

A procedure defined by means other than Fortran shall not alter the floating-point status (14.7) other than by setting an exception flag to signaling.

The values of the floating-point exception flags on entry to a procedure defined by means other than Fortran are processor-dependent.


iso_c_binding (7) March 18, 2019
Generated by manServer 1.08 from 41803274-813e-441a-b69a-b34744f45d6d using man macros.