Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 variables, such as the regular ex-
       pressions.

       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_DE-
       FINE_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  ap-
       propriately. 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	<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>.

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

NAME | SYNOPSIS | DESCRIPTION | DISPLAY METHODS | HELPER METHODS | EXAMPLE | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ccze-plugin&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help