libgomp.texi (omp_interop_*): Add note about 5.2-to-6.0 incompatibility

GCC uses the 6.0 types - which are unfortunately not quite compatible with
code expecting 5.1/5.2 data types.  Therefore, this commit adds a note to
hopefully reduce surprises. Namely:

For C/C++: while OpenMP 5.1 and 5.2 used 'int *ret_code', OpenMP 6.0 uses
'omp_interop_rc_t *ret_code' in omp_interop_{int,ptr,str} and 'int' instead
of 'omp_interop_rc_t ret_code' in omp_get_interop_rc_desc.

Neither C nor C++ like passing the wrong pointer type, albeit for C, GCC < 14
and clang only warn (gcc >= r14-6037-g9715c545d33b3a has an error) and
using -fpermissive turns it into a warning and -Wno-incompatible-pointer-types
silences it for C.

C++ also dislikes passing an int to an enum, albeit -fpermissive turns the
error into a warning with g++ (but not clang++). And, here, using an enum
on the caller side works with both int and enum on the callee side.

libgomp/ChangeLog:

	* libgomp.texi (omp_interop_{int,ptr,str,rc_desc}): Add note about
	the 'ret_code' type change in OpenMP 6.

Co-authored-by: Sandra Loosemore <sloosemore@baylibre.com>

diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 8e487bcd168c249923a6b048b827282726f5412e..7116fcda13fec0ae79f62d78018954ebdbee58b3 100644 (file)
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -3130,6 +3130,11 @@ and Fortran or used with @code{NULL} as argument in C and C++.  If successful,
 In GCC, the effect of running this routine in a @code{target} region that is not
 the initial device is unspecified.
 
+GCC implements the OpenMP 6.0 version of this function for C and C++, which is not
+compatible with its type signature in previous versions of the OpenMP specification.
+In older versions, the type @code{int*} was used for the @var{ret_code} argument
+in place of a pointer to the enumerated type @code{omp_interop_rc_t}.
+
 @c Implementation remark: In GCC, the Fortran interface differs from the one shown
 @c below: the function has C binding and @var{interop} and @var{property_id} are
 @c passed by value, which permits use of the same ABI as the C function.  This does
@@ -3176,6 +3181,11 @@ and Fortran or used with @code{NULL} as argument in C and C++.  If successful,
 In GCC, the effect of running this routine in a @code{target} region that is not
 the initial device is unspecified.
 
+GCC implements the OpenMP 6.0 version of this function for C and C++, which is not
+compatible with its type signature in previous versions of the OpenMP specification.
+In older versions, the type @code{int*} was used for the @var{ret_code} argument
+in place of a pointer to the enumerated type @code{omp_interop_rc_t}.
+
 @c Implementation remark: In GCC, the Fortran interface differs from the one shown
 @c below: the function has C binding and @var{interop} and @var{property_id} are
 @c passed by value, which permits use of the same ABI as the C function.  This does
@@ -3222,6 +3232,11 @@ and Fortran or used with @code{NULL} as argument in C and C++.  If successful,
 In GCC, the effect of running this routine in a @code{target} region that is not
 the initial device is unspecified.
 
+GCC implements the OpenMP 6.0 version of this function for C and C++, which is not
+compatible with its type signature in previous versions of the OpenMP specification.
+In older versions, the type @code{int*} was used for the @var{ret_code} argument
+in place of a pointer to the enumerated type @code{omp_interop_rc_t}.
+
 @c Implementation remark: In GCC, the Fortran interface differs from the one shown
 @c below: @var{interop} and @var{property_id} are passed by value.  This does not
 @c affect the usage of the function when GCC's @code{omp_lib} module or
@@ -3348,6 +3363,11 @@ the @var{ret_code} in human-readable form.
 The behavior is unspecified if value of @var{ret_code} was not set by an
 interoperability routine invoked for @var{interop}.
 
+GCC implements the OpenMP 6.0 version of this function for C and C++, which is not
+compatible with its type signature in previous versions of the OpenMP specification.
+In older versions, the type @code{int} was used for the @var{ret_code} argument
+in place of the enumerated type @code{omp_interop_rc_t}.
+
 @item @emph{C/C++}:
 @multitable @columnfractions .20 .80
 @item @emph{Prototype}: @tab @code{const char *omp_get_interop_rc_desc(const omp_interop_t interop,