Plugins

Plugins — accessing gretl plugins

Synopsis

#include <libgretl.h>

void *              gretl_dlopen                        (const char *path,
                                                         int now);
void *              gretl_dlsym                         (void *handle,
                                                         const char *name);
void *              get_plugin_function                 (const char *funcname,
                                                         void **handle);
void *              get_packaged_C_function             (const char *pkgname,
                                                         const char *funcname,
                                                         void **handle);
void                close_plugin                        (void *handle);

Description

Some of the functionality of libgretl is provided by plugin modules that are loaded on demand. Here we have functions for opening and closing plugins, and for obtaining a pointer to a symbol from a gretl plugin. These functions should work on both unix-type systems (including Mac OS X) and MS Windows.

Note that if you wish to make use of gretl plugins in your own program, you will have to build and install the plugins (of course) and you will also have to tell libgretl where to find them. This can be done via the environment variable GRETL_PLUGIN_PATH. If gretl has been installed under /usr/local then in a C program you could do:

putenv("GRETL_PLUGIN_PATH=/usr/local/lib/gretl-gtk2/");

Details

gretl_dlopen ()

void *              gretl_dlopen                        (const char *path,
                                                         int now);

Cross-platform wrapper for opening a shared code object on MS Windows or unix-type systems (including OS X).

path :

full path to the shared object to be opened.

now :

on *nix, if non-zero we call dlopen with the flag RTLD_NOW, else we use RTLD_LAZY.

Returns :

handle to the shared object.

gretl_dlsym ()

void *              gretl_dlsym                         (void *handle,
                                                         const char *name);

Cross-platform wrapper for obtained a handle to a named symbol in a shared object.

handle :

handle to shared object; see gretl_dlopen().

name :

name of symbol to look up.

Returns :

pointer corresponding to name, or NULL.

get_plugin_function ()

void *              get_plugin_function                 (const char *funcname,
                                                         void **handle);

Looks up funcname in gretl's internal plugin table and attempts to open the plugin object file that offers the given function. If successful, the handle argument receives the pointer obtained from dlopen or equivalent, and this can be used to close the plugin once the caller is finished with it; see close_plugin().

funcname :

name of function to access.

handle :

location to receive handle to shared object.

Returns :

function pointer, or NULL on failure.

get_packaged_C_function ()

void *              get_packaged_C_function             (const char *pkgname,
                                                         const char *funcname,
                                                         void **handle);


close_plugin ()

void                close_plugin                        (void *handle);

Closes a shared plugin object.

handle :

pointer obtained via the handle argument to get_plugin_function().