ATTRIBUTES Properties and Calling Conventions

The ATTRIBUTES properties (also known as options) C, STDCALL (Windows* only), REFERENCE, VALUE, and VARYING affect the calling convention of routines. You can specify:

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*, 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:

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.

Calling Conventions for ATTRIBUTES Options

Argument Default C C, REFERENCE STDCALL
(Windows* IA-32 architecture)
STDCALL, REFERENCE
(Windows* 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 systems using IA-32 architecture, Mac OS systems)
none
for all others

_ (Windows systems using IA-32 architecture, Mac OS systems)
none
for all others

_ (Windows systems using  IA-32 architecture, Mac OS systems)
none
for all others

_

_

Suffix

none (Windows)

_ (Linux, Mac OS)

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:

[value]

Argument assigned the VALUE attribute.

[reference]

Argument assigned the REFERENCE attribute.

Value

The argument value is pushed on the stack. All values are padded to the next 4-byte boundary.

Reference

On systems using IA-32 architecture, the 4-byte argument address is pushed on the stack.
On systems using Intel® 64 and IA-64 architectures, the 8-byte argument address is pushed on the stack.

Len:End or Len:Mixed

For certain string arguments:

  • Len:End applies when -nomixed-str-len-arg (Linux and Mac OS) or /iface:nomixed_str_len_arg (Windows) is set. The length of the string is pushed (by value) on the stack after all of the other arguments. This is the default.

  • Len:Mixed applies when -mixed-str-len-arg (Linux and Mac OS) or  /iface:mixed_str_len_arg (Windows) is set. The length of the string is pushed (by value) on the stack immediately after the address of the beginning of the string.

No Len or Len:Mixed

For certain string arguments:

  • No Len applies when nomixed-str-len-arg (Linux and Mac OS) or /iface:nomixed_str_len_arg (Windows) is set. The length of the string is not available to the called procedure. This is the default.

  • Len:Mixed applies when mixed-str-len-arg (Linux and Mac OS) or  /iface:mixed_str_len_arg (Windows) is set. The length of the string is pushed (by value) on the stack immediately after the address of the beginning of the string.

No Len

For string arguments, the length of the string is not available to the called procedure.

String(1:1)

For string arguments, the first character is converted to INTEGER(4) as in ICHAR(string(1:1)) and pushed on the stack by value.

Error

Produces a compiler error.

Descriptor

On systems using IA-32 architecture, the 4-byte address of the array descriptor.
On systems using Intel® 64 architecture and systems using IA-64 architecture, the 8-byte address of the array descriptor.

@n

On systems using IA-32 architecture, the at sign (@) followed by the number of bytes (in decimal) required for the argument list.

Size dependent

On systems using IA-32 architecture, derived-type arguments specified by value are passed as follows:

  • Arguments from 1 to 4 bytes are passed by value.

  • Arguments from 5 to 8 bytes are passed by value in two registers (two arguments).

  • Arguments more than 8 bytes provide value semantics by passing a temporary storage address by reference.

Upper Case

Procedure name in all uppercase.

Lower Case

Procedure name in all lowercase.

Callee

The procedure being called is responsible for removing arguments from the stack before returning to the caller.

Caller

The procedure doing the call is responsible for removing arguments from the stack after the call is over.

The following table shows which Fortran ATTRIBUTES options match other language calling conventions.

Matching Calling Conventions

Other Language Calling Convention Matching ATTRIBUTES Option

C/C++ cdecl (default)

C

C/C++ __stdcall (Windows only)

STDCALL

MASM C (in PROTO and PROC declarations) (Windows only)

C

MASM STDCALL (in PROTO and PROC declarations)  (Windows only)

STDCALL

Assembly (Linux 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 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