J3/15-119
To:        J3 Members
From:      Steve Lionel
Subject:   Editorial suggestions for C interop functions
Date: 2015 February 04
Reference: 15-007

The text and examples for some of the ISO_Fortran_binding.h functions
have ambiguities or errors. This paper suggests corrections for these.
No functional change is intended.

General

There is some inconsistency in this section regarding "parameters" and
"arguments". In C, "parameters" are what Fortran calls "dummy
arguments" and "arguments" are Fortran's "actual arguments".

CFI_establish

In paragraph 2, the description of the elem_len parameter has as the
last sentence: "Otherwise, type will be ignored." I assume this meant
to refer to elem_len and not type.

The text leaves unstated how the elem_len member of the C
descriptor is derived when the type is not struct, other or character.
Paragraph 3 says "The remaining properties of the object are given by
the other arguments.", but for objects not struct, other or character,
no arguments specify the length. Discussion on the J3 mailing list
agreed that for such objects, CFI_establish uses its own knowledge of
the length of such objects to supply a value for elem_len.

CFI_section

The example for case(ii) uses "lower" as the descriptor member
name but it should be lower_bound.

CFI_select_part

For the displacement parameter, the text says: "the sum of the
displacement and the size in bytes of the array section shall be less
than or equal to source->elem_len." I believe this should instead say
"... the size in bytes [of an element of] the array section...",
otherwise this would be rather useless. The intent is that an element
of the newly selected array is not allowed to cross an element
boundary of the source array.

EDITS to 15-007:

[462:36 15.5.5.5p2] Replace "Otherwise, type will be ignored." with
"Otherwise, the known length of objects of the type specified by
*type* will be used and *elem_len* is ignored."

[465:18-28 15.5.5.7p4] Replace ".lower" with ".lower_bound" thrice,
taking care not to change references to the variable named "lower".

[465:44 15.5.5.8p2] Replace "the size in bytes of the array section"
with "the size in bytes of an element of the array section"

[466:4 15.5.5.8p2] Replace "otherwise, the value of this parameter
is ignored" with "otherwise, *elem_len* is ignored."