Changed #ifdefs from headers to if defined().
[silc.git] / lib / silcutil / silclog.h
1 /*
2
3   silclog.h
4
5   Author: Johnny Mnemonic <johnny@themnemonic.org>
6
7   Copyright (C) 1997 - 2002 Pekka Riikonen
8
9   This program is free software; you can redistribute it and/or modify
10   it under the terms of the GNU General Public License as published by
11   the Free Software Foundation; either version 2 of the License, or
12   (at your option) any later version.
13
14   This program is distributed in the hope that it will be useful,
15   but WITHOUT ANY WARRANTY; without even the implied warranty of
16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17   GNU General Public License for more details.
18
19 */
20
21 /****h* silcutil/SILC Logging Interface
22  *
23  * DESCRIPTION
24  *
25  * The SILC logging APIs provide a powerful and easy-to-use interface to
26  * the logging system and debugging output.
27  *
28  ***/
29
30 #ifndef SILCLOG_H
31 #define SILCLOG_H
32
33 /****d* silcutil/SilcLogAPI/SilcLogType
34  *
35  * NAME
36  *
37  *    typedef enum { ... } SilcLogType;
38  *
39  * DESCRIPTION
40  *
41  *    This is the main logging channel id. There are currently four known
42  *    logging channels (plus the debugging output channel), and they are
43  *    ordered by importance.
44  *    See the source code for SILC coding conventions about how to choose
45  *    the right output channel.
46  *
47  * SOURCE
48  */
49 typedef enum {
50   /* Generic info channel file */
51   SILC_LOG_INFO,
52
53   /* This should be used for warnings and non critical failures */
54   SILC_LOG_WARNING,
55
56   /* Generic error and critical failure messages */
57   SILC_LOG_ERROR,
58
59   /* Fatal messages (usually situations that will lead to a program crash */
60   SILC_LOG_FATAL,
61
62   /* Total number logging channels */
63   SILC_LOG_MAX
64 } SilcLogType;
65 /***/
66
67 /****f* silcutil/SilcLogAPI/SilcLogCb
68  *
69  * SYNOPSIS
70  *
71  *    typedef bool (*SilcLogCb)(SilcLogType type, char *message,
72  *                              void *context);
73  *
74  * DESCRIPTION
75  *
76  *    The logging custom callback function.  The `type' is the channel ID
77  *    that triggered the event, which allows you to use the same callback
78  *    function for multiple logging channels.
79  *    The `message' parameter points to a null-terminated buffer containing
80  *    the received message, while `context' is the caller-specified context.
81  *    The message must not be modified or freed by the callback function.
82  *
83  * SEE ALSO
84  *    silc_log_set_callback
85  *
86  ***/
87 typedef bool (*SilcLogCb)(SilcLogType type, char *message, void *context);
88
89 /****f* silcutil/SilcLogAPI/SilcLogDebugCb
90  *
91  * SYNOPSIS
92  *
93  *    typedef bool (*SilcLogDebugCb)(char *file, char *function, int line,
94  *                                   char *message, void *context);
95  *
96  * DESCRIPTION
97  *
98  *    The debug logging callback function.  The default behaviour is to
99  *    output messages to stderr.  `file', `function', and `line' are the
100  *    corresponding offsets in the source files.  `message' points to a
101  *    null-terminated buffer containing the debugging message, and `context'
102  *    is the caller-specified context.
103  *    The message must not be modified or freed by the callback function.
104  *    If the function returns TRUE, SilcLog will assume the message as handled
105  *    and won't run its default handler.
106  *
107  * SEE ALSO
108  *    silc_debug, silc_log_set_debug_callbacks
109  *
110  ***/
111 typedef bool (*SilcLogDebugCb)(char *file, char *function, int line,
112                                char *message, void *context);
113
114 /****f* silcutil/SilcLogAPI/SilcLogHexdumpCb
115  *
116  * SYNOPSIS
117  *
118  *    typedef bool (*SilcDebugHexdumpCb)(char *file, char *function, int line,
119  *                                       unsigned char *data, SilcUInt32 data_len,
120  *                                       char *message, void *context;
121  *
122  * DESCRIPTION
123  *
124  *    The hexdump logging callback function.  The default behaviour is to
125  *    print a formatted hexdump to stderr, and is commonly what you would
126  *    like it to be.  `file', `function', and `line' are the corresponding
127  *    offsets in the source files.  `data' is the begin of the buffer that
128  *    should be hexdumped, which is `data_len' bytes long.
129  *    The `message' parameter points to a null-terminated buffer containing
130  *    the received message, while `context' is the caller-specified context.
131  *    The message must not be modified or freed by the callback function.
132  *    If the function returns TRUE, SilcLog will assume the message as handled
133  *    and won't run its default handler.
134  *
135  * SEE ALSO
136  *    silc_debug_hexdump, silc_log_set_debug_callbacks
137  *
138  ***/
139 typedef bool (*SilcLogHexdumpCb)(char *file, char *function, int line,
140                                  unsigned char *data, SilcUInt32 data_len,
141                                  char *message, void *context);
142
143 /* Global Variables */
144
145 /****v* silcutil/SilcLogAPI/silc_log_timestamp
146  *
147  * NAME
148  *
149  *    bool silc_log_timestamp -- enable/disable fast logging timestamp
150  *
151  * DESCRIPTION
152  *
153  *    Causes SilcLog to add a timestamp as returned by silc_get_time().
154  *    This may be useful for example if you run your application under a
155  *    daemon helper like watchdog that adds its own timestamp.  Defaults to
156  *    true.
157  *
158  ***/
159 extern DLLAPI bool silc_log_timestamp;
160
161 /****v* silcutil/SilcLogAPI/silc_log_quick
162  *
163  * NAME
164  *
165  *    bool silc_log_quick -- enable/disable fast logging output
166  *
167  * DESCRIPTION
168  *
169  *    SilcLog makes use of libc stream buffering output, which means that it
170  *    saves HD activity by buffering the logging messages and writing them
171  *    all together every some minutes (default is 5 minutes).
172  *    Setting this variable to TRUE will force SilcLog to write messages to the
173  *    filesystem as soon as they are received. This increases the CPU activity
174  *    notably on bigger servers, but reduces memory usage.
175  *    If you want to change the logging style on-the-fly, make sure to call
176  *    silc_log_flush_all() after setting this variable to TRUE.
177  *
178  ***/
179 extern DLLAPI bool silc_log_quick;
180
181 /****v* silcutil/SilcLogAPI/silc_log_flushdelay
182  *
183  * NAME
184  *
185  *    long silc_log_flushdelay -- flushing time delay
186  *
187  * DESCRIPTION
188  *
189  *    Sets the logfiles flushing delay in seconds.  As for now, changing this
190  *    value AFTER logfiles initialization won't take effect until previous
191  *    delay time will expire; for example if you change from 300 seconds to
192  *    60 seconds you will have to wait up to 300 seconds for this change to
193  *    take effect.
194  *    This value must be greater than 2 seconds.
195  *
196  ***/
197 extern DLLAPI long silc_log_flushdelay;
198
199 /****v* silcutil/SilcLogAPI/silc_debug
200  *
201  * NAME
202  *
203  *    bool silc_debug -- enable/disable debugging output
204  *
205  * DESCRIPTION
206  *
207  *    If silc_debug is set to FALSE, debugging functions won't procude any
208  *    output.  This is useful when for example you compile in the debugging
209  *    support but at a certain point you want to send the program in the
210  *    background.
211  *
212  * SEE ALSO
213  *    SILC_LOG_DEBUG
214  *
215  ***/
216 extern DLLAPI bool silc_debug;
217
218 /****v* silcutil/SilcLogAPI/silc_debug_hexdump
219  *
220  * NAME
221  *
222  *    bool silc_debug_hexdump -- enable/disable debugging output
223  *
224  * DESCRIPTION
225  *
226  *    If silc_debug_hexdump is set to FALSE, debugging functions won't produce
227  *    any output.  This is useful when for example you compile in the debugging
228  *    support but at a certain point you want to send the program in the
229  *    background.
230  *
231  * SEE ALSO
232  *    SILC_LOG_HEXDUMP
233  *
234  ***/
235 extern DLLAPI bool silc_debug_hexdump;
236
237 /* Macros */
238
239 #if defined(SILC_WIN32)
240 #ifndef __FUNCTION__
241 #define __FUNCTION__ ""
242 #endif
243 #endif
244
245 /****d* silcutil/SilcLogAPI/SILC_LOG_INFO
246  *
247  * NAME
248  *
249  *    #define SILC_LOG_INFO(...)
250  *
251  * DESCRIPTION
252  *
253  *    This macro is a wrapper to the main logging function.
254  *    It supports variable argument list formatting, and *automatically*
255  *    appends newline at the end of the string.
256  *
257  * NOTES
258  *
259  *    This macro requires double parenthesis to ensure that the VA list
260  *    formatting would work correctly.
261  *
262  * EXAMPLE
263  *
264  *    SILC_LOG_INFO(("Today i feel %s", core->mood));
265  *
266  * SOURCE
267  */
268 #define SILC_LOG_INFO(fmt) silc_log_output(SILC_LOG_INFO, silc_format fmt)
269 /***/
270
271 /****d* silcutil/SilcLogAPI/SILC_LOG_WARNING
272  *
273  * NAME
274  *
275  *    #define SILC_LOG_WARNING(...)
276  *
277  * DESCRIPTION
278  *
279  *    Wrapper to the WARNING logging channel.
280  *    Please see the SILC_LOG_INFO macro.
281  *
282  * SEE ALSO
283  *    SILC_LOG_INFO
284  *
285  * SOURCE
286  */
287 #define SILC_LOG_WARNING(fmt) silc_log_output(SILC_LOG_WARNING, silc_format fmt)
288 /***/
289
290 /****d* silcutil/SilcLogAPI/SILC_LOG_ERROR
291  *
292  * NAME
293  *
294  *    #define SILC_LOG_ERROR(...)
295  *
296  * DESCRIPTION
297  *
298  *    Wrapper to the ERROR logging channel.
299  *    Please see the SILC_LOG_INFO macro.
300  *
301  * SEE ALSO
302  *    SILC_LOG_INFO
303  *
304  * SOURCE
305  */
306 #define SILC_LOG_ERROR(fmt) silc_log_output(SILC_LOG_ERROR, silc_format fmt)
307 /***/
308
309 /****d* silcutil/SilcLogAPI/SILC_LOG_FATAL
310  *
311  * NAME
312  *
313  *    #define SILC_LOG_FATAL(...)
314  *
315  * DESCRIPTION
316  *
317  *    Wrapper to the FATAL logging channel.
318  *    Please see the SILC_LOG_INFO macro.
319  *
320  * SEE ALSO
321  *    SILC_LOG_INFO
322  *
323  * SOURCE
324  */
325 #define SILC_LOG_FATAL(fmt) silc_log_output(SILC_LOG_FATAL, silc_format fmt)
326 /***/
327
328 /****d* silcutil/SilcLogAPI/SILC_LOG_DEBUG
329  *
330  * NAME
331  *
332  *    #define SILC_LOG_DEBUG(...)
333  *
334  * DESCRIPTION
335  *
336  *    This is a special wrapper to the debugging output (usually stderr).
337  *    The standard behaviour is the same as SILC_LOG_INFO, with the difference
338  *    that this macro also depends on the global define SILC_DEBUG.
339  *    Undefining SILC_DEBUG causes these functions to be defined to an empty
340  *    value, thus removing all debug logging calls from the compiled
341  *    application.
342  *    This macro is also affected by the global variable silc_debug.
343  *
344  * SOURCE
345  */
346 #if defined(SILC_DEBUG)
347 #define SILC_LOG_DEBUG(fmt) silc_log_output_debug(__FILE__, \
348                                 __FUNCTION__, \
349                                 __LINE__, \
350                                 silc_format fmt)
351 #define SILC_NOT_IMPLEMENTED(string) \
352   SILC_LOG_INFO(("*********** %s: NOT IMPLEMENTED YET", string));
353 #else
354 #define SILC_LOG_DEBUG(fmt)
355 #define SILC_NOT_IMPLEMENTED(string)
356 #endif  /* SILC_DEBUG */
357 /***/
358
359 /****d* silcutil/SilcLogAPI/SILC_LOG_HEXDUMP
360  *
361  * NAME
362  *
363  *    #define SILC_LOG_HEXDUMP(...)
364  *
365  * DESCRIPTION
366  *
367  *    This is a special wrapper to the hexdump output function.  This macro
368  *    behaves slightly differently from other logging wrappers.
369  *    The first parameter, is composed by a group of parameters delimited by
370  *    parenthesis.
371  *    The second parameter is a `char *' pointer pointing to the beginning
372  *    of the memory section that should be hexdumped, and the third parameter
373  *    is the length of this memory section.
374  *    Undefining the global SILC_DEBUG define causes these functions to be
375  *    defined to an empty value, thus removing all debug logging calls from
376  *    the compiled application.
377  *    This macro is also affected by the global variable silc_debug_hexdump.
378  *
379  * EXAMPLE
380  *
381  *    SILC_LOG_HEXDUMP(("Outgoing packet [%d], len %d", pckt->seq, pckt->len),
382  *                     pckt->data, pckt->datalen);
383  *
384  * SOURCE
385  */
386 #if defined(SILC_DEBUG)
387 #define SILC_LOG_HEXDUMP(fmt, data, len) silc_log_output_hexdump(__FILE__, \
388                                 __FUNCTION__, \
389                                 __LINE__, \
390                                 (data), (len), \
391                                 silc_format fmt)
392 #else
393 #define SILC_LOG_HEXDUMP(fmt, data, len)
394 #endif  /* SILC_DEBUG */
395 /***/
396
397 /* Prototypes */
398
399 /****f* silcutil/SilcLogAPI/silc_log_output
400  *
401  * SYNOPSIS
402  *
403  *    void silc_log_output(SilcLogType type, char *string);
404  *
405  * DESCRIPTION
406  *
407  *    This is the main function for logging output. Please note that you
408  *    should rather use one of the logging wrapper macros.
409  *    If you really want to use this function, its usage is quite simple.
410  *    The `type' parameter identifies the channel to use, while the `string'
411  *    parameter must be a dynamic allocated (null-terminated) buffer, because
412  *    it will be freed at the end of this function, for internal reasons.
413  *    If there are registered callbacks for the specified type, this function
414  *    will first trigger those callbacks.  The callback functions must NOT
415  *    free or modify the original buffer.
416  *
417  * SEE ALSO
418  *    SILC_LOG_INFO, SILC_LOG_WARNING, SILC_LOG_ERROR, SILC_LOG_FATAL
419  *
420  ***/
421 void silc_log_output(SilcLogType type, char *string);
422
423 /****f* silcutil/SilcLogAPI/silc_log_get_file
424  *
425  * SYNOPSIS
426  *
427  *    char *silc_log_get_file(SilcLogType type);
428  *
429  * DESCRIPTION
430  *
431  *    Returns the current logging file for the channel `type'.
432  *    If there has been an error during the opening of this channel, NULL
433  *    is returned, even if the file has been previously set with
434  *    silc_log_set_file().
435  *    The returned pointer points to internally allocated storage and must
436  *    not be freed, modified or stored.
437  *
438  ***/
439 char *silc_log_get_file(SilcLogType type);
440
441 /****f* silcutil/SilcLogAPI/silc_log_set_file
442  *
443  * SYNOPSIS
444  *
445  *    bool silc_log_set_file(SilcLogType type, char *filename, 
446  *                           SilcUInt32 maxsize,
447  *                           SilcSchedule scheduler);
448  *
449  * DESCRIPTION
450  *
451  *    Sets `filename', which can be maximum `maxsize' bytes long, as the new
452  *    logging file for the channel `type'.  If you specify an illegal filename
453  *    a warning message is printed and FALSE is returned.  In this case
454  *    logging settings are not changed.
455  *    You can disable logging for a channel by specifying NULL filename, the
456  *    maxsize in this case is not important.
457  *    The `scheduler' parameter is needed by the internal logging to allow
458  *    buffered output and thus to save HD activity.
459  *
460  ***/
461 bool silc_log_set_file(SilcLogType type, char *filename, SilcUInt32 maxsize,
462                        SilcSchedule scheduler);
463
464 /****f* silcutil/SilcLogAPI/silc_log_set_callback
465  *
466  * SYNOPSIS
467  *
468  *    void silc_log_set_callback(SilcLogType type, SilcLogCb cb,
469  *                               void *context);
470  *
471  * DESCRIPTION
472  *
473  *    Set `cb' as the default callback function for the logging channel
474  *    `type'.  When SilcLog receives a message for this channel, it will
475  *    trigger the callback function.  If the callback function returns TRUE
476  *    SilcLog will assume the input as handled and won't run its default
477  *    handler.
478  *    You can disable/remove a callback by setting it to NULL or calling the
479  *    function silc_log_reset_callbacks.
480  *    If set, the callback function must be in the form described by
481  *    SilcLogCb.
482  *
483  * SEE ALSO
484  *    silc_log_reset_callbacks
485  *
486  ***/
487 void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context);
488
489 /****f* silcutil/SilcLogAPI/silc_log_reset_callbacks
490  *
491  * SYNOPSIS
492  *
493  *    void silc_log_reset_callbacks();
494  *
495  * DESCRIPTION
496  *
497  *    Removes all logging callbacks for normal channels.  This function does
498  *    NOT remove callbacks for debugging channels (debug and hexdump), you
499  *    rather need to call silc_log_set_debug_callbacks() with NULL callbacks.
500  *
501  ***/
502 void silc_log_reset_callbacks();
503
504 /****f* silcutil/SilcLogAPI/silc_log_flush_all
505  *
506  * SYNOPSIS
507  *
508  *    void silc_log_flush_all();
509  *
510  * DESCRIPTION
511  *
512  *    Forces flushing for all logging channels.  This should be called for
513  *    example after receiving special signals.
514  *
515  * SEE ALSO
516  *    silc_log_quick
517  *
518  ***/
519 void silc_log_flush_all();
520
521 /****f* silcutil/SilcLogAPI/silc_log_reset_all
522  *
523  * SYNOPSIS
524  *
525  *    void silc_log_reset_all();
526  *
527  * DESCRIPTION
528  *
529  *    Forces all logging channels to close and reopen their streams.  Useful
530  *    for example after a SIGHUP signal.
531  *    Please note that this function could generate some warning messages if
532  *    one or more logging channels point to an illegal filename.
533  *
534  ***/
535 void silc_log_reset_all();
536
537 /****f* silcutil/SilcLogAPI/silc_log_output_debug
538  *
539  * SYNOPSIS
540  *
541  *    void silc_log_output_debug(char *file, char *function,
542  *                               int line, char *string);
543  *
544  * DESCRIPTION
545  *
546  *    This is the main function for debug output.  Please note that you should
547  *    rather use the wrapper macro SILC_LOG_DEBUG.
548  *    If you want to use it anyway, the `file', `function', and `line' are the
549  *    corresponding offsets in the source files, while `string' must be a
550  *    dynamic allocated (null-terminated) buffer.
551  *
552  ***/
553 void silc_log_output_debug(char *file, char *function,
554                            int line, char *string);
555
556 /****f* silcutil/SilcLogAPI/silc_log_output_hexdump
557  *
558  * SYNOPSIS
559  *
560  *    void silc_log_output_hexdump(char *file, char *function,
561  *                                 int line, void *data_in,
562  *                                 SilcUInt32 len, char *string);
563  *
564  * DESCRIPTION
565  *
566  *    This is the main function for hexdump output.  Please note that you
567  *    should rather use the wrapper macro SILC_LOG_HEXDUMP.
568  *    If you want to use it anyway, the `file', `function', and `line' are the
569  *    corresponding offsets in the source files, `data_in' is the beginning
570  *    of the buffer you wish to hexdump, which is `len' bytes long.
571  *    `string' must be a dynamic allocated (null-terminated) buffer.
572  *
573  ***/
574 void silc_log_output_hexdump(char *file, char *function,
575                              int line, void *data_in,
576                              SilcUInt32 len, char *string);
577
578 /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks
579  *
580  * SYNOPSIS
581  *
582  *    void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
583  *                                      void *debug_context,
584  *                                      SilcLogHexdumpCb hexdump_cb,
585  *                                      void *hexdump_context);
586  *
587  * DESCRIPTION
588  *
589  *    Sets `debug_cb' as the the default callback function for the debug
590  *    output, that will be called with the `debug_context' parameter.
591  *    When SilcLog receives a debug message, it will trigger the callback
592  *    function.  If the callback function returns TRUE SilcLog will assume
593  *    the input as handled and won't run its default handler.
594  *    `hexdump_cb' and `hexdump_context' works the same way, except that they
595  *    are referred to SILC_LOG_HEXDUMP requests.
596  *    You can disable/remove a callback by setting it to NULL.
597  *    If set, each callback function must be either in the form described by
598  *    SilcLogDebugCb or SilcLogHexdumpCb.
599  *
600  * SEE ALSO
601  *    SilcLogDebugCb,  SilcLogHexdumpCb
602  *
603  ***/
604 void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
605                                   void *debug_context,
606                                   SilcLogHexdumpCb hexdump_cb,
607                                   void *hexdump_context);
608
609 /****f* silcutil/SilcLogAPI/silc_log_set_debug_string
610  *
611  * SYNOPSIS
612  *
613  *    void silc_log_set_debug_string(const char *debug_string);
614  *
615  * DESCRIPTION
616  *
617  *    Sets `debug_string' as the regexp string for filtering debugging
618  *    output.  The string is copied and it can be modified/destroyed after
619  *    this function call.
620  *
621  ***/
622 void silc_log_set_debug_string(const char *debug_string);
623
624 #endif  /* !SILCLOG_H */