phpman > man > ccze-plugin(7)

CCZE-PLUGIN(7)                                  CCZE                                  CCZE-PLUGIN(7)



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:  how they work, how they
       are implemented, and how to add new ones.

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

       The  startup  function  must be of type ccze_plugin_startup_t. This is called right after the
       module is loaded.  Its purpose is to initialise all kinds  of  module-specific  global  vari‐
       ables, such as the regular expressions.

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

       The core part of a plugin is the handler, of type ccze_plugin_handle_t.  This does the actual
       coloring.   The  string  to process is passed in 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.  If the string could be  processed  only  par‐
       tially,  the  part  which  was  deemed unknown by the handler must be passed back in the rest
       variable.

       The fourth part, although the smallest part, is the most important. Without this, the  module
       is useless, it cannot be loaded.  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 will be explained.

       CCZE_DEFINE_PLUGIN  is  the  macro to use if one wants 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,  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.

       A  FULL  plugin is one that accepts raw input, untouched by any other plugin before, and pro‐
       cesses it.  On the other hand, a PARTIAL plugin relies on previous ones preprocessing the in‐
       put.   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 is left to subsequent plugins, like ulogd. An ANY
       plugin is one can act as both other types.

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

       There are two other helper functions, ccze_plugin_argv_get and ccze_plugin_name_get. One  can
       pass  arguments  to  CCZE  plugins,  and  these  is  the  function  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.

DISPLAY METHODS
       The  so-called display methods are the only supported interface to emit something to the dis‐
       play. These handle both the normal, ncurses-based, and the HTML output. This is a kind of ab‐
       straction so plugins will not have to worry about the differences between the output formats.

       The  most  important  one  is ccze_addstr, which takes a color (see ccze.h for a list of sup‐
       ported color tags) and a string, and displays it appropriately. The ccze_space and  ccze_new‐
       line functions emit a space and a newline, respectively.

       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: ccze_print_date, which simply prints out the date in the ap‐
       propriate colour, and ccze_http_action, which given a HTTP  method,  returns  the  associated
       colour, in a format suitable for ccze_addstr.

EXAMPLE
       #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 AT bonehunter.org>, based on colorize by Istvan
       Karaszi <colorize AT spam.hu>.



CCZE 0.2.1                                   2003-03-29                               CCZE-PLUGIN(7)