mkf2c(1)
mkf2c - generate FORTRAN-C interface routines
As shipped in IRIX 6.5. First release of IRIX 6.5.
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. 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 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. -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: /* 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 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 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 ALSO extcentry(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. BUGS mkf2c 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