11.1 Compatibility Issues

Most C-Fortran interfaces must agree in all of these aspects:

• Function and subroutine definitions and calls

• Data type compatibility

• Argument passing, either by reference or by value

• Order of arguments

• Procedure name, either uppercase, lowercase, or with a trailing underscore (_)

• Passing the right library references to the linker

Some C-Fortran interfaces must also agree on:

• Array indexing and order

• File descriptors and stdio

• File permissions

11.1.1 Function or Subroutine?

The word function has different meanings in C and Fortran. Depending on the situation, the choice is important:

• In C, all subprograms are functions; however, void functions do not return a value.

• In Fortran, a function passes a return value, but a subroutine generally does not.

When a Fortran routine calls a C function:

• If the called C function returns a value, call it from Fortran as a function.

• If the called C function does not return a value, call it as a subroutine.

When a C function calls a Fortran subprogram:

• If the called Fortran subprogram is a function, call it from C as a function that returns a compatible data type.

• If the called Fortran subprogram is a subroutine, call it from C as a function that returns a value of int (compatible to Fortran INTEGER*4) or void otherwise. A value is returned if the Fortran subroutine uses alternate returns, in which case it is the value of the expression on the RETURN statement. If no expression appears on the RETURN statement, and alternate returns are declared on the SUBROUTINE statement, a zero is returned.

11.1.2 Data Type Compatibility

Table 11–2 summarizes the data sizes and default alignments for Fortran 95 data types compared with C. It assumes no compilation options affecting alignment or promoting default data sizes are applied. Note the following:

• C data types int, long int, and long are equivalent (4 bytes) in a 32-bit environment. However, in a 64-bit environment, long and pointers are 8 bytes. This is referred to as the LP64 data model.

• REAL*16 and COMPLEX*32, in a 64-bit SPARC environment and when compiling with any -m64 option, are aligned on 16-byte boundaries.

• Alignments marked 4/8 indicate that alignment is 8-bytes by default, but on 4-byte boundaries in COMMON blocks. The maximum default alignment in COMMON is 4-bytes. 4/8/16 indicates alignments on 16-byte boundaries when compiling with -m64 option.

• REAL(KIND=16), REAL*16, COMPLEX(KIND=16), COMPLEX*32, are only available on SPARC platforms.

• The elements and fields of arrays and structures must be compatible.

• You cannot pass arrays, character strings, or structures by value.

• You can pass arguments by value from a Fortran 95 routine to a C routine by using %VAL(arg) at the call site. You can pass arguments by value from C to Fortran 95 provided the Fortran routine has an explicit interface block that declares the dummy argument with the VALUE attribute.

• Components of numeric sequence types are aligned the same way as common blocks, and are also affected by the -aligncommon option.A numeric sequence type is a sequence type where all the components are of type default integer, default real, double-precision real, default complex, or default logical, and are not pointers.

• Components of data types that are not numeric sequence types are aligned on natural alignments in most cases, except QUAD variables. For quad-precision variables, the alignment is different between 32–bit and 64–bit SPARC platforms.

• Components of VAX structures and data types defined with the BIND(C) attribute always have the same alignment as C structures on all platforms.

11.1.3 Case Sensitivity

C and Fortran take opposite perspectives on case sensitivity:

• C is case sensitive—case matters.

• Fortran ignores case by default.

The f95 default is to ignore case by converting subprogram names to lowercase. It converts all uppercase letters to lowercase letters, except within character-string constants.

There are two usual solutions to the uppercase/lowercase problem:

• In the C subprogram, make the name of the C function all lowercase.

• Compile the Fortran program with the -U option, which tells the compiler to preserve existing uppercase/lowercase distinctions on function/subprogram names.

Use one of these two solutions, but not both.

Most examples in this chapter use all lowercase letters for the name in the C function, and do not use the f95 -U compiler option.

11.1.4 Underscores in Routine Names

The Fortran compiler normally appends an underscore (_) to the names of subprograms appearing both at entry point definition and in calls. This convention differs from C procedures or external variables with the same user-assigned name. Almost all Fortran library procedure names have double leading underscores to reduce clashes with user-assigned subroutine names.

