MAN page from OpenSuSE ccze-0.2.1.2-9.3.x86_64.rpm

CCZE-PLUGIN

Section: CCZE (7)
Updated: 2003-03-29
Index

NAME

ccze - A robust log colorizer, plugin infrastructure

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 manual page attempts to outline the internals of CCZE plugins: howthey work, how they are implemented, and how to add new ones.

There are four required entry points in a plugin: a startup, ashutdown and a handler routine (more on these later), and aninformational structure.

The startup function must be of type ccze_plugin_startup_t. Thisis called right after the module is loaded. Its purpose is to initialiseall kinds of module-specific global variables, such as the regularexpressions.

The shutdown function is its counterpart: this is used to deallocateany memory reserved by the startup code.

The core part of a plugin is the handler, of typeccze_plugin_handle_t. This does the actual coloring. The string toprocess is passed in the str argument, its length in length.The third argument, rest is a pointer to a string. Unlike the firsttwo, this argument is used only for output.

When a handler processed a string, it must return a non-zero value, in caseit could not process it, the handler must return with zero. If the stringcould be processed only partially, the part which was deemed unknown by thehandler must be passed back in the rest variable.

The fourth part, although the smallest part, is the most important. Withoutthis, the module is useless, it cannot be loaded. This part tells CCZE whatthe startup, shutdown and handler functions are called.

To encourage good style, the little details of this structure will not bedisclosed in this manual page. Instead, the helper macro,CCZE_DEFINE_PLUGIN will be explained.

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

It is assumed that the three functions mentioned earlier are calledccze_name_setup, ccze_name_shutdown andccze_name_handle, respectively.

A FULL plugin is one that accepts raw input, untouched by any otherplugin before, and processes it. On the other hand, a PARTIAL pluginrelies on previous ones preprocessing the input. For example, syslogis a full plugin, on which ulogd, a partial plugin relies. Thesyslog plugin processes the raw input from the logfile, adds colour tomost of it, save the actual message sent by a process, that is left tosubsequent plugins, like ulogd. An ANY plugin is one can act asboth other types.

With CCZE_DEFINE_PLUGINS one can place more than one plugin into oneshared object.

There are two other helper functions, ccze_plugin_argv_get andccze_plugin_name_get. One can pass arguments to CCZE plugins, andthese is the function to retrieve them. While ccze_plugin_name_getreturns the name of the current plugin, ccze_plugin_argv_get returns aNULL-terminated array, with each entry containing an argument.

DISPLAY METHODS

The so-called display methods are the only supported interfaceto emit something to the display. These handle both the normal,ncurses-based, and the HTML output. This is a kind of abstraction soplugins will not have to worry about the differences between the outputformats.

The most important one is ccze_addstr, which takes a color (seeccze.h for a list of supported color tags) and a string, and displaysit appropriately. The ccze_space and ccze_newline functions emita space and a newline, respectively.

Our last function, ccze_wordcolor_process_one passes word to theword 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: ccze_print_date, which simply printsout the date in the appropriate colour, and ccze_http_action, whichgiven a HTTP method, returns the associated colour, in a formatsuitable for ccze_addstr.

EXAMPLE

#include <ccze.h>#include <stddef.h>#include <string.h>static char **ccze_foo_argv;static intccze_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 voidccze_foo_startup (void){  ccze_foo_argv = ccze_plugin_argv_get (ccze_plugin_name_get ());}static voidccze_foo_shutdown (void){}CCZE_DEFINE_PLUGIN (foo, PARTIAL, "Partial FOO coloriser.");

AUTHOR

ccze was written by Gergely Nagy <algernonAATTbonehunter.rulez.org>, based oncolorize by Istvan Karaszi <colorizeAATTspam.raszi.hu>.

This document was created byman2html,using the manual pages.