The ATTRIBUTES properties (also known as options) C, STDCALL (Windows* OS only), REFERENCE, VALUE, and VARYING affect the calling convention of routines. You can specify:
The C, STDCALL, REFERENCE, and VARYING properties for an entire routine.
The VALUE and REFERENCE properties for individual arguments.
By default, Fortran passes all data by reference (except the hidden length argument of strings, which is passed by value). If the C (or, for Windows OS, STDCALL) option is used, the default changes to passing almost all data except arrays by value. However, in addition to the calling-convention options C and STDCALL, you can specify argument options, VALUE and REFERENCE, to pass arguments by value or by reference, regardless of the calling convention option. Arrays can only be passed by reference.
Different Fortran calling conventions can be specified by declaring the Fortran procedure to have certain attributes.
It is advisable to use the DECORATE option in combination with the ALIAS option to ensure appropriate name decoration regardless of operating system or architecture. The DECORATE option indicates that the external name specified in ALIAS should have the correct prefix and postfix decorations for the calling mechanism in effect.
Naming conventions are as follows:
leading (prefix) underscore for Windows operating systems based on IA-32 architecture; no underscores for Windows operating systems based on Intel® 64 architecture and Windows systems based on IA-64 architecture.
trailing (postfix) underscore for all Linux operating systems
leading and trailing underscores for all Mac OS* X operating systems
For example:
INTERFACE SUBROUTINE MY_SUB (I) !DEC$ ATTRIBUTES C, DECORATE, ALIAS:'My_Sub' :: MY_SUB INTEGER I END SUBROUTINE MY_SUB END INTERFACE
This code declares a subroutine named MY_SUB with the C property. The external name will be appropriately decorated for the operating system and platform.
The following table summarizes the effect of the most common Fortran calling-convention directives.
Argument |
Default |
C |
C, REFERENCE |
STDCALL (Windows OS IA-32 architecture) |
STDCALL, REFERENCE (Windows OS IA-32 architecture) |
---|---|---|---|---|---|
Scalar |
Reference |
Value |
Reference |
Value |
Reference |
Scalar [value] |
Value |
Value |
Value |
Value |
Value |
Scalar [reference] |
Reference |
Reference |
Reference |
Reference |
Reference |
String |
Reference, either Len:End or Len:Mixed |
String(1:1) |
Reference, either Len:End or Len:Mixed |
String(1:1) |
String(1:1) |
String [value] |
Error |
String(1:1) |
String(1:1) |
String(1:1) |
String(1:1) |
String [reference] |
Reference, either No Len or Len:Mixed |
Reference, No Len |
Reference, No Len |
Reference, No Len |
Reference, No Len |
Array |
Reference |
Reference |
Reference |
Reference |
Reference |
Array [value] |
Error |
Error |
Error |
Error |
Error |
Array [reference] |
Reference |
Reference |
Reference |
Reference |
Reference |
Derived Type |
Reference |
Value, size dependent |
Reference |
Value, size dependent |
Reference |
Derived Type [value] |
Value, size dependent |
Value, size dependent |
Value, size dependent |
Value, size dependent |
Value, size dependent |
Derived Type [reference] |
Reference |
Reference |
Reference |
Reference |
Reference |
F90 Pointer |
Descriptor |
Descriptor |
Descriptor |
Descriptor |
Descriptor |
F90 Pointer [value] |
Error |
Error |
Error |
Error |
Error |
F90 Pointer [reference] |
Descriptor |
Descriptor |
Descriptor |
Descriptor |
Descriptor |
Naming Conventions |
|||||
Prefix |
_ (Windows operating systems using IA-32 architecture, Mac OS X operating systems) none for all others |
_ (Windows operating systems using IA-32 architecture, Mac OS X operating systems) none for all others |
_ (Windows operating systems using IA-32 architecture, Mac OS X operating systems) none for all others |
_ |
_ |
Suffix |
none (Windows OS) _ (Linux OS, Mac OS X) |
none |
none |
@n |
@n |
Case |
Upper Case |
Lower Case |
Lower Case |
Lower Case |
Lower Case |
Stack Cleanup |
Caller |
Caller |
Caller |
Callee |
Callee |
The terms in the above table mean the following:
The following table shows which Fortran ATTRIBUTES options match other language calling conventions.
Other Language Calling Convention |
Matching ATTRIBUTES Option |
---|---|
C/C++ cdecl (default) |
C |
C/C++ __stdcall (Windows OS only) |
STDCALL |
MASM C (in PROTO and PROC declarations) (Windows OS only) |
C |
MASM STDCALL (in PROTO and PROC declarations) (Windows OS only) |
STDCALL |
Assembly (Linux OS only) |
C |
The ALIAS option can be used with any other Fortran calling-convention option to preserve mixed-case names. You can also use the DECORATE option in combination with the ALIAS option to specify that the external name specified in ALIAS should have the correct prefix and postfix decorations for the calling mechanism in effect.
For Windows operating systems, the compiler option /iface also establishes some default argument passing conventions. The /iface option has the following choices:
Option |
How are arguments passed? |
Append @n to names on systems using IA-32 architecture? |
Who cleans up stack? |
Varargs support? |
---|---|---|---|---|
/iface:cref |
By reference |
No |
Caller |
Yes |
/iface:stdref |
By reference |
Yes |
Callee |
No |
/iface:default |
By reference |
No |
Caller |
Yes |
/iface:c |
By value |
No |
Caller |
Yes |
/iface:stdcall |
By value |
Yes |
Callee |
No |
/iface:cvf |
By reference |
Yes |
Callee |
No |