Ups - I attached the wrong patch (same file name, wrong directory).
Hopefully, this one is the correct one.
Tobias
Am 29.03.2013 19:40, schrieb Tobias Burnus:
Dear all,
the attached patch attempts to document gfortran's naming and argument
passing convention when Bind(C) is not used.
While Bind(C) is the recommended way for interoperation with other
Fortran compilers and other languages, there are situations where this
is not possible; for instance, legacy code. Or in case of the MPI
standard, the MPI implementation might need this information and MPI
performance tool developers (PMPI) have to know how the different
Fortran compilers pass the arguments.
The attached patch does not (yet) state how array descriptors are
handled internally. (I was thinking of deferring this until the new
array descriptor becomes available.) I also believe there are other
omissions as well and the wording could be improved. Suggestions are
welcome.
The patch was motivated by Walter's comment** to my VALUE+OPTIONAL
patch.* It takes his comments into account and, that part, only
reflects gfortran's implementation after the VALUE+OPTIONAL patch has
been committed with his suggested change.
What do you think?
Tobias
* http://gcc.gnu.org/ml/fortran/2013-03/msg00102.html
** http://gcc.gnu.org/ml/fortran/2013-03/msg00173.html
diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi
index 4f9008d..b998c8d 100644
--- a/gcc/fortran/gfortran.texi
+++ b/gcc/fortran/gfortran.texi
@@ -2204,6 +2204,7 @@ common, but not the former.
* Interoperability with C::
* GNU Fortran Compiler Directives::
* Non-Fortran Main Program::
+* Naming and argument-passing conventions::
@end menu
This chapter is about mixed-language interoperability, but also applies
@@ -2250,6 +2251,21 @@ in C and Fortran, the named constants shall be used which are defined in the
for kind parameters and character named constants for the escape sequences
in C. 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
+logicals and C99 defines that @code{true} has the value 1 and @code{false}
+the value 0. In GCC, Boolean variables (Fortran @code{logicals} with and
+without C binding [and for all @code{kind} values], C99's @code{_Bool},
+C++'s @code{bool}, Ada's @code{Boolean}, etc.) all expect that only the
+value 0 and 1 are used; using other values might lead to wrong results.
+Therefore, using @code{logical(kind=c_int)} to interoperate with C99's
+@code{int} is discouraged and should be replaced either by
+@code{integer(kind=c_int)} on the Fortran side (which can then be
+converted to @code{logical}) -- or to use @code{_Bool} and
+@code{logical(kind=c_bool)}. Note that some other (Fortran) compilers
+use a different value for @code{.true.} (e.g. @math{-1}), even with C binding.
+
+
@node Derived Types and struct
@subsection Derived Types and struct
@@ -2975,6 +2991,115 @@ int main (int argc, char *argv[])
@end table
+@node Naming and argument-passing conventions
+@section Naming and argument-passing conventions
+
+This section gives an overview about the naming convention of procedures
+and global variables and about the argument passing conventions used by
+GNU Fortran if no C binding has been specified. If possible, mixed-language
+and mixed-compiled projects should use the better C binding for
+interoperability. See @pxref{Interoperability with C}.
+
+@menu
+* Naming conventions::
+* Argument passing conventions::
+@end menu
+
+
+@node Naming conventions
+@subsection Naming conventions
+
+According the Fortran standard, valid Fortran names consist of a letter
+between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
+@code{1} to @code{9} and underscores (@code{_}) with the restriction
+that names may only start with a letter. As vendor extension, the
+dollar sign (@code{$}) is additionally permitted with the option
+@option{-fdollar-ok}, but not as first character and only if the
+target system supports it.
+
+By default, the procedure name is the lower-cased Fortran name with an
+appended underscore (@code{_}); using @option{-fno-underscoring} no
+underscore is appended while @code{-fsecond-underscore} appends two
+underscores. Depending on the target system and the calling convention,
+the procedure might be additionally dressed; for instance, on 32bit
+Windows with @code{stdcall}, a at-sign @code{@@} followed by an integer
+number is appended. For the changing the calling convention, see
+@pxref{GNU Fortran Compiler Directives}.
+
+For common blocks, the same convention is used, i.e. by default an
+underscore is appended to the lower-cased Fortran name. Blank commons
+have the name @code{__BLNK__}.
+
+For procedures and variables declared in the specification space of a
+module, the name is formed by @code{__}, followed by the lower-cased
+module name, @code{_MOD_}, and the lower-cased Fortran name. Note that
+no underscore is appended.
+
+
+@node Argument passing conventions
+@subsection Argument passing conventions
+
+GNU Fortran passes most arguments by reference, i.e. by passing a
+pointer to the data. Note that the compiler might use a temporary
+variable into which the actual argument has been copied, if required
+semantically (copy-in/copy-out). Using the @code{VALUE} attribute
+for the argument in the procedure interface or, as vendor extension
+and not recommended, using @code{%VAL()} in the call to a procedure,
+the argument is passed by value.
+
+Subroutines do not return a value (matching C99's @code{void}) while
+functions either return a value as specified in the platform ABI or
+the result variable is passed as hidden argument to the function and
+no result is returned. A hidden result variable is used when the
+result variable is an array or of type @code{CHARACTER}.
+
+Arguments are passed according to the platform ABI. In particular,
+complex arguments may not be compatible to a struct with two real
+components for the real and imaginary part; and complex values are
+returned as result and not by reference. Note that with the
+@option{-ff2c} option, the argument passing is modified and no
+longer completely matches the platform ABI. Some other Fortran
+compilers use @code{f2c} semantic by default; this might cause
+problems with interoperablility. Additionally, GCC expects for
+Boolean variables that only the value 0 and 1 are used. Passing
+other values to GNU Fortran's @code{LOGICAL} variable might lead
+to wrong results.
+
+For arguments with @code{ALLOCATABLE} and @code{POINTER}
+attribute (including procedure pointers), a pointer to the pointer
+is passed such that the pointer address can be modified in the
+procedure.
+
+For @code{OPTIONAL} dummy arguments, an absent argument is denoted
+by a NUL pointer, except for scalar dummy arguments of type
+@code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX}
+which have a value attribute. For the latter, a hidden Boolean
+argument (@code{logical(kind=C_bool),value}) is used to indicate
+whether the argument is present.
+
+For arguments of @code{CHARACTER} type, the character length is passed
+as hidden argument. For deferred-length strings, the value is passed
+by reference, otherwise by value. The character length has the type
+@code{INTEGER(kind=4)}.
+
+Arguments which are assumed-shape, assumed-rank or deferred-rank
+arrays or, with @option{-coarray=lib}, allocatable scalar coarrays use
+an array descriptor. All other arrays are pass the address of the
+first element of the array.
+
+The arguments are passed in the following order
+@itemize @bullet
+@item Result variable, when the function result is passed by reference
+@item Character length of the function result, if it is a of type
+@code{CHARACTER}
+@item The arguments in the order in which they appear in the Fortran
+declaration
+@item The the present status for optional arguments passed internally
+by value
+@item The character lengths
+@end itemize
+
+
@c Intrinsic Procedures
@c ---------------------------------------------------------------------
