J3/00-265R2

Date:    2000/09/20
To:      J3
From:    /interop
Subject: C pointer comparison

Ref:     ISO/IEC JTC1/SC22/WG5 N1402a
Ref:     Issue 252 on page 386

Edits and references are to J3/00-007r2.

1. Analysis

Fortran 95 has the functionality of finding out whether a pointer is
associated with its target or not. This is implemented with the
intrinsic function ASSOCIATED.

This functionality can be implemented for objects of type C_PTR in two
ways:

1. Specify an intrinsic procedure, which compares two objects of type
C_PTR, and returns the value .TRUE. if the two objects are the same,
and .FALSE., if the two objects are different. Specify that the
C_NULL_PTR can be used as argument in the intrinsic procedure.

2. Allow comparison with .EQ. of objects of type C_PTR, and define a
constant of type C_PTR, which corresponds to the (null) pointer (for
instance with name C_NULL_PTR).

The following straw votes were taken at the WG5 Oulu meeting.

Straw Vote #1: What should be the requirement of the intrinsic function:

Test against C_NULL_PTR only                     1
Test against pointer equality                   13
Undecided                                        1

Straw Vote #2: Which language specification should J3 use:

Specify an intrinsic procedure                  14
Extend the .EQ. operator                         0
Undecided                                        1

2. Syntax

Thus WG5 has a preference for an intrinsic procedure which tests
against procedure equality. The name of the function has not yet been
determined. The example below uses C_ASSOCIATED as name.

Note: The name has been changed to C_ASSOCIATED and the semantics have been
changed to agree with the semantics of ASSOCIATED. There are now one and
two parameter forms.

3. Syntax Example - (removed - see example in edits)

4. Edits to 00-007r2

[385:16] add C_ASSOCIATED to list of defined entities.

[386:26-44] Delete J3 note

[389:31] Change the section title to:

Interoperability inquiry functions

[389:33+] Add the following text at end of sentence:

The C_ASSOCIATED function is provided so that Fortran applications
can compare "C addresses".

[390:30+] Add the following text:

"C_ASSOCIATED(C_PTR_1[, C_PTR_2])

Description. Indicates the association status of C_PTR_1 or indicates if
C_PTR_1 and C_PTR_2 are associated with the same object.

Class.       Inquiry Function.

Arguments. C_PTR_1 shall be of type C_PTR.
           C_PTR_2(optional) shall be of type C_PTR.

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.  Otherwise, the result is true if C_PTR_1 compares
          equal to C_PTR_2, in the sense of section 6.3.2.3 of the C
          standard, and false otherwise.

"The following example illustrates the use of C_LOC and C_ASSOCIATED.

USE ISO_C_BINDING
INTERFACE
  SUBROUTINE FOO(GAMMA), BIND(C)
        USE ISO_C_BINDING
        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)
..."

[390:18-30] Delete Note 16.8