CCZE-PLUGIN(7)

🌸 NAME 🌸

okay so bestie, this is CCZE-PLUGIN(7) — the manual page for ccze, aka a robust log colorizer, and specifically for its plugin infrastructure 💅. Like, the whole backstage situation that makes the pretty colors happen.

---

✨ SYNOPSIS ✨

#include <ccze.h>

/* Plugin support */
typedef void (*ccze_plugin_startup_t) (void);
typedef void (*ccze_plugin_shutdown_t) (void);
typedef int (*ccze_plugin_handle_t) (const char *str, size_t length,
char **rest);

CCZE_DEFINE_PLUGIN (name, type, desc);
CCZE_DEFINE_PLUGINS (plugins...);

/* Display */
void ccze_addstr (ccze_color_t col, const char *str);
void ccze_newline (void);
void ccze_space (void);
void ccze_wordcolor_process_one (char *word, int slookup);

/* Helpers */
ccze_color_t ccze_http_action (const char *method);
void ccze_print_date (const char *date);

/* Command line */
char **ccze_plugin_argv_get (const char *name);
const char *ccze_plugin_name_get (void);

---

🫶 DESCRIPTION 🫶

This page is literally here to spill the internals of CCZE plugins: how they work, how they're implemented, and how you'd go about adding new ones. no gatekeeping, periodt 💖

There are four required entry points in a plugin: a startup, a shutdown, a handler routine (more on these in a sec, bestie), and an informational structure.

The startup function must be of type ccze_plugin_startup_t. It gets called right after the module is loaded. Its whole job is to initialise all the module-specific global variables — stuff like the regular expressions 👑

The shutdown function is its counterpart: this is where you deallocate any memory the startup code reserved. so like, cleanup era 🧹

The core part of a plugin is the handler, of type ccze_plugin_handle_t. This one does the actual coloring. The string to process comes in through the str argument, its length in length. The third argument, rest, is a pointer to a string. Unlike the first two, this argument is used only for output.

When a handler processed a string, it must return a non-zero value. In case it could not process it, the handler must return with zero. And if the string could be processed only partially, the part which was deemed unknown by the handler must be passed back in the rest variable. iykyk 😌

The fourth part — even though it's the smallest part — is the most important one. Without this, the module is useless, it cannot be loaded. full stop. This part tells CCZE what the startup, shutdown and handler functions are called.

To encourage good style, the little details of this structure will not be disclosed in this manual page. Instead, the helper macro CCZE_DEFINE_PLUGIN gets explained. slay, mystery ✨

CCZE_DEFINE_PLUGIN is the macro you use if you want to make the plugin loadable. Its first argument is an unquoted string: the name of the plugin. The second part is the type of the plugin, and it can be FULL, PARTIAL or ANY. The last argument is a short description of the plugin.

It is assumed that the three functions mentioned earlier are called ccze_name_setup, ccze_name_shutdown and ccze_name_handle, respectively.

So let's talk types, because the vibes differ:

• A FULL plugin is one that accepts raw input, untouched by any other plugin before, and processes it.
• A PARTIAL plugin relies on previous ones preprocessing the input.
• An ANY plugin is one that can act as both other types.

For example, syslog is a full plugin, on which ulogd, a partial plugin, relies. The syslog plugin processes the raw input from the logfile, adds colour to most of it, save the actual message sent by a process — that part is left to subsequent plugins, like ulogd 💫

With CCZE_DEFINE_PLUGINS one can place more than one plugin into one shared object. efficient 💅

There are two other helper functions, ccze_plugin_argv_get and ccze_plugin_name_get. One can pass arguments to CCZE plugins, and these are the functions to retrieve them. While ccze_plugin_name_get returns the name of the current plugin, ccze_plugin_argv_get returns a NULL-terminated array, with each entry containing an argument. cute, organized, obsessed 🎀

---

🌈 DISPLAY METHODS 🌈

The so-called display methods are the only supported interface to emit something to the display. These handle both the normal, ncurses-based, and the HTML output. It's a kind of abstraction so plugins will not have to worry about the differences between the output formats. literally the whole point, bestie 🦋

The most important one is ccze_addstr, which takes a color (see ccze.h for a list of supported color tags) and a string, and displays it appropriately. The ccze_space and ccze_newline functions emit a space and a newline, respectively. tiny but mighty 🌸

Our last function, ccze_wordcolor_process_one passes word to the word colourising engine. If the second argument, slookup is non-zero, the engine will perform service lookups (like getent and friends). 👀

---

💜 HELPER METHODS 💜

We only have two helper methods, and honestly? they're both doing the most:

• ccze_print_date — which simply prints out the date in the appropriate colour.
• ccze_http_action — which, given a HTTP method, returns the associated colour, in a format suitable for ccze_addstr.

---

⭐ EXAMPLE ⭐

here's the whole thing in action, copy it, love it, make it yours:

#include <ccze.h>
#include <stddef.h>
#include <string.h>

static char **ccze_foo_argv;

static int
ccze_foo_handle (const char *str, size_t length, char **rest)
{
  int i = 1;

  if (strstr (str, "foo"))
    {
      ccze_addstr (CCZE_COLOR_GOODWORD, str);
      return 1;
    }

  while (ccze_foo_argv[i])
    {
      if (strstr (str, ccze_foo_argv[i]))
        {
          ccze_addstr (CCZE_COLOR_GOODWORD, str);
          return 1;
        }
      i++;
    }
  return 0;
}

static void
ccze_foo_startup (void)
{
  ccze_foo_argv = ccze_plugin_argv_get (ccze_plugin_name_get ());
}

static void
ccze_foo_shutdown (void)
{
}

CCZE_DEFINE_PLUGIN (foo, PARTIAL, "Partial FOO coloriser.");

---

🦋 SEE ALSO 🦋

• ccze(1)

---

👑 AUTHOR 👑

ccze was written by Gergely Nagy <algernon@bonehunter.rulez.org>, based on colorize by Istvan Karaszi <colorize@spam.raszi.hu>. legends only, no cap 🫶

---

and that's the whole page, bestie 💖 this was CCZE version 0.2.1, dated 2003-03-29, manual page CCZE-PLUGIN(7) — go forth and colorize the logs, main character energy only 🌈✨🎀