This section discusses items to consider before calling C functions from Fortran.

subroutine MATRIX
subroutine Matrix
subroutine matrix

call nret (*1,*2Ex,*3)

goto (1,2,3), nret()

The following rules apply to arguments passed between Fortran and C:

When a C function calls a Fortran routine, the C function must explicitly specify these items in its argument list in the following order:

The examples on the following pages illustrate these rules.

C  Fortran call to SAM, a routine written
C  in Fortran
   EXTERNAL F
   CHARACTER*7 S
   INTEGER B(3)
   …
   CALL SAM (F, B(2), S)

/* C call to SAM, a routine written in Fortran */
/* We pass in the function pointer for the     */
/* Fortran SUBROUTINE F                        */
char s[7];
int  b[3];
extern void sam_(void (*)(), int *, char*);
                        /* Fortran subroutine SAM          */
extern void f_();       /* Fortran subroutine F            */
…
sam_(F, &B[1], S);      /* We pass in pointer to Fortran F */
                        /* for Fortran call-by-reference   */

C  Fortran call to F, a function written
C  in Fortran
   EXTERNAL F
   CHARACTER*10 F, G
   G = F()

/* C call to SAM, a routine written in Fortran */
/* which returns a string.                     */
CHAR S[10];
. . .
f_(S, 10);

