From patchwork Mon Nov 1 23:57:01 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 46937 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 4719F3857C48 for ; Tue, 2 Nov 2021 00:00:35 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa2.mentor.iphmx.com (esa2.mentor.iphmx.com [68.232.141.98]) by sourceware.org (Postfix) with ESMTPS id 11DC13858033; Mon, 1 Nov 2021 23:57:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 11DC13858033 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com IronPort-SDR: FfHNIT/oUhWPjJ5gEnHsgpAbSk5wMCYPNn0SWQz6Smwiu2Nzm1kYCDkxQPwoXFAhdUybsO1qAB JPZviSodpayZTCw6IHKtdDjCRLsaPuMNXaRh3QkM+6q4Eu/YsPbj6lrPigAI4Vhvui74AuexmZ RndmKM22Jq+kmFeWBHZzsBfbhCGoH+H+SlsPGoLMs7o5wDyI37lEyw5RimXxs+TIzyTRgeyeZ3 04j7rRi/kW/4XyoLs+jGhyQrocp40fkj1H28kzQfCRsDYQXmVrs+cpnlHGomlPOPpxcn9g5DAQ gIy9DyaL8i7b1wiJqtNDWOhv X-IronPort-AV: E=Sophos;i="5.87,201,1631606400"; d="scan'208";a="67917983" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa2.mentor.iphmx.com with ESMTP; 01 Nov 2021 15:57:32 -0800 IronPort-SDR: Ayb30TsYj68Y8sflX5cSEgQybUUlia5+LCC+Y5EhF2yQKkm1Q8Ht0GuamNCh1tHNCeXoCJWRuy EX7DxX2SmgtgqvLjW55FyafPqc5wESKYEUi7cL0ScMv3NKyp8/EM5MppWz0+KECR54j40MWeZF P/soluOCC/7KlqzUIWteND1CSjVa2whoa1NGrNVSseaP5AHtu96KrNtQmAPajVGBHHUoJyvfdp +XZZFLOz1nZRumoaN7Mapxfw2kemAv1jbPehaTNPwi7M2hC1bv2XzqfLsFp9RCfsJReNMMMDhX UB0= From: Sandra Loosemore To: , Subject: [PATCH 3/5] Fortran manual: Update section on Interoperability with C Date: Mon, 1 Nov 2021 17:57:01 -0600 Message-ID: <20211101235703.112341-4-sandra@codesourcery.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20211101235703.112341-1-sandra@codesourcery.com> References: <20211101235703.112341-1-sandra@codesourcery.com> MIME-Version: 1.0 X-ClientProxiedBy: SVR-ORW-MBX-09.mgc.mentorg.com (147.34.90.209) To svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) X-Spam-Status: No, score=-9.9 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" 2021-11-01 Sandra Loosemore gcc/fortran/ * gfortran.texi (Interoperability with C): Copy-editing. Add more index entries. (Intrinsic Types): Likewise. (Derived Types and struct): Likewise. (Interoperable Global Variables): Likewise. (Interoperable Subroutines and Functions): Likewise. (Working with C Pointers): Likewise. (Further Interoperability of Fortran with C): Likewise. Rewrite to reflect that this is now fully supported by gfortran. --- gcc/fortran/gfortran.texi | 170 +++++++++++++++++++--------------------------- 1 file changed, 69 insertions(+), 101 deletions(-) diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi index ba5db57..e231e74 100644 --- a/gcc/fortran/gfortran.texi +++ b/gcc/fortran/gfortran.texi @@ -2726,20 +2726,22 @@ and their use is highly recommended. @node Interoperability with C @section Interoperability with C +@cindex interoperability with C +@cindex C interoperability @menu * Intrinsic Types:: * Derived Types and struct:: * Interoperable Global Variables:: * Interoperable Subroutines and Functions:: -* Working with Pointers:: +* Working with C Pointers:: * Further Interoperability of Fortran with C:: @end menu Since Fortran 2003 (ISO/IEC 1539-1:2004(E)) there is a standardized way to generate procedure and derived-type -declarations and global variables which are interoperable with C -(ISO/IEC 9899:1999). The @code{bind(C)} attribute has been added +declarations and global variables that are interoperable with C +(ISO/IEC 9899:1999). The @code{BIND(C)} attribute has been added to inform the compiler that a symbol shall be interoperable with C; also, some constraints are added. Note, however, that not all C features have a Fortran equivalent or vice versa. For instance, @@ -2755,12 +2757,16 @@ assuming @math{i < n}) in memory is @code{A(i+1,j)} (C: @code{A[j-1][i]}). @node Intrinsic Types @subsection Intrinsic Types +@cindex C intrinsic type interoperability +@cindex intrinsic type interoperability with C +@cindex interoperability, intrinsic type In order to ensure that exactly the same variable type and kind is used -in C and Fortran, the named constants shall be used which are defined in the -@code{ISO_C_BINDING} intrinsic module. That module contains named constants -for kind parameters and character named constants for the escape sequences -in C. For a list of the constants, see @ref{ISO_C_BINDING}. +in C and Fortran, you should use the named constants for kind parameters +that are defined in the @code{ISO_C_BINDING} intrinsic module. +That module contains named constants of character type representing +the escaped special characters in C, such as newline. +For a list of the constants, see @ref{ISO_C_BINDING}. For logical types, please note that the Fortran standard only guarantees interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind @@ -2770,12 +2776,13 @@ the value 0. Using any other integer value with GNU Fortran's @code{LOGICAL} values than 0 and 1 to GCC's @code{_Bool} is also undefined, unless the integer is explicitly or implicitly casted to @code{_Bool}.) - - @node Derived Types and struct @subsection Derived Types and struct +@cindex C derived type and struct interoperability +@cindex derived type interoperability with C +@cindex interoperability, derived type and struct -For compatibility of derived types with @code{struct}, one needs to use +For compatibility of derived types with @code{struct}, use the @code{BIND(C)} attribute in the type declaration. For instance, the following type declaration @@ -2790,6 +2797,7 @@ following type declaration END TYPE @end smallexample +@noindent matches the following @code{struct} declaration in C @smallexample @@ -2814,6 +2822,9 @@ with bit field or variable-length array members are interoperable. @node Interoperable Global Variables @subsection Interoperable Global Variables +@cindex C variable interoperability +@cindex variable interoperability with C +@cindex interoperability, variable Variables can be made accessible from C using the C binding attribute, optionally together with specifying a binding name. Those variables @@ -2841,17 +2852,18 @@ a macro. Use the @code{IERRNO} intrinsic (GNU extension) instead. @node Interoperable Subroutines and Functions @subsection Interoperable Subroutines and Functions +@cindex C procedure interoperability +@cindex procedure interoperability with C +@cindex function interoperability with C +@cindex subroutine interoperability with C +@cindex interoperability, subroutine and function Subroutines and functions have to have the @code{BIND(C)} attribute to be compatible with C. The dummy argument declaration is relatively straightforward. However, one needs to be careful because C uses call-by-value by default while Fortran behaves usually similar to call-by-reference. Furthermore, strings and pointers are handled -differently. Note that in Fortran 2003 and 2008 only explicit size -and assumed-size arrays are supported but not assumed-shape or -deferred-shape (i.e. allocatable or pointer) arrays. However, those -are allowed since the Technical Specification 29113, see -@ref{Further Interoperability of Fortran with C} +differently. To pass a variable by value, use the @code{VALUE} attribute. Thus, the following C prototype @@ -2860,6 +2872,7 @@ Thus, the following C prototype @code{int func(int i, int *j)} @end smallexample +@noindent matches the Fortran declaration @smallexample @@ -2870,12 +2883,12 @@ matches the Fortran declaration @end smallexample Note that pointer arguments also frequently need the @code{VALUE} attribute, -see @ref{Working with Pointers}. +see @ref{Working with C Pointers}. Strings are handled quite differently in C and Fortran. In C a string is a @code{NUL}-terminated array of characters while in Fortran each string has a length associated with it and is thus not terminated (by e.g. -@code{NUL}). For example, if one wants to use the following C function, +@code{NUL}). For example, if you want to use the following C function, @smallexample #include @@ -2885,7 +2898,8 @@ has a length associated with it and is thus not terminated (by e.g. @} @end smallexample -to print ``Hello World'' from Fortran, one can call it using +@noindent +to print ``Hello World'' from Fortran, you can call it using @smallexample use iso_c_binding, only: C_CHAR, C_NULL_CHAR @@ -2898,7 +2912,7 @@ to print ``Hello World'' from Fortran, one can call it using call print_c(C_CHAR_"Hello World"//C_NULL_CHAR) @end smallexample -As the example shows, one needs to ensure that the +As the example shows, you need to ensure that the string is @code{NUL} terminated. Additionally, the dummy argument @var{string} of @code{print_C} is a length-one assumed-size array; using @code{character(len=*)} is not allowed. The example @@ -2914,6 +2928,7 @@ function @code{strncpy}, whose prototype is char *strncpy(char *restrict s1, const char *restrict s2, size_t n); @end smallexample +@noindent The function @code{strncpy} copies at most @var{n} characters from string @var{s2} to @var{s1} and returns @var{s1}. In the following example, we ignore the return value: @@ -2941,18 +2956,21 @@ example, we ignore the return value: The intrinsic procedures are described in @ref{Intrinsic Procedures}. -@node Working with Pointers -@subsection Working with Pointers +@node Working with C Pointers +@subsection Working with C Pointers +@cindex C pointers +@cindex pointers, C -C pointers are represented in Fortran via the special opaque derived type -@code{type(c_ptr)} (with private components). Thus one needs to +C pointers are represented in Fortran via the special opaque derived +type @code{type(c_ptr)} (with private components). C pointers are distinct +from Fortran objects with the @code{POINTER} attribute. Thus one needs to use intrinsic conversion procedures to convert from or to C pointers. +For some applications, using an assumed type (@code{TYPE(*)}) can be +an alternative to a C pointer, and you can also use library routines +to access Fortran pointers from C. See @ref{Further Interoperability +of Fortran with C}. -For some applications, using an assumed type (@code{TYPE(*)}) can be an -alternative to a C pointer; see -@ref{Further Interoperability of Fortran with C}. - -For example, +Here is an example of using C pointers in Fortran: @smallexample use iso_c_binding @@ -2970,7 +2988,7 @@ For example, When converting C to Fortran arrays, the one-dimensional @code{SHAPE} argument has to be passed. -If a pointer is a dummy-argument of an interoperable procedure, it usually +If a pointer is a dummy argument of an interoperable procedure, it usually has to be declared using the @code{VALUE} attribute. @code{void*} matches @code{TYPE(C_PTR), VALUE}, while @code{TYPE(C_PTR)} alone matches @code{void**}. @@ -3096,81 +3114,31 @@ END MODULE m @node Further Interoperability of Fortran with C @subsection Further Interoperability of Fortran with C - -The Technical Specification ISO/IEC TS 29113:2012 on further -interoperability of Fortran with C extends the interoperability support -of Fortran 2003 and Fortran 2008. Besides removing some restrictions -and constraints, it adds assumed-type (@code{TYPE(*)}) and assumed-rank -(@code{dimension}) variables and allows for interoperability of -assumed-shape, assumed-rank and deferred-shape arrays, including -allocatables and pointers. +@cindex Further Interoperability of Fortran with C +@cindex TS 29113 +@cindex array descriptor +@cindex dope vector +@cindex assumed-type +@cindex assumed-rank + +GNU Fortran implements the Technical Specification ISO/IEC TS +29113:2012, which extends the interoperability support of Fortran 2003 +and Fortran 2008 and is now part of the 2018 Fortran standard. +Besides removing some restrictions and constraints, the Technical +Specification adds assumed-type (@code{TYPE(*)}) and assumed-rank +(@code{DIMENSION(..)}) variables and allows for interoperability of +assumed-shape, assumed-rank, and deferred-shape arrays, as well as +allocatables and pointers. Objects of these types are passed to +@code{BIND(C)} functions as descriptors with a standard interface, +declared in the header file @code{}. Note: Currently, GNU Fortran does not use internally the array descriptor (dope vector) as specified in the Technical Specification, but uses -an array descriptor with different fields. Assumed type and assumed rank -formal arguments are converted in the library to the specified form. The -ISO_Fortran_binding API functions (also Fortran 2018 18.4) are implemented -in libgfortran. Alternatively, the Chasm Language Interoperability Tools, -@url{http://chasm-interop.sourceforge.net/}, provide an interface to GNU -Fortran's array descriptor. - -The Technical Specification adds the following new features, which -are supported by GNU Fortran: - -@itemize @bullet - -@item The @code{ASYNCHRONOUS} attribute has been clarified and -extended to allow its use with asynchronous communication in -user-provided libraries such as in implementations of the -Message Passing Interface specification. - -@item Many constraints have been relaxed, in particular for -the @code{C_LOC} and @code{C_F_POINTER} intrinsics. - -@item The @code{OPTIONAL} attribute is now allowed for dummy -arguments; an absent argument matches a @code{NULL} pointer. - -@item Assumed types (@code{TYPE(*)}) have been added, which may -only be used for dummy arguments. They are unlimited polymorphic -but contrary to @code{CLASS(*)} they do not contain any type -information, similar to C's @code{void *} pointers. Expressions -of any type and kind can be passed; thus, it can be used as -replacement for @code{TYPE(C_PTR)}, avoiding the use of -@code{C_LOC} in the caller. - -Note, however, that @code{TYPE(*)} only accepts scalar arguments, -unless the @code{DIMENSION} is explicitly specified. As -@code{DIMENSION(*)} only supports array (including array elements) but -no scalars, it is not a full replacement for @code{C_LOC}. On the -other hand, assumed-type assumed-rank dummy arguments -(@code{TYPE(*), DIMENSION(..)}) allow for both scalars and arrays, but -require special code on the callee side to handle the array descriptor. - -@item Assumed-rank arrays (@code{DIMENSION(..)}) as dummy argument -allow that scalars and arrays of any rank can be passed as actual -argument. As the Technical Specification does not provide for direct -means to operate with them, they have to be used either from the C side -or be converted using @code{C_LOC} and @code{C_F_POINTER} to scalars -or arrays of a specific rank. The rank can be determined using the -@code{RANK} intrinisic. -@end itemize - - -Currently unimplemented: - -@itemize @bullet - -@item GNU Fortran always uses an array descriptor, which does not -match the one of the Technical Specification. The -@code{ISO_Fortran_binding.h} header file and the C functions it -specifies are not available. - -@item Using assumed-shape, assumed-rank and deferred-shape arrays in -@code{BIND(C)} procedures is not fully supported. In particular, -C interoperable strings of other length than one are not supported -as this requires the new array descriptor. -@end itemize - +an array descriptor with different fields in functions without the +@code{BIND(C)} attribute. Arguments to functions marked @code{BIND(C)} +are converted to the specified form. If you need to access GNU Fortran's +internal array descriptor, you can use the Chasm Language Interoperability +Tools, @url{http://chasm-interop.sourceforge.net/}. @node GNU Fortran Compiler Directives @section GNU Fortran Compiler Directives