1CCZE-PLUGIN(7) CCZE CCZE-PLUGIN(7)
2
6 ccze - A robust log colorizer, plugin infrastructure
7
9 #include <ccze.h>
10 /* Plugin support */
12 typedef void (*ccze_plugin_startup_t) (void);
13 typedef void (*ccze_plugin_shutdown_t) (void);
14 typedef int (*ccze_plugin_handle_t) (const char *str, size_t length,
15 char **rest);
16 CCZE_DEFINE_PLUGIN (name, type, desc);
18 CCZE_DEFINE_PLUGINS (plugins...);
19 /* Display */
21 void ccze_addstr (ccze_color_t col, const char *str);
22 void ccze_newline (void);
23 void ccze_space (void);
24 void ccze_wordcolor_process_one (char *word, int slookup);
25 /* Helpers */
27 ccze_color_t ccze_http_action (const char *method);
28 void ccze_print_date (const char *date);
29 /* Command line */
31 char **ccze_plugin_argv_get (const char *name);
32 const char *ccze_plugin_name_get (void);
33
35 This manual page attempts to outline the internals of CCZE plugins:
36 how they work, how they are implemented, and how to add new ones.
37 There are four required entry points in a plugin: a startup, a shutdown
39 and a handler routine (more on these later), and an informational
40 structure.
41 The startup function must be of type ccze_plugin_startup_t. This is
43 called right after the module is loaded. Its purpose is to initialise
44 all kinds of module-specific global variables, such as the regular
45 expressions.
46 The shutdown function is its counterpart: this is used to deallocate
48 any memory reserved by the startup code.
49 The core part of a plugin is the handler, of type ccze_plugin_handle_t.
51 This does the actual coloring. The string to process is passed in the
52 str argument, its length in length. The third argument, rest is a
53 pointer to a string. Unlike the first two, this argument is used only
54 for output.
55 When a handler processed a string, it must return a non-zero value, in
57 case it could not process it, the handler must return with zero. If
58 the string could be processed only partially, the part which was deemed
59 unknown by the handler must be passed back in the rest variable.
60 The fourth part, although the smallest part, is the most important.
62 Without this, the module is useless, it cannot be loaded. This part
63 tells CCZE what the startup, shutdown and handler functions are called.
64 To encourage good style, the little details of this structure will not
66 be disclosed in this manual page. Instead, the helper macro,
67 CCZE_DEFINE_PLUGIN will be explained.
68 CCZE_DEFINE_PLUGIN is the macro to use if one wants to make the plugin
70 loadable. Its first argument is an unquoted string: the name of the
71 plugin. The second part is the type of the plugin, it can be FULL,
72 PARTIAL or ANY. The last argument is a short description of the plugin.
73 It is assumed that the three functions mentioned earlier are called
75 ccze_name_setup, ccze_name_shutdown and ccze_name_handle, respectively.
76 A FULL plugin is one that accepts raw input, untouched by any other
78 plugin before, and processes it. On the other hand, a PARTIAL plugin
79 relies on previous ones preprocessing the input. For example, syslog
80 is a full plugin, on which ulogd, a partial plugin relies. The syslog
81 plugin processes the raw input from the logfile, adds colour to most of
82 it, save the actual message sent by a process, that is left to subse‐
83 quent plugins, like ulogd. An ANY plugin is one can act as both other
84 types.
85 With CCZE_DEFINE_PLUGINS one can place more than one plugin into one
87 shared object.
88 There are two other helper functions, ccze_plugin_argv_get and
90 ccze_plugin_name_get. One can pass arguments to CCZE plugins, and these
91 is the function to retrieve them. While ccze_plugin_name_get returns
92 the name of the current plugin, ccze_plugin_argv_get returns a
93 NULL-terminated array, with each entry containing an argument.
94
96 The so-called display methods are the only supported interface to emit
97 something to the display. These handle both the normal, ncurses-based,
98 and the HTML output. This is a kind of abstraction so plugins will not
99 have to worry about the differences between the output formats.
100 The most important one is ccze_addstr, which takes a color (see ccze.h
102 for a list of supported color tags) and a string, and displays it
103 appropriately. The ccze_space and ccze_newline functions emit a space
104 and a newline, respectively.
105 Our last function, ccze_wordcolor_process_one passes word to the word
107 colourising engine. If the second argument, slookup is non-zero, the
108 engine will perform service lookups (like getent and friends).
109
111 We only have two helper methods: ccze_print_date, which simply prints
112 out the date in the appropriate colour, and ccze_http_action, which
113 given a HTTP method, returns the associated colour, in a format suit‐
114 able for ccze_addstr.
115
117 #include <ccze.h>
118 #include <stddef.h>
119 #include <string.h>
120 static char **ccze_foo_argv;
122 static int
124 ccze_foo_handle (const char *str, size_t length, char **rest)
125 {
126 int i = 1;
127 if (strstr (str, "foo"))
129 {
130 ccze_addstr (CCZE_COLOR_GOODWORD, str);
131 return 1;
132 }
133 while (ccze_foo_argv[i])
135 {
136 if (strstr (str, ccze_foo_argv[i]))
137 {
138 ccze_addstr (CCZE_COLOR_GOODWORD, str);
139 return 1;
140 }
141 i++;
142 }
143 return 0;
144 }
145 static void
147 ccze_foo_startup (void)
148 {
149 ccze_foo_argv = ccze_plugin_argv_get (ccze_plugin_name_get ());
150 }
151 static void
153 ccze_foo_shutdown (void)
154 {
155 }
156 CCZE_DEFINE_PLUGIN (foo, PARTIAL, "Partial FOO coloriser.");
158
160 ccze(1)
161
163 ccze was written by Gergely Nagy <algernon@bonehunter.rulez.org>, based
164 on colorize by Istvan Karaszi <colorize@spam.raszi.hu>.
165CCZE 0.2.1 2003-03-29 CCZE-PLUGIN(7)