4.25.2 Interface Module

The interface module is responsible for loading the library, and providing MFL wrappers over external functions defined in it.

For the first task, the dlopen function is provided. It takes a single argument, the file name of the library to load. This can be an absolute pathname, in which case it is used as is, or a relative file name, which will be searched in the library search path (see mfmod-path). On success, the function returns the library handle, which will be used in subsequent calls to identify that library. On error, a runtime exception is signalled.

It is common to call the dlopen function in the startup section of the interface module (see startup/shutdown), so that the library gets loaded at the program startup. For example:

static number libh

prog startup
do
  set libh dlopen("mfmod_crypt.so")
done

The function dlcall is provided to call a function from the already loaded library. It is a variadic function with three mandatory parameters:

1. The handle of the loadable library as returned by dlopen.
2. Name of the external function to call.
3. Type string

The type string argument declares data types of the variable arguments. It contains a single letter for each additional argument passed to dlcall. The valid letters are:

s

The argument is of string type.

n

d

The argument is of numeric type.

m

The argument is of message type.

For example, the following will call the cryptval function defined in the previous section (supposing key and salt are two string MFL variables):

set x dlcall(libh, "cryptval", "ss", key, salt)

The last letter in type string can be ‘+’ or ‘*’. Both mean that any number of arguments are allowed (all of the type given by the penultimate type letter). The difference between the two is that ‘+’ allows for one or more arguments, while ‘*’ allows for zero or more arguments. For example, ‘n+’ means one or more numeric arguments, and ‘n*’ means zero or more such arguments. Both are intended to be used in variadic functions, e.g.:

func pringstddev(number ...)
  returns number
do
  return dlcall(libh, "stddev", "n*", $@)
done

The dlcall function returns the value returned by the library function it invoked. If the library function returns no meaningful value, it is recommended to use the void type cast around the dlcall invocation (see void type cast). E.g.:

func out(string text)
do
  void(dlcall(libh, "output", "s", text))
done

Without void type cast, the definition above will produce the following warning when compiled:

return from dlcall is ignored