LIBIRCCD(3) - Library Functions Manual

NAME

libirccd - irccd C interface

SYNOPSIS

const char *<prefix>_author;
const char *<prefix>_description;
const char *<prefix>_version;
const char *<prefix>_license;

void
<prefix>_set_option(const char *key, const char *value);

void
<prefix>_set_template(const char *key, const char *value);

void
<prefix>_set_path(const char *key, const char *value);

const char *‌
<prefix>_get_option(const char *key);

const char *‌
<prefix>_get_template(const char *key);

const char *‌
<prefix>_get_path(const char *key);

const char * const *‌
<prefix>_get_options(void);

const char * const *‌
<prefix>_get_templates(void);

const char * const *‌
<prefix>_get_paths(void);

int
<prefix>_load(void);

void
<prefix>_reload(void);

void
<prefix>_unload(void);

void
<prefix>_event(const struct irc_event *ev);

DESCRIPTION

The libirccd library is a set of functions available from the irccd(1) daemon when writing native C plugins. It isn’t shipped as a library because it opens plugins dynamically and exports its own set of symbols through it. Plugins don’t need any kind of link when built.

The API offers various utilities to control the daemon by inspecting servers, rules, plugins or hooks. It also offers various miscellaneous utilities along with some compatibility shims.

This documentation only shows a quick overview of what is available, documentation of very modules is done through the set of libirccd-MODULE-NAME(3) manual pages.

For “namespace” issue, every symbol or macros are prefixed by irc_ or IRC_.

An example of plugin can be found at /usr/share/doc/irccd/sample-plugin.c

PLUGIN INTERFACE

To be opened by irccd(1) the plugin has to match a specific ABI. Several variables and functions should be exported using a specific prefix and variable names.

The <prefix> as shown in the SYNOPSIS section is computed using the plugin base file name and translating every non C character to an “_”. For example, if the plugin is named irc-notify.so then the prefix will be irc_notify and subsequent function to implement should be named irc_notify_event(), irc_notify_get_option() and so on.

Every variable and function are completely optional.

Variables

The <prefix>_author, <prefix>_description, <prefix>_version, and <prefix>_license variables can be declared as plugin metadata to inform about the plugin author, a short description, its version and the license respectively.

Functions

The following functions can be implemented in the plugin and called from irccd(1) upon certain circumstances.

The <prefix>_set_option(), <prefix>_set_template() and <prefix>_set_path() are called when the user wants to change the property key to the new value. If the key isn’t supported by the plugin, no action should be taken. They alter the plugin options, user templates and predefined paths respectively.

The <prefix>_get_option(), <prefix>_get_template() and <prefix>_get_path() are the exact opposite of their set_*‌ counterparts, they should return the value associated with the key argument. If the plugin does not support the given key it should return NULL to indicate it.

The <prefix>_get_options(), <prefix>_get_templates() and <prefix>_get_paths() should return a NULL terminated array of strings that the plugin supports for options, templates and paths respectively. The returned array isn’t free’d so the user may return a static array for convenience.

The <prefix>_load() function is called when the plugin is being loaded before being added to the daemon. If the function returns non-zero it is treated as an error an not loaded.

The <prefix>_reload() is called when the user requests to reload the plugin.

The <prefix>_unload() is called when the plugin is about to be removed.

The <prefix>_event() is called upon reception of a new IRC server message. See the libirccd-event(3) module about how to use the argument ev.

MODULES

The following APIs are available

libirccd-server(3)

Manipulate servers. This module is probably the one you will use the most while writing plugins. It lets you send messages through an IRC server.

libirccd-channel(3)

Channel information.

libirccd-compat(3)

Compatibility layer offered for various BSD and POSIX extensions if not available on your system.

libirccd-event(3)

Information about an IRC event received.

libirccd-hook(3)

Create new hooks.

libirccd-irccd(3)

General functions to manipulate the running daemon.

libirccd-log(3)

Functions for logging messages through the configured logger adapter.

libirccd-plugin(3)

Create new plugins.

libirccd-rule(3)

Create or match rules.

libirccd-subst(3)

The substitution mechanism to create user plugin templates.

libirccd-util(3)

Various utilities.

SEE ALSO

irccd-cmake(7), libirccd-channel(3), libirccd-compat(3), libirccd-event(3), libirccd-hook(3), libirccd-irccd(3), libirccd-log(3), libirccd-plugin(3), libirccd-rule(3), libirccd-server(3), libirccd-util(3)

AUTHORS

The irccd daemon was written by David Demelier <markand@malikania.fr>.

macOS 13.5 - February 3, 2022