MKF2C(1) MKF2C(1)
NAME
mkf2c - generate FORTRAN-C interface routines
SYNOPSIS
mkf2c [ options ] [ cprog.fc [ cprog.s ] ]
DESCRIPTION
mkf2c is used to generate assembly-language routines to
provide greater flexibility when calling a C function from a
FORTRAN routine.
Mkf2c accepts as input a set of C functions, and produces an
assembly-language interface routine in the output file. If
the input and output files are not specified, mkf2c reads
from stdin and writes to stdout. The input may be a copy of
the actual C file being interfaced, perhaps filtered by the
program extcentry(1). The output of mkf2c is an assembly-
language (.s) file that must be assembled with as(1), and
loaded with the FORTRAN and C routines that are to be
interfaced.
Mkf2c uses the parameter declarations in the C function
headers to transform each parameter of the calling language
to that of the receiving language. The standard basic C
types attached to the parameters are used to determine the
object each parameter represents - i.e., whether it is a
value or pointer, its size, whether it is unsigned, etc.
Only the opening and closing brace of the function body must
be present. Information in the body of the function is
ignored. mkf2c expects its input to consist solely of the
functions it is to interface, comments, and lines which
begin with the preprocessor control character '#'. It can
match braces, enabling it to bound function bodies. It
cannot, however, understand other C constructs normally
occurring at the global level (typedefs, structure
declarations, data declarations, function prototypes, etc.).
Such unrecognized constructs must be eliminated from the
input (this is the purpose of extcentry).
Mkf2c will ignore functions of storage class static .
Make(1) contains default rules for generating an object file
which consists of a file of C functions and their associated
interface routines. If some functions in a C source file
foo.c are to be made FORTRAN-callable with special interface
routines included, those functions to be interfaced should
be surrounded by the special comments /* CENTRY */ and /*
ENDCENTRY */ (for extcentry(1)), and a dependency of foo.o
on foo.fc should be inserted in the makefile. This
dependency will cause extcentry(1) to be run on foo.c,
producing foo.fc, mkf2c to be run on foo.fc, and the
resultant .s file to be assembled and combined with the file
Page 1 (last mod. 8/20/87)
MKF2C(1) MKF2C(1)
produced by compiling foo.c with cc(1).
OPTIONS
-f Suppress extending floats to doubles across the
call. Normally, formal parameters of type float in
the C input to mkf2c are dereferenced and
converted to type double across the interface, to
conform to C calling conventions. This option
suppresses the conversion to double. If this
option is selected, the receiving routine in C
should have a prototype with the float parameters
declared correctly.
-o output Name the output file output. If the output
filename is not specified by a -o filename switch,
mkf2c will use the second filename appearing in
its argument list as the output file name. This
method must be used if it is desired to generate
an interface routine in a file when the input is
from stdin.
-U Normally, upper case characters appearing in
FORTRAN external names are mapped to lower case.
This option suppresses that mapping, allowing
FORTRAN external names to be of mixed case. This
option should be used in conjunction with the -U
option to f77(1).
-signed,-unsigned
Specify the signed attribute of single-character
parameters. The setting of this option determines
whether a scalar parameter of type char (in the C
input to mkf2c), which corresponds to a FORTRAN
argument of type character*1, should be sign-
extended across the interface. The default
setting is unsigned.
-l By default, mkf2c truncates FORTRAN external names
to six characters to conform to the ANSI standard
and to be backwards-compatible with the IRIS 4-D
Series. This switch allows the maximum number of
characters in FORTRAN external names to be the
same as that enforced by the FORTRAN front-end
(currently 32). If this switch is not specified,
the FORTRAN program should have the C function
name truncated to six characters at the call.
-v Inhibit the generation of warning messages. As
creating wrappers can cause confusion, mkf2c gives
warning messages for constructs which will result
in an interface which is 'unnatural' for C (i.e.,
in which the C side of the interface must take
Page 2 (last mod. 8/20/87)
MKF2C(1) MKF2C(1)
special precautions when accessing the parameters
or naming the routines). An example of this would
be passing a FORTRAN character variable as a C
character array. Mkf2c knows that this situation
requires C to use special care when manipulating
the string, as it is not null-terminated, and,
hence, it generates a warning message. It is
recommended that -v only be used by programmers
experienced with the generation of wrappers.
EXAMPLE
In this example, a FORTRAN program wants to call a C
function AllParameters with many parameters. The FORTRAN
program is in the file f.f and the C function is in the file
c.c. These are the only two files in the program. The C
function header is given below:
/* CENTRY */
AllParameters(i,s,c,cptr,ptr1,ptr2,ar1,f,d,d1,struct1,string1,string2,u)
short s;
char c,*cptr;
int *ptr1;
char *ptr2[];
short ar1[];
float f;
double d,*d1;
struct test_s *struct1;
char string1[],string2[30];
sometype u;
{
/*
The C function body is ignored by mkf2c.
*/
}
/* ENDCENTRY */
When this function is run through mkf2c, a complaint will be
given about not understanding the type of parameter u. It
will be assumed to be a simple pointer. Additionally, a
warning about passing the parameters string1 and string2 as
simple pointers will be given.
The parameter i will be assumed to be of type int, as it is
by the C compiler ccom during compilation.
Several items are noteworthy about the parameters in this
example. The parameters i, s, c, f, and d will be
dereferenced accross the call. The parameter f will be
extended to a double across the call unless the -f switch is
given to mkf2c(1). The parameters ptr1, ptr2, ar1, d1,
struct1, string1, and string2 will be passed as simple
Page 3 (last mod. 8/20/87)
MKF2C(1) MKF2C(1)
pointers. The FORTRAN character*1 variable which is passed
as c will be dereferenced and extended to a long across the
call. If the -signed switch is specified, c will be sign-
extended when being dereferenced. A copy of parameter cptr
will be made and the copy null-terminated. A pointer to
this copy will be passed. The C entry point will be named
AllParameters. The FORTRAN entry point name depends on
whether or not the -U and/or the -l switches have been
given. The various combinations of these switches and their
effect is detailed below:
___________________________
|Switches | FORTRAN Entry |
___________________________
| | |
<none> allpar_
| | |
-l allparameters_
| | |
-U AllPar_
| | |
-l -U AllParameters_
|_________|________________|
The program can be made easily using the built-in rules in
make(1). The makefile would be as follows:
test: f.o c.o
f77 -o test f.o c.o
c.o: c.fc
clean:
rm -f *.o test *.fc
In the make, the program extcentry will be run on c.c to
produce c.fc. This program (see extcentry(1)) will copy to
c.fc all text in c.c which is between the special comments
/* CENTRY */ and /* ENDCENTRY */. Mkf2c will then be run on
c.fc, and the make variable F2CFLAGS will be passed to it.
The C source will be compiled with cc(1), and the output of
mkf2c will be assembled. These two .os will then be loaded
together into a single relocatable named c.o.
If it is desired to pass mkf2c(1) some flags (e.g., -l and
-signed), the make variable F2CFLAGS should be set in the
makefile, as
F2CFLAGS = -signed -l
SEE ALSO
DIAGNOSTICS
Mkf2c is very simple-minded about diagnosing syntax errors.
It can detect such things as a formal parameter having its
type declared when it is not in the formal parameter list.
Page 4 (last mod. 8/20/87)
MKF2C(1) MKF2C(1)
A few such cases give intelligible error messages. The
program will complain about types it does not understand.
The default type assigned in such cases is simple pointer.
Mkf2c will also delete characters from FORTRAN entry names
which are illegal (e.g., underscores). The user will be
warned in such instances. Most errors that the programs
detect are indicated only by the source line number.
If mkf2c encounters an error which it cannot remedy, it will
abort, giving the line number on which the error occurred.
The resultant .s file will be removed, and an error exit
will be taken.
Because of its limited error diagnostic ability, it is
advisable to use cc (1) to determine whether the input
syntax is correct before passing it to mkf2c.
AUTHOR
Greg Boyd
ORIGIN
Silicon Graphics, Inc.
Page 5 (last mod. 8/20/87)