MKF2C(1)MKF2C(1)NAMEmkf2c - generate FORTRAN-C interface routines
SYNOPSISmkf2c [ options ] [ cprog.fc [ cprog.s ] ]
DESCRIPTIONmkf2c 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.
The assembly-language output is KPIC code which must be assembled with
the -KPIC option to as(1) unless an unshared .o is desired.
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.
For C functions in K&R style, the opening and closing brace of the
function body must be present. Information in the body of the function is
ignored. For C functions in ANSI C function prototype style, the function
may be either a definition (and whatever is between the opening and
closing brace is ignored) or a declaration (ie, with ; rather than {}).
Function parameters in ANSI C style function prototypes need not name the
parameters. Function parameters in ANSI C style function prototypes
cannot use typedef names to declare parameter types.
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(1)).
Mkf2c will ignore functions of storage class static .
The simplest way to generate an interface for a C function is to simply
hand-code a copy of the function which consists of the entry and
parameter declarations with an empty body. This stub, which is
traditionally suffixed with .fc is then used as input to mkf2c, and the
resultant .s file is assembled and linked into the executable. The root
name of the stub file must differ from the root name of the file
Page 1
MKF2C(1)MKF2C(1)
containing the actual C functions (so that the name of the resultant .os
differ). NOTE: the -KPIC switch must be given to as(1) unless the object
is to be non-shared.
mkf2c foo.fc foo.s
as -KPIC foo.s -o foo.o
It is also possible to create wrappers from existing C source code. This
is done by adding special rules to your makefile and adding special
comments around each function for which an interface is to be generated.
See the example at the end of this man page.
The options to mkf2c(1) are the following:
-32 Generate wrappers with (old) 32-bit calling conventions. At
this time, it is the default, but may change as different ABIs
become the future default.
-64 Generate wrappers with 64-bit pointer sizes, and using the 64
bit calling conventions.
-n32 Generate wrappers with the n32 calling conventions.
-f Suppress extending floats to doubles across the call. Normally,
formal parameters of type float in the (K&R) 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. For declarations
input to mkf2c in ANSI C style function prototypes float
arguments are not extended, so -f need not be supplied.
-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.
Page 2
MKF2C(1)MKF2C(1)-u Keep underscores in function names. By default underscores are
removed and a warning is issued.
-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 4D 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.
-w 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 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
-w only be used by programmers experienced with the generation
of wrappers.
-call_same_dso
This is used when the wrapper and the target C function will be
placed in the same DSO. A further optimization is taken which
removes the restoring of the gp register after the call return.
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 special comments /*CENTRY*/ and /*ENDCENTRY*/ have
been added to the C source code to bracket the function for which an
interface is to be generated. The C function header is given below:
Page 3
MKF2C(1)MKF2C(1)
/* 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. (These FORTRAN
character variables each have an associated length which is passed as a
hidden parameter to the C function, at the end of the parameter list.
These additional parameters may be accessed by the C function by the use
of the varargs macros. See the FORTRAN Language Reference Manual for
more information.)
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 across 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 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
Page 4
MKF2C(1)MKF2C(1)
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 and the interface generated automatically
by adding the following special rules to your makefile:
# .fc must be added to your SUFFIXES between .c and .o
.SUFFIXES:
.SUFFIXES: .o .fc .c .s .f
F2CFLAGS=
ASFLAGS=-KPIC
test: f.o c.o
f77 -o test f.o c.o
# note -- each .c file containing routines to be interfaced must have
# a dependency such as the following
c.o: c.fc
.fc.o:
cc $(CFLAGS) -c $*.c
mkf2c $(F2CFLAGS) $< $*.s
as $(ASFLAGS) -o $*.wo $*.s
ld -r $*.o $*.wo -o $*.tmp
mv $*.tmp $*.o
rm -f $*.s $*.wo
.c.fc:
extcentry $*.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
Page 5
MKF2C(1)MKF2C(1)
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) (using cc $CFLAGS), and
the output of mkf2c will be assembled (with as $ASFLAGS). 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 ALSOextcentry(1), cc(1), FORTRAN Language Reference Manual
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. 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.
BUGSmkf2c does not understand the ANSI notation a(void) as meaning a function
with no arguments.
In ANSI C style function prototypes, typedef names cannot be used.
AUTHOR
Greg Boyd
Page 6
