Quick ?s
Cheat Sheets
Man Pages
The Lynx
Software
CCZE-PLUGIN(7)			     CCZE			CCZE-PLUGIN(7)



NAME
       ccze - A robust log colorizer, plugin infrastructure

SYNOPSIS
       #include 

       /* 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	variables, 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 partially, 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 processes it.  On the other hand, a  PARTIAL	plugin
       relies  on  previous ones preprocessing the input.  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	subse
       quent  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 display. These handle both the normal,	ncurses-based,
       and  the HTML output. This is a kind of abstraction 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  supported  color  tags) and a string, and displays it
       appropriately. The ccze_space and ccze_newline 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 appropriate	colour,  and  ccze_http_action,  which
       given  a  HTTP method, returns the associated colour, in a format suit
       able for ccze_addstr.

EXAMPLE
       #include 
       #include 
       #include 

       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 , based
       on colorize by Istvan Karaszi .



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




Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:31 2009