There are three usual solutions to the underscore problem:

• In the C function, change the name of the function by appending an underscore to that name.

• Use the BIND(C) attribute declaration to indicate that an external function is a C language function.

• Use the f95 -ext_names option to compile references to external names without underscores.

Use only one of these solutions.

The examples in this chapter could use the BIND(C) attribute declaration to avoid underscores. BIND(C) declares the C external functions that can be called from Fortran, and the Fortran routines that can be called from C as arguments. The Fortran compiler does not append an underscore as it ordinarily does with external names. The BIND(C) must appear in each subprogram that contains such a reference. The conventional usage is:

       FUNCTION ABC
        EXTERNAL XYZ
        BIND(C) ABC, XYZ

Here the user has specified not only that XYZ is an external C function, but that the Fortran caller, ABC, should be callable from a C function. If you use BIND(C), the C function does not need an underscore appended to the function name.

11.1.5 Argument-Passing by Reference or Value

In general, Fortran routines pass arguments by reference. In a call, if you enclose an argument with the nonstandard function %VAL(), the calling routine passes it by value.

The standard Fortran 95 way to pass arguments by value is the VALUE attribute and through INTERFACE blocks. See 11.4 Passing Data Arguments by Value.

In general, C passes arguments by value. If you precede an argument by the ampersand operator (&), C passes the argument by reference using a pointer. C always passes arrays and character strings by reference.

11.1.6 Argument Order

Except for arguments that are character strings, Fortran and C pass arguments in the same order. However, for every argument of character type, the Fortran routine passes an additional argument giving the length of the string. These are long int quantities in C, passed by value.

The order of arguments is:

• Address for each argument (datum or function)

• A long int for each character argument (the whole list of string lengths comes after the whole list of other arguments)

Example:

CHARACTER*7 S
INTEGER B(3)
...
 CALL SAM( S, B(2) )

char s[7];
int b[3];
...
sam_( s, &b[1], 7L ) ; 

11.1.7 Array Indexing and Order

Array indexing and order differ between Fortran and C.

11.1.7.1 Array Indexing

C arrays always start at zero, but by default Fortran arrays start at 1. There are two usual ways of approaching indexing.

• You can use the Fortran default, as in the preceding example. Then the Fortran element B(2) is equivalent to the C element b[1].

• You can specify that the Fortran array B starts at B(0) as follows:

      INTEGER B(0:2)

This way, the Fortran element B(1) is equivalent to the C element b[1].

11.1.7.2 Array Order

Fortran arrays are stored in column-major order: A(3,2)

A(1,1)  A(2,1)  A(3,1)  A(1,2)  A(2,2)  A(3,2)

C arrays are stored in row-major order: A[3][2]

A[0][0] A[0][1] A[1][0] A[1][1] A[2][0] A[2][1]

This does not present a problem for one-dimensional arrays. However, with multi-dimensional arrays, be aware of how subscripts appear and are used in all references and declarations—some adjustments might be necessary.

For example, it may be confusing to do part of a matrix manipulation in C and the rest in Fortran. It might be preferable to pass an entire array to a routine in the other language and perform all the matrix manipulation in that routine to avoid doing part in C and part in Fortran.

11.1.8 File Descriptors and stdio

Fortran I/O channels are in terms of unit numbers. The underlying SunOS operating system does not deal with unit numbers but with file descriptors. The Fortran runtime system translates from one to the other, so most Fortran programs do not have to recognize file descriptors.

Many C programs use a set of subroutines, called standard I/O (or stdio). Many functions of Fortran I/O use standard I/O, which in turn uses operating system I/O calls. Some of the characteristics of these I/O systems are listed in the following table.

11.1.9 Libraries and Linking With the f95 Command

To link the proper Fortran and C libraries, use the f95 command to invoke the linker.

Example 1: Use the compiler to do the linking:

demo% cc -c someCroutine.c
demo% f95 theF95routine.f someCroutine.o  <- The linking step
demo% a.out
 4.0 4.5
 8.0 9.0
demo%