J3/03-105 To: J3 From: Aleksandar Donev, Richard Maine, and John Reid Subject: Edits for C_LOC and C_F_POINTER Date: 16 December 2002 This paper aims to address this point made by one of us (RM) in commenting on the CD: T8. The descriptions of C_LOC and C_F_POINTER are so incomprehensible as to constitute technical, rather then mere wording flaws. The descriptions are full of requirements that are assumed rather than stated, and other requirements that contradict each other by failing to state assumed conditions. For the simplest example, [384:20] says without qualification "FPTR shall be scalar", although there is lots of discussion of cases where it is an array; this requirement is clearly intended to apply only in some cases, but that isn't stated. Ref 02-276, 02-230r3. We have addressed this with a complete rewrite of the descriptions, but have tried to keep as much as possible of the earlier words and not to alter the functionality. We noticed that zero-sized arrays were not excluded. We think that this is needed since a zero-sized array does not have an address. In fact, we think that a zero-sized array should not be interoperable. We have also made each description into a subclause in the style of the intrinsic procedure definitions and put them in alphabetic order. EDITS 388:10. After 'if' add 'its size is nonzero and'. 382:17-383:10+. Delete present definition of C_LOC and NOTE 15.3. 383:11. Make into subclause 15.1.2.1 heading line. 384:1-20+. Replace present definition of C_LOC and NOTES 15.5 and 15.6 by 15.1.2.2 C_F_POINTER (CPTR, FPTR [, SHAPE]) Description. Associates a pointer with the target of a C pointer and specifies its shape. Class. Subroutine. Arguments. CPTR shall be a scalar of type C_PTR. It is an INTENT(IN) argument. Its value shall be: Case (i): The C address of a procedure that is interoperable, Case (ii): The C address of an interoperable data entity, or Case (iii): The result of a reference to C_LOC with a noninteroperable argument. The value of C_PTR shall not be the C address of a Fortran variable that does not have the TARGET attribute. FPTR shall be a pointer. It is an INTENT(OUT) argument. Case (i): If the value of CPTR is the C address of an interoperable procedure, FPTR shall be a procedure pointer whose interface is interoperable with the prototype that describes the procedure. In this case, F_PTR becomes pointer associated with the target of CPTR. Case (ii): 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 it is an array, its shape is specified by SHAPE and each lower bound is 1. Case (iii): 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 was a pointer shall not have been deallocated or have become undefined due to execution of a RETURN or END statement since the reference. F_PTR becomes pointer associated with this target. SHAPE (optional) shall be of type integer and rank one. It is an INTENT(IN) argument. If SHAPE is present, its size shall be equal to the rank of FPTR. If FPTR is an array, SHAPE shall be present. NOTE 15.4 The term "target" in the description of C_F_POINTER denotes the entity referenced by a C pointer, as described in 6.2.5 of the C standard. 15.1.2.3 C_LOC (X) Description. Returns the C address of the argument. Class. Inquiry function. Argument. X shall either (1) be (a) a procedure that is interoperable, or (b) a procedure pointer associated with an interoperable procedure, (2) have interoperable type and type parameters and be (a) a variable that has the TARGET attribute and is interoperable, (b) an allocated allocatable variable that has the TARGET attribute and is not an array of zero size, or (c) an associated scalar pointer, or (3) be a nonpolymorphic scalar, have no nonkind type parameters, and be (a) a nonallocatable, nonpointer variable that has the TARGET attribute, (b) an allocated allocatable variable that has the TARGET attribute, or (c) an associated scalar pointer. Result Characteristics. Scalar of type C_PTR. Result Value. The result value will be described using the result name CPTR. Case (i): If X is a procedure, the result is determined as if C_PTR were a derived type containing an implicit-interface pointer component PX and the pointer assignment CPTR%PX => X were executed. Case (ii): 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. Case (iii): 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 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 When 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 may 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 standard).