Next: , Up: External Calls to C   [Index]


14.1.1 External C Call Infrastructure

For a C program to be connected to an INTERCAL program, it needs to be marked with the correct header file, and needs to have functions marked for communication with the INTERCAL program.

#include <ick_ec.h>

The header file ick_ec.h must be included using the preprocessor in any file which uses any of the INTERCAL external call functions, variables, or macros. (Note that this file may not necessarily exist, or exist in the usual place; ick will deal with making sure the correct header file is included.) This will include stdint.h (a standard C header file, which must exist on your system), so that you can access INTERCAL variables (the INTERCAL types onespot, twospot, tail, hybrid correspond to the C types uint16_t, uint32_t, uint16_t*, uint32_t* respectively); also, it will provide the prototypes for all the functions and definitions for all the macros needed to use the external calls system with C.

ICK_EC_FUNC_START
ICK_EC_FUNC_END

Many of the INTERCAL interface macros (ick_linelabel, ick_comefrom, and ick_nextfrom) make it possible to jump from an INTERCAL program to a C program. Because C doesn’t allow jumping into the middle of a function, there has to be some way to create a block of code which can be jumped into. This is what these two macros achieve.

This declaration and definition:

ICK_EC_FUNC_START(identifier)
{
  /* code goes here */
}
ICK_EC_FUNC_END

is equivalent to this:

void identifier(void)
{
  /* code goes here */
}

except that it is possible to jump from an INTERCAL program into the declared and defined program. (If you need to write a prototype for the function early, void identifier(void); is perfectly acceptable, but an early prototype is not required unless you call the function from earlier within the C code.) Of course, you can substitute any identifier that’s legal as a function name for identifier (as long as it doesn’t start with ick_ or ICK_). The resulting function is a function (for instance, you can take its address or call it in the usual ways); the only differences are that it can be jumped into from INTERCAL code and that it is constrained to take no arguments and return no data. (It can still access global and INTERCAL variables.) If the function is jumped into from INTERCAL code, but then control flow reaches the end of the function, or the function return;s but was not called from C, the resulting behaviour is undefined; C-INTERCAL will attempt to continue by some means at that point, but may fail. If a function is unsure whether it gained control from C or from INTERCAL code, it may use ick_return_or_resume (described below).

Because you are not allowed to declare two C functions with the same name (even in different modules), all functions declared with ICK_EC_FUNC_START must have unique names across the entire compilation.


Next: , Up: External Calls to C   [Index]