J3/99-118r1 Date: 1999/03/03 To: J3 From: interop Subject: Additional edits for "procedural interoperability" References: J3/99-007; J3/99-011; J3/98-239; J3/98-240r1 This paper is an attempt to address some of the areas of interoperability that have not been specified. In some instances, we have introduced new J3 notes in an effort to clearly identify additional deficiencies that have not yet been addressed. We have surrounded notes to the reviewer with asterisks. 2.5 [20:3+] Add "2.5.10 Companion processors A processor has one or more <>. A companion processor is a processor dependent mechanism by which global data and procedures may be referenced or defined. A companion processor may be a mechanism that references and defines such entities by a means other than Fortran (12.5.3), or it may be the Fortran processor itself. The definition of a procedure by a companion processor that is not the Fortran processor itself is referred to in this standard as the C function that defines the procedure, though the function need not be defined by means of the C programming language. [Begin note] The companion processor may be a mechanism that conforms to the requirements of the C standard, but need not. For example, a processor may allow a procedure, defined using some programming language other than Fortran or C, to be linked (12.5.3) with a Fortran procedure, if it can also be described via a C prototpye. [End note] The effect of specifying the BIND(C) attribute for a procedure, variable, common block, derived type definition, or enumeration type would have no discernable effect for a processor that was its own companion processor. The means by which a Fortran processor might select amongst several companion processors are processor dependent." 4.5.1 [39:37] After "accessible" add " or" 4.5.1 [39:37+] Add "[Begin J3 note] This constraint prohibits derived type names and type alias names from being the same. It's not clear that this prohibition is needed, because of the rules in 14.1. [End J3 note]" [78:28-29] Change "target C processor" to "companion processor" [39:3-9] Delete J3 note 85. 4.5 [39.1] Change "target C processor" to "companion processor (2.5.10)" 5.1 [62:14+] Add "[Begin J3 note] Still need to define the BIND(C) attribute for global data. [End J3 note] 5.6 [90:15] Change "SEQUENCE statement" to "SEQUENCE and BIND(C) statements" 12.2 [244:5] After "attribute" add ", the value of its binding label, if any" *** The "binding label" (defined below) is *** *** now a characteristic of a procedure. *** 12.3.1.1 [245:30+] Add "(4) The procedure has the BIND(C) attribute." 12.4.1.2 [254:36-39] Replace the last sentence with "The length of an array element in the dummy argument array may be different from the length of an array element of the associated actual argument, if the actual argument is an array, or the length of the actual argument, if the actual argument is a scalar. However, the dummy argument array shall not extend beyond the end of the actual argument element sequence (12.4.1.5)." 12.4.1.2 [256:1-15] Delete J3 note 114. Preceding two edits should address the error introduced into sequence association. However, we realized there's an additional problem. The sequence association stuff for characters that allows dummy array elements to have a different length than the actual requires the kind to be default character. Of course, for C, we want the kind to be C_CHAR. We'll fix that in a separate paper. [256:15+] Add "[Begin J3 note] We need to permit sequence association for characters to allow dummy array elements to have a different length than the actual when the kind is C_CHAR. [End J3 note]" 12.4.1.2 [256:35] After "element" add "or substring of an element" 12.5.2.1 [263:39+] Add " or BIND(C [, ]) R12?? is NAME= or BINDNAME=]" 12.5.2.1 [263:41+] Add "Constraint: If BIND is present, ELEMENTAL shall not be specified. Constraint: If BIND is present on the or of an abstract interface body (12.3.2.1) or a dummy procedure, NAME= shall not appear. Constraint: The BIND shall not be specified for an internal or module subprogram. [Begin J3 note] Should we permit the BIND to appear on a module subprogram? If we do, there would be restrictions on how a user can use a C_PTR to the thing - what happens to the pointer when no one is currently using the module? The same issue already exists for ordinary procedure pointers. Also, should they be allowed on declarations of procedures in the procedure declaration statement? Otherwise, how do you specify the binding label of such an entity? We probably do want that. [End J3 note] Constraint: The NAME= specifier shall not appear on the BIND of a subprogram. Constraint: The BINDNAME= specifier shall not appear on the of a interface body. BIND shall not be specified for a procedure that cannot interoperate with some C function (16.2.4). [Begin note] For example, if a dummy argument or function result has the POINTER attribute, has the ALLOCATABLE attribute, is an asterisk or is of a type that cannot interoperate with some C type, the function cannot interoperate with any C function. [End note]" 12.5.2.6 [268:7+] Add "12.5.2.7 Binding labels for procedures A <> is a value of type default character that specifies the name by which a procedure is known by the companion processor, if the procedure has the BIND(C) attribute. If the BIND is present with the NAME= specifier, the procedure has a binding label whose value is that of the expression specified after the NAME= specifier. The case is significant for any letters in the binding label, but leading and trailing blanks are ignored. If the BIND is present with no NAME= specifier, and the procedure is not a dummy procedure, the binding label of the procedure is the same as the name of the function, using lower case letters. If the BIND is present for a dummy procedure, the binding label is the same as that of the associated actual procedure argument. If an ENTRY statement appears in a subprogram that has the BIND on its or , the binding label of the procedure defined by the ENTRY statement is the same as the using lower case letters. The binding label for a C function with external linkage is the same as the C function name. [Begin note] In the following, the binding label of C_SUB is c_sub, and the binding label of C_FUNC is C_funC. BIND(C) SUBROUTINE C_SUB END SUBROUTINE C_SUB BIND(C, NAME='C_funC') INTEGER(C_INT) FUNCTION C_FUNC() USE ISO_C_BINDING END SUBROUTINE C_FUNC The C standard permits functions to have names that are not permitted as names by this standard, and draws distinctions between names that are not permitted by this standard. For example, a name may begin with an underscore according to the C standard, and names that differ with regard to case are distinct names according to the C standard. The specification of a binding label allows a program to refer to procedures using a Fortran name. [End note] The meaning of the expression following a BINDNAME= specifier is processor dependent. [Begin note] A processor may give a unique label, often referred to as a binder name, to each external procedure in a program. The label is derived in some way from the name of the external procedure, and need not be the same as the binding label. A processor may permit a procedure defined by means of Fortran to be known by more than one binder name, if it needs to be referenced from more than one companion processor, each of which has a different way of transforming an external name to a binder name. Use of the BINDNAME= specifier might be appropriate in such a circumstance. This is not the only possible meaning of the BINDNAME= specifier, nor is the processor required to ascribe such a meaning to the specifier. [End note]" 12.5.3 [268:8] After "Definition" add "and invocation" *** Changing the title of the section *** 12.5.3 [268:9] After "procedure" add ", that does not have the BIND(C) attribute," 12.5.3 [268:13+] Add "If a procedure has the BIND(C) attribute, it shall (1) interoperate (16.2.4) with a C function with external linkage that has the same binding label as the procedure, and is defined by means of a companion processor, or [Begin J3 note] We really shouldn't use the term "C function" to describe this. It's something that can be described via a C prototype, but need not be defined by means of C. This is a general problem. [End J3 note] (2) be defined by means of a Fortran subprogram or an ENTRY statement in a Fortran subprogram that has the BIND(C) attribute specified on its or , and has the same binding label as the procedure, but not both. The procedure is said to be <> with that C function or Fortran subprogram. If the procedure is linked with a C function, the procedure is defined by means of that C function. A reference to such a procedure causes the C function to be called as specified by the C standard. [Begin J3 note] Need to describe how actual args. get associated with C formals. [End J3 note] A procedure defined by means of a Fortran subprogram or entry statement in a subprogram that has the BIND(C) attribute specified on its or its can be invoked by a means other than Fortran. In particular, it can be invoked by a reference to a C function that has the same binding label as the subprogram or entry that defines the procedure. Any other means by which such a procedure can be invoked are processor dependent." *** Fortran 95 specified that how procedures might be defined by *** *** means other than Fortran was processor dependent. Now, there *** *** is a standard mechanism for specifying the Fortran procedure. *** 14.1.1 [335:18] Change "and external procedures" to "external procedures, and binding labels" 14.1.1 [335:20+] Add "[Begin J3 note] The concept of binding labels needs more work. A binding label doesn't necessarily have a name, so it doesn't fit in with the assumptions made by this section. Generally, we want the user to avoid a situation in which the binder names of a Fortran thing and a C (or system) thing are the same and clash. But it's hard to describe that. [End J3 note]" 16 [377:2-4] Replace J3 note 91 with "Fortran provides a means of specifying an explicit interface to procedures that are defined by means of the C programming language, or for which C prototypes can be written, even if the procedure is not actually defined by means of C. The ISO_C_BINDING module provides access to named constants that represent kind type parameters. These kind type parameters facilitate the creation of such Fortran interfaces. In addition, these facilities provide a means of specifying that a procedure defined by a Fortran subprogram can be called from a function written by means of C. Fortran also provides facilities for creating derived types (4.5), enumerated types (4.7) and type aliases (4.6) that correspond to C derived types, and for declaring global variables that are linked with C variables that have external linkage. [Begin J3 note] Need refs. to C9x for "external linkage" and "prototype". Need a ref for linked (as it relates to variables). [End J3 note]" *** Introduction for section 16. *** 16 [377:5-11] *** Still need the glossary entries. We won't be getting to it yet. *** 16 [377:12-24] Delete J3 note 93. How being interoperable with a C function gets used is specified by the edits to 12.5.3. 16.1 [377:32], [378:9], [378:11], [378:12] Change "C_NULLCHAR" to "C_NULL_CHAR" throughout this section. 16.1 [377:34-38] Delete J3 note 95. Took Richard's suggestion to change C_NULLCHAR to C_NULL_CHAR. 16.1 [378:4] Change "C_COMPLES" to "C_COMPLEX" 16.1 [378:11-12] Replace last sentence with "If C_CHAR has a non-negative value, the value of C_NULL_CHAR shall be the same as the null value of the C character type; otherwise, the value of C_NULL_CHAR shall be the first character in the collating sequence for characters of default kind." 16.1 [378:13-26] Delete J3 note 96. This was handled by the preceding edit and the edit to 2.5.10. 16.2 [379:1+] Add "Fortran entities are said to <> with C entities when some correspondence exists between the entities. That correspondence is defined by this section. A Fortran entity with the POINTER attribute or the ALLOCATABLE attribute cannot interoperate with any C entity. The following sections describe situations in which a Fortran entity can interoperate with a C entity. If an entity is not expressly described as interoperating with a C entity, it cannot interoperate with any C entity. 16.2.1 Fortran scalar intrinsic entities and C entities" Renumber subsequent sections 16.2.2 through 16.2.5. 16.2 [379:4] After "parameter" add ", that is not expressly prohibited from interoperating with any C entity," 16.2 [379:5] Change "compatable" to "compatible with" 16.2 [379:8+] Add "[Begin note] The C programming language defines null terminated strings that are actually arrays of the C type char that have a C null character in them to indicate the last valid element value. A C string can interoperate with a Fortran array of type character, with a kind type parameter equal to C_CHAR. Fortran's rules of sequence association (12.4.1.5) permit a character scalar actual argument to be associated with a dummy argument array. This makes it a simple matter to argument associate a Fortran character string with a C string. [End note]" 16.2 [379:31-33] Change 3 occurrences of "complex" in the last column to "_Complex" 16.2 [380:2] Change "specified" to "specifies" 16.2 [380:11] After "C_PTR" add ", that is not expressly prohibited from interoperating with any C entity (16.2)," 16.2.1 [380:15-17] Delete ", so this might. . . determined." *** We think the last part of note 16.3 was intended to be a J3 note. *** *** At this point, we haven't heard about any such processors that *** *** might be of interest. *** 16.2.1 [380:18-25] Delete J3 note 98. This was dealt with in the preceding edit. 16.2 [380:29] After "derived type" add ", that is not expressly prohibited from interoperating with any C entity," 16.2.2 [380:32] After "corresponding components of the struct type" add "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 types. [Begin note] The names of the corresponding components of the derived type and the C struct type need not be the same. [End note]" 16.2.2 [380:33-36] Delete J3 note 99. The preceding edit should clarify the issue. *** Does it for you, Richard? *** 16.2.2 [380:38] Change "array of an incomplete type" to "that contains a flexible array member" 16.2.2 [380:39+] Add "[Begin J3 note] Need a reference/glossary entry for flexible array member. [End J3 note]" 16.2.2 [380:40-45] Delete J3 note 100. The edit to [380:38] should fix it. 16.2.2 [381:1-2] Change first sentence of note to the following: "For example, a scalar objct of the type myctype, declared below, interoperates with a scalar Fortran object of the type MYFTYPE, declared below." 16.2.2 [381:6] Change "floar" to "float" 16.2.2 [381:7+] Add the following: "TYPE MYFTYPE BIND(C) 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 the types are interoperable." 16.2.2 [381:8-17] Delete J3 note 101. The preceding edit should fix it. 16.2.2 [381:18-33] *** We haven't looked into this yet. We'll do it in another paper. *** 16.2.3 [382:2-20] Delete J3 note 103. This doesn't restrict what the actual arguments can look like; only what the dummy arguments can look like. 16.2.3 [382:21-30] Re: issue 104. Yes, this is redundant. However, we thought someone might think that the element type of, say, "int a[10][20]" was "int" rather than "int [20]". We'll make it a note (at 34+). 16.2.3 [382:24-30] Delete J3 note 104. 16.2.3 [382:34+] Add "[Begin note] The element type of a multi-dimensional C array is an array type, so a Fortran array of rank one cannot interoperate with a multi- dimensional C array." [End note] 16.2.3 [382:21-23,31-39] Replace this text with "An explicit-shape or assumed-size array of rank , with a shape of [ . . . ], interoperates with a C array, if 1 r (1) the array is assumed-size, and the C array does not specify a size or specifies a size of *, or (2) the array is explicit-shape and the extent of the last dimension () is the same as the size of the C array, r and (1) is equal to one, and an element of the array interoperates with an element of the C array, or (2) is greater than one, and an explicit-shape array with a shape of [ . . . ], with the same type and type parameters 1 r-1 as the original array would interoperate with a C array of the element type of the C array." 16.2.3 [382:40-43] Delete J3 note 105. Hopefully, the preceding edit clarifies things. 16.2.4 [383:7] Replace this line with "The <> of a C pointer type is the C type of the object that the C pointer type points to. [Begin note] For example, the reference type of the pointer type <> is <>. [End note] 16.2.4 [383:8-13] Delete J3 note 106. This is addressed by the preceding edit. 16.2.4 [383:13+] Add "A formal parameter of a C function corresponds to a dummy argument of a Fortran procedure if the formal parameter and dummy arugment are in the same relative positions in the C parameter list and the dummy argument list, respectively." 16.2.4 [383:14] Change "fortran" to "Fortran" 16.2.4 [383:18] Before "void" add "compatible with the C type" 16.2.4 [383:19-22] *** We'll look into this in a subsequent paper. *** 16.2.4 [383:24] After "function" add ", all the dummy arguments are dummy data objects, none of which have either the POINTER or ALLOCATABLE attribute." 16.2.4 [383:27-29] Delete J3 note 108. This is clarified by the edit to [383:13+]. 16.2.4 [383:33-39] *** We'll look at this note more carefully for a subsequent paper. *** 16.2.4 [384:16+] Add at end of J3 note "Addendum from meeting 148 (though no correction, yet) This is attempting to prevent things that have dummy arguments with the pointer or allocatable attribute, array results, etc. However, if the BIND(C) attribute is specified on a subprogram, any procedure defined by that subprogram must have an explicit interface. So we want to prohibit the former, but not the latter. We'll work on it in a subsequent paper." 16.2.4 [384:19+] Add the line "USE ISO_C_BINDING" 16.2.4 [384:27-33] Delete J3 note 111. This is fixed by the preceding edit. 16.2.4 [384:34-42] *** Subgroup still needs to deal with this issue in a subsequent paper. *** C.9.2 [430:30+] Add "[Begin J3 note] This section needs revision in light of changes made to 12.5.3. [End J3 note]"