C  function F, written in Fortran
   CHARACTER*10 FUNCTION F()
   F = `0123456789'
   RETURN
   END

Fortran stores arrays in column-major order with the leftmost subscript varying the fastest. C, however, stores arrays in the opposite arrangement (row-major order), with the rightmost subscripts varying the fastest.

Here is how the layout of the Fortran array looks:

integer t (2,3)
t(1,1), t(2,1), t(1,2), t(2,2), t(1,3), t(2,3)

Here is how the layout of the C array looks:

int t [2] [3]
t[0][0], t[0][1], t[0][2], t[1][0], t[1][0], t[1][1],t[1][2]

Note that the default for the lower bound of an array in Fortran is 1, where the default in C is 0.

When a C routine uses an array passed by a Fortran subprogram, the dimensions of the array and the use of the subscripts must be interchanged, as shown in Figure 3-1.

Figure 3-1. Array Subscripts

The Fortran caller prints out the value 99. Note the following:

The following rules apply to accessing common blocks of data:

The following examples show C and Fortran routines that access common blocks of data.

Fortran

subroutine sam()
common /r/ i, r
i = 786
r = 3.2
return
end

C

struct S {int i; float j;}r_;
main () {
sam_() ;
printf("%d %f\n",r_.i,r_.j);
}

The C routine prints out 786 and 3.2.

The mkf2c program uses C data-type declarations for parameters to generate the correct assembly language interface. In generating a Fortran-callable entry point for an existing C-callable function, the C function is passed through mkf2c, and mkf2c adds additional entry points. Native language entry points are not altered.

Use these rules with mkf2c:

A simple case of using a function as input to mkf2c is

func()
{}

Here, the function func has no parameters. If mkf2c is used to produce a Fortran-to-C wrapper, the Fortran entry is func_. The wrapper func_ simply calls the C routine func().

Here is another example:

simplefunc (a)
int a;
{}

In this example, the function simplefunc has one argument, a. The argument is of type int. For this function, mkf2c produces three items: a Fortran entry, simple, and two pieces of code. The first piece of code dereferences the address of a, which was passed by Fortran. The second passes the resulting int to C. It then calls the C routine simplefunc().

You can specify the length of a character variable passed as a parameter to Fortran either at compilation or at run time. The length is determined by the declaration of the parameter in the Fortran routine. If the declaration contains a length, the passed length must match the declaration. For example, in the following declaration, the length of the string is declared to be 10 characters:

character*10 string

The passed length must be 10 in order to match the declaration.

When this next declaration is used, the passed length is taken for operations performed on the variable inside the routine:

character*(*) string

The length can be retrieved by use of the Fortran intrinsic function LEN. Substring operations may cause Fortran run-time errors if they do not check this passed length.

Arrays of character variables are treated by Fortran as simple byte arrays, with no alignment of elements. The length of the individual elements is determined by the length passed at run time. For instance, the array sarray() can be declared in this manner:

character*(*) sarray()

This length is necessary to compute the indexes of the array elements. The program mkf2c has special constructs for dealing with the lengths of Fortran character variables.

The program mkf2c reduces each parameter to one of seven simple objects. The following list explains each object.

Below is an example of a C specification for a function:

test (i,s,c,ptr1,ar1,u,f,d,d1,str1,str2,str3)
short s;
unsigned char c;
int *ptr1;
char *ptr2[];
short ar1[];
sometype u;
float f;
long float d, *d1;
char *str1;
char str2[],str3[30];
 {
   /* The C function body CAN go here. Nothing
   except the opening and closing braces are
   necessary */

If this function were passed to mkf2c, the parameters would be transformed as follows:

When the wrapper generator is used, a character variable that is specified as char* in the C parameter list is copied and null terminated. C may thus determine the length of the string by the use of the standard C function strlen.

If a character variable is specified as a character array in the C parameter list, the address of the character variable is passed, making it impossible for C to determine its length, as it is not null terminated. When the call occurs, the wrapper code receives this length from Fortran. For those C functions needing this information, the wrapper passes it by extending the C parameter list.

For example, if the C function header is specified as follows

func1 (carr1,i,str,j,carr2)
char carr1[],*str,carr2[];
int i, j;
{}

mkf2c will pass a total of seven parameters to C. The sixth parameter will be the length of the Fortran character variable corresponding to carr1, and the seventh will be the length of carr2. The C function func1() must use the varargs macros to retrieve these hidden parameters. mkf2c will ignore the

varargs macro va_alist appearing at the end of the parameter name list and its counterpart va_alist appearing at the end of the parameter type list. In the case above, use of these macros would produce the function header

#include "varargs.h"
func1 (carr1,i,str,j,carr2,va_alist)
char carr1[], *str, carr2[];
int i, j;
va_dcl
{}

The C routine could retrieve the lengths of carr1 and carr2, placing them in the local variables carr1_len and carr2_len by the following code fragment:

va_list ap;
int carr1_len, carr2_len;
va_start(ap);
carr1_len = va_arg (ap, int)
carr2_len = va_arg (ap, int)

mkf2c understands only a limited subset of the C grammar. This subset includes common C syntax for function entry point, C-style comments, and function bodies. However, it cannot understand constructs such as typedefs, external function declarations, or C preprocessor directives.

To ensure that only those constructs understood by mkf2c are included in wrapper input, you need to place special comments around each function for which Fortran-to-C wrappers are to be generated (see example below).

Once these special comments, /* CENTRY */ and /* ENDCENTRY */, are placed around the code, use the program excentry(1) before mkf2c to generate the input file for mkf2c.

To illustrate the use of extcentry, the C file foo.c is shown below. It contains the function foo, which is to be made Fortran callable.

typedef unsigned short grunt [4];
struct {
   long 1,11;
   char *str;
} bar;
main ()
{
   int kappa =7;
   foo (kappa,bar.str);
}
/* CENTRY */
foo (integer, cstring)
int integer;
char *cstring;
{
   if (integer==1) printf("%s",cstring);
} /* ENDCENTRY */

The special comments /* CENTRY */ and /* ENDCENTRY */ surround the section that is to be made Fortran callable. To generate the assembly language wrapper foowrp.s from the above file foo.c, use the following set of commands:

% extcentry foo.c foowrp.fc% mkf2c foowrp.fc foowrp.s

The programs mkf2c and extcentry are found in the directory /usr/bin on your workstation.

make(1) contains default rules to help automate the control of wrapper generation. The following example of a makefile illustrates the use of these rules. In the example, an executable object file is created from the files main.f (a Fortran main program) and callc.c:

test:  main.o callc.o
   f77 -o test main.o callc.o
callc.o: callc.fc
clean:
   rm -f *.o test *.fc

In this program, main calls a C routine in callc.c. The extension .fc has been adopted for Fortran-to-call-C wrapper source files. The wrappers created from callc.fc will be assembled and combined with the binary created from callc.c. Also, the dependency of callc.o on callc.fc will cause callc.fc to be recreated from callc.c whenever the C source file changes. (The programmer is responsible for placing the special comments for extcentry in the C source as required.)

---

Note: Options to mkf2c can be specified when make is invoked by setting the make variable F2CFLAGS. Also, do not create a .fc file for the modules that need wrappers created. These files are both created and removed by make in response to the file.o:file.fc dependency.

---

The makefile above will control the generation of wrappers and Fortran objects. You can add modules to the executable object file in one of the following ways:

This section explains procedure and function declaration considerations.

call nret (*1,*2,*3)

goto (1,2,3), nret()

character*15 function g (…)

type string = array [1..15];
var
   length: integer;
   a: array[1..15] of char;
procedure g_(var a:string;length:integer;…); external;

g_ (a, 15);

The following rules apply to argument specifications in both Fortran and Pascal programs:

When a Pascal program calls a Fortran subprogram, the Pascal program must explicitly specify these items in its argument list in the following order:

C  SAM IS A ROUTINE WRITTEN IN FORTRAN
   EXTERNAL F
   CHARACTER*7 S
   INTEGER B(3)
   …
   CALL SAM (F, B(1), S) <– Length of S is implicit.

PROCEDURE F_; EXTERNAL;
S: ARRAY[1..7] OF CHAR;
B: ARRAY[1..3] OF INTEGER;
   …
SAM_ (F, B[1], S, 7);  <– Length of S is explicit.

Pascal checks certain variables for errors at execution time, whereas Fortran does not. For example, in a Pascal program, when a reference to an array exceeds its bounds, the error is flagged (if run-time checks are not suppressed). Use the f77–c option if you want a Fortran program to detect similar errors when you pass data to it from a Pascal program.

Fortran stores arrays in column-major order, where the leftmost subscripts vary the fastest. Pascal, however, stores arrays in row-major order, with the rightmost subscript varying the fastest. Also, the default lower bound for arrays in Fortran is 1. Pascal has no default; the lower bound must be explicitly specified. Here is an example of the various layouts:

Fortran

integer t (2,3)
t(1,1), t(2,1), t(1,2), t(2,2), t(1,3), t(2,3)

Pascal

var t: array[1..2,1..3] of integer;
t[1,1], t[1,2], t[1,3], t[2,1], t[2,2], t[2,3]

When a Pascal routine uses an array passed by a Fortran program, the dimensions of the array and the use of the subscripts must be interchanged. The example below shows the Pascal code that interchanges the subscripts.

In the following example, the Fortran routine calls the Pascal procedure p, receives the value 99, and prints it out.

Fortran

   INTEGER A(2,3)
   CALL P (A, 1, 3)
   WRITE (6,10) A(1,3)
10 FORMAT (1X, I9)
   STOP
   END

Pascal

TYPE ARRY = ARRAY [1..3,1..2];
PROCEDURE P_(VAR A:ARRY; VAR I,J:INTEGER);
BEGIN
 A[I,J] := 99;
END;

In the next example, the Pascal routine passes the character string "0123456789" to the Fortran subroutine S_, which prints it out and then returns to the calling program.

Pascal

TYPE STRING = ARRAY[1..10] OF CHAR;
PROCEDURE S_( VAR A: STRING; I: INTEGER); EXTERNAL;
/* Note the underbar */
PROGRAM TEST;
VAR
 R: STRING;
BEGIN
 R:= "0123456789";
 S_(R,10);
END.

Fortran

   SUBROUTING S(C)
   CHARACTER*10 C
   WRITE (6,10) C
10 FORMAT (6,10) C
   RETURN
   END

The following rules apply to accessing common blocks of data:

VAR
A_: RECORD
    I : INTEGER;
    R : REAL;
END;
PROCEDURE SAM_;
 EXTERNAL;
PROGRAM S;
BEGIN
A_.I := 4;
A_.R := 5.3;
SAM_;
END.

   SUBROUTINE SAM()
   COMMON /A/I,R
   WRITE (6,10) i,r
10 FORMAT (1x,I5,F5.2)
   RETURN
   END