70.13.3 How to write an input file for Fcc

Fcc is a Basis utility which takes as input simple prototypes of C functions and produces ``wrapper'' functions which, when called from FORTRAN, convert the FORTRAN parameters to what C expects, and then calls the C function accordingly. If the C function returns a value, then that value will be returned to FORTRAN. Because the language directive causes mac to create an Fcc input file automatically, most users will never need to use Fcc directly, and can bypass this section. However, power users may wish to know how to set up their own Fcc input files, and how to use Fcc to process them.

Fcc accepts the interface file name as a command line argument, has two command line options, -h and -c. The option -h causes a file Fcc.h to be created which is appropriate for the current machine. The option -c causes the file Fcc.c to be created, which is the file containing the runtime support routines needed by the glue routines created by Fcc. The interface file itself contains a series of descriptions of C routines which are to be called from Fortran. Each of these descriptions has the form:

      [return_type] Name(argument_list) [alias ActualCName]

where the square brackets denote optional items.

Name is the name of the C-language routine. It must be a mixed-case name if the alias clause is not given. The Fortran call should be to a routine called name, where name is the lower- or upper-case version of Name. The C routine called will be Name, or ActualCName if an alias clause is present.

argument_list is a (possibly empty) list of type designators separated by commas. This list should be the same length as the argument list of the C routine. return_type, if present, is a single type designator, or the word `subroutine'. A type designator is one of the following: integer, logical, real, real(Size4), real (Size8), real(Size16), Address, character, or string. This type designator is preceded by an ampersand in the argument list if the corresponding argument is to be passed by address. The two cases where this is needed are: (a) the argument is an array, or (b) the argument represents an output argument.

The type `string' is handled in a special way:

  1. If an argument type is `string', the C routine receives a C string that is a null-terminated copy of the actual argument with trailing blanks deleted.
  2. If an argument type is '&string', the C routine receives a blank, null-terminated string of the same length as the Fortran character variable used as an actual argument. On return from the C routine, the actual argument is filled with whatever resides in the string the C-routine received, less the final null, and is then blank padded if necessary to its full length.

A string argument cannot be used for both input and output.

The type `character' is also handled in a special way. Because some Fortrans limit the size of a string, it is sometimes necessary to use a long array of character*1 to hold all the characters. To pass such an array to C, use `character' or `&character' as its type; the next argument after a `character' or `&character' argument must be an integer argument telling how many characters of the character array are to be used. The C wrapper routines then use the array of character*1 the same as a string of that length, as described above.

The type `real' is an abbreviation for real(Size8), unless the -r4 option for mac has been used, in which case it is an abbreviation for real(Size4). You are encouraged to spell out the desired kind qualifier and not rely on this option. (Which is why we don't mention it in the option section, we were hoping you wouldn't notice.)