5 Author: Giovanni Giacobbi <giovanni@giacobbi.net>
7 Copyright (C) 1997 - 2005 Pekka Riikonen
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.
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.
21 /****h* silcutil/SILC Logging Interface
25 * The SILC logging APIs provide a powerful and easy-to-use interface to
26 * the logging system and debugging output.
33 /****d* silcutil/SilcLogAPI/SilcLogType
37 * typedef enum { ... } SilcLogType;
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.
45 * See the source code for SILC coding conventions about how to choose
46 * the right output channel.
51 /* Generic info channel file */
54 /* This should be used for warnings and non critical failures */
57 /* Generic error and critical failure messages */
60 /* Fatal messages (usually situations that will lead to a program crash */
63 /* Total number logging channels */
68 /****f* silcutil/SilcLogAPI/SilcLogCb
72 * typedef bool (*SilcLogCb)(SilcLogType type, char *message,
77 * The logging custom callback function. The `type' is the channel ID
78 * that triggered the event, which allows you to use the same callback
79 * function for multiple logging channels.
80 * The `message' parameter points to a null-terminated buffer containing
81 * the received message, while `context' is the caller-specified context.
82 * The message must not be modified or freed by the callback function.
85 * silc_log_set_callback
88 typedef bool (*SilcLogCb)(SilcLogType type, char *message, void *context);
90 /****f* silcutil/SilcLogAPI/SilcLogDebugCb
94 * typedef bool (*SilcLogDebugCb)(char *file, char *function, int line,
95 * char *message, void *context);
99 * The debug logging callback function. The default behaviour is to
100 * output messages to stderr. `file', `function', and `line' are the
101 * corresponding offsets in the source files. `message' points to a
102 * null-terminated buffer containing the debugging message, and `context'
103 * is the caller-specified context.
104 * The message must not be modified or freed by the callback function.
105 * If the function returns TRUE, SilcLog will assume the message as handled
106 * and won't run its default handler.
109 * silc_debug, silc_log_set_debug_callbacks
112 typedef bool (*SilcLogDebugCb)(char *file, char *function, int line,
113 char *message, void *context);
115 /****f* silcutil/SilcLogAPI/SilcLogHexdumpCb
119 * typedef bool (*SilcDebugHexdumpCb)(char *file, char *function, int line,
120 * unsigned char *data, SilcUInt32 data_len,
121 * char *message, void *context;
125 * The hexdump logging callback function. The default behaviour is to
126 * print a formatted hexdump to stderr, and is commonly what you would
127 * like it to be. `file', `function', and `line' are the corresponding
128 * offsets in the source files. `data' is the begin of the buffer that
129 * should be hexdumped, which is `data_len' bytes long.
130 * The `message' parameter points to a null-terminated buffer containing
131 * the received message, while `context' is the caller-specified context.
132 * The message must not be modified or freed by the callback function.
133 * If the function returns TRUE, SilcLog will assume the message as handled
134 * and won't run its default handler.
137 * silc_debug_hexdump, silc_log_set_debug_callbacks
140 typedef bool (*SilcLogHexdumpCb)(char *file, char *function, int line,
141 unsigned char *data, SilcUInt32 data_len,
142 char *message, void *context);
144 /* Global Variables */
146 /****v* silcutil/SilcLogAPI/silc_log_timestamp
150 * bool silc_log_timestamp -- enable/disable fast logging timestamp
154 * Causes SilcLog to add a timestamp as returned by silc_get_time().
155 * This may be useful for example if you run your application under a
156 * daemon helper like watchdog that adds its own timestamp. Defaults to
160 extern DLLAPI bool silc_log_timestamp;
162 /****v* silcutil/SilcLogAPI/silc_log_quick
166 * bool silc_log_quick -- enable/disable fast logging output
170 * SilcLog makes use of libc stream buffering output, which means that it
171 * saves HD activity by buffering the logging messages and writing them
172 * all together every some minutes (default is 5 minutes).
173 * Setting this variable to TRUE will force SilcLog to write messages to the
174 * filesystem as soon as they are received. This increases the CPU activity
175 * notably on bigger servers, but reduces memory usage.
176 * If you want to change the logging style on-the-fly, make sure to call
177 * silc_log_flush_all() after setting this variable to TRUE.
180 extern DLLAPI bool silc_log_quick;
182 /****v* silcutil/SilcLogAPI/silc_log_flushdelay
186 * long silc_log_flushdelay -- flushing time delay
190 * Sets the logfiles flushing delay in seconds. As for now, changing this
191 * value AFTER logfiles initialization won't take effect until previous
192 * delay time will expire; for example if you change from 300 seconds to
193 * 60 seconds you will have to wait up to 300 seconds for this change to
195 * This value must be greater than 2 seconds.
198 extern DLLAPI long silc_log_flushdelay;
200 /****v* silcutil/SilcLogAPI/silc_debug
204 * bool silc_debug -- enable/disable debugging output
208 * If silc_debug is set to FALSE, debugging functions won't procude any
209 * output. This is useful when for example you compile in the debugging
210 * support but at a certain point you want to send the program in the
217 extern DLLAPI bool silc_debug;
219 /****v* silcutil/SilcLogAPI/silc_debug_hexdump
223 * bool silc_debug_hexdump -- enable/disable debugging output
227 * If silc_debug_hexdump is set to FALSE, debugging functions won't produce
228 * any output. This is useful when for example you compile in the debugging
229 * support but at a certain point you want to send the program in the
236 extern DLLAPI bool silc_debug_hexdump;
242 #define __FUNCTION__ ""
246 /****d* silcutil/SilcLogAPI/SILC_ENABLE_DEBUG
250 * #define SILC_ENABLE_DEBUG
254 * Use this macro to enable the debugging in your application. If
255 * SILC was compiled with debugging enabled, this macro enables it.
256 * Use this macro in your application's main header, or in place where
257 * you need to enable the debugging.
261 * You still can control the debugging with silc_debug variable, on
262 * whether to actually print the debugging or not. This macro is
263 * used to enable debugging, not to say it is printed or not.
267 #define SILC_ENABLE_DEBUG \
269 #define SILC_DEBUG 1 \
273 /****d* silcutil/SilcLogAPI/SILC_LOG_INFO
277 * #define SILC_LOG_INFO(...)
281 * This macro is a wrapper to the main logging function.
282 * It supports variable argument list formatting, and *automatically*
283 * appends newline at the end of the string.
287 * This macro requires double parenthesis to ensure that the VA list
288 * formatting would work correctly.
292 * SILC_LOG_INFO(("Today i feel %s", core->mood));
296 #define SILC_LOG_INFO(fmt) silc_log_output(SILC_LOG_INFO, silc_format fmt)
299 /****d* silcutil/SilcLogAPI/SILC_LOG_WARNING
303 * #define SILC_LOG_WARNING(...)
307 * Wrapper to the WARNING logging channel.
308 * Please see the SILC_LOG_INFO macro.
315 #define SILC_LOG_WARNING(fmt) silc_log_output(SILC_LOG_WARNING, silc_format fmt)
318 /****d* silcutil/SilcLogAPI/SILC_LOG_ERROR
322 * #define SILC_LOG_ERROR(...)
326 * Wrapper to the ERROR logging channel.
327 * Please see the SILC_LOG_INFO macro.
334 #define SILC_LOG_ERROR(fmt) silc_log_output(SILC_LOG_ERROR, silc_format fmt)
337 /****d* silcutil/SilcLogAPI/SILC_LOG_FATAL
341 * #define SILC_LOG_FATAL(...)
345 * Wrapper to the FATAL logging channel.
346 * Please see the SILC_LOG_INFO macro.
353 #define SILC_LOG_FATAL(fmt) silc_log_output(SILC_LOG_FATAL, silc_format fmt)
356 /****d* silcutil/SilcLogAPI/SILC_LOG_DEBUG
360 * #define SILC_LOG_DEBUG(...)
364 * This is a special wrapper to the debugging output (usually stderr).
365 * The standard behaviour is the same as SILC_LOG_INFO, with the difference
366 * that this macro also depends on the global define SILC_DEBUG.
367 * Undefining SILC_DEBUG causes these functions to be defined to an empty
368 * value, thus removing all debug logging calls from the compiled
370 * This macro is also affected by the global variable silc_debug.
374 #if defined(SILC_DEBUG)
375 #define SILC_LOG_DEBUG(fmt) silc_log_output_debug(__FILE__, \
379 #define SILC_NOT_IMPLEMENTED(string) \
380 SILC_LOG_INFO(("*********** %s: NOT IMPLEMENTED YET", string));
382 #define SILC_LOG_DEBUG(fmt) do { } while(0)
383 #define SILC_NOT_IMPLEMENTED(string) do { } while(0)
384 #endif /* SILC_DEBUG */
387 /****d* silcutil/SilcLogAPI/SILC_LOG_HEXDUMP
391 * #define SILC_LOG_HEXDUMP(...)
395 * This is a special wrapper to the hexdump output function. This macro
396 * behaves slightly differently from other logging wrappers.
397 * The first parameter, is composed by a group of parameters delimited by
399 * The second parameter is a `char *' pointer pointing to the beginning
400 * of the memory section that should be hexdumped, and the third parameter
401 * is the length of this memory section.
402 * Undefining the global SILC_DEBUG define causes these functions to be
403 * defined to an empty value, thus removing all debug logging calls from
404 * the compiled application.
405 * This macro is also affected by the global variable silc_debug_hexdump.
409 * SILC_LOG_HEXDUMP(("Outgoing packet [%d], len %d", pckt->seq, pckt->len),
410 * pckt->data, pckt->datalen);
414 #if defined(SILC_DEBUG)
415 #define SILC_LOG_HEXDUMP(fmt, data, len) silc_log_output_hexdump(__FILE__, \
418 (void *)(data), (len), \
421 #define SILC_LOG_HEXDUMP(fmt, data, len) do { } while(0)
422 #endif /* SILC_DEBUG */
427 /****f* silcutil/SilcLogAPI/silc_log_output
431 * void silc_log_output(SilcLogType type, char *string);
435 * This is the main function for logging output. Please note that you
436 * should rather use one of the logging wrapper macros.
438 * If you really want to use this function, its usage is quite simple.
439 * The `type' parameter identifies the channel to use, while the `string'
440 * parameter must be a dynamic allocated (null-terminated) buffer, because
441 * it will be freed at the end of this function, for internal reasons.
442 * If there are registered callbacks for the specified type, this function
443 * will first trigger those callbacks. The callback functions must NOT
444 * free or modify the original buffer.
447 * SILC_LOG_INFO, SILC_LOG_WARNING, SILC_LOG_ERROR, SILC_LOG_FATAL
450 void silc_log_output(SilcLogType type, char *string);
452 /****f* silcutil/SilcLogAPI/silc_log_get_file
456 * char *silc_log_get_file(SilcLogType type);
460 * Returns the current logging file for the channel `type'.
461 * If there has been an error during the opening of this channel, NULL
462 * is returned, even if the file has been previously set with
463 * silc_log_set_file().
465 * The returned pointer points to internally allocated storage and must
466 * not be freed, modified or stored.
469 char *silc_log_get_file(SilcLogType type);
471 /****f* silcutil/SilcLogAPI/silc_log_set_file
475 * bool silc_log_set_file(SilcLogType type, char *filename,
476 * SilcUInt32 maxsize,
477 * SilcSchedule scheduler);
481 * Sets `filename', which can be maximum `maxsize' bytes long, as the new
482 * logging file for the channel `type'. If you specify an illegal filename
483 * a warning message is printed and FALSE is returned. In this case
484 * logging settings are not changed.
486 * You can disable logging for a channel by specifying NULL filename, the
487 * maxsize in this case is not important. The `scheduler' parameter is
488 * needed by the internal logging to allow buffered output and thus to
492 bool silc_log_set_file(SilcLogType type, char *filename, SilcUInt32 maxsize,
493 SilcSchedule scheduler);
495 /****f* silcutil/SilcLogAPI/silc_log_set_callback
499 * void silc_log_set_callback(SilcLogType type, SilcLogCb cb,
504 * Set `cb' as the default callback function for the logging channel
505 * `type'. When SilcLog receives a message for this channel, it will
506 * trigger the callback function. If the callback function returns TRUE
507 * SilcLog will assume the input as handled and won't run its default
510 * You can disable/remove a callback by setting it to NULL or calling the
511 * function silc_log_reset_callbacks. If set, the callback function
512 * must be in the form described by SilcLogCb.
515 * silc_log_reset_callbacks
518 void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context);
520 /****f* silcutil/SilcLogAPI/silc_log_reset_callbacks
524 * void silc_log_reset_callbacks();
528 * Removes all logging callbacks for normal channels. This function does
529 * NOT remove callbacks for debugging channels (debug and hexdump), you
530 * rather need to call silc_log_set_debug_callbacks() with NULL callbacks.
533 void silc_log_reset_callbacks();
535 /****f* silcutil/SilcLogAPI/silc_log_flush_all
539 * void silc_log_flush_all();
543 * Forces flushing for all logging channels. This should be called for
544 * example after receiving special signals.
550 void silc_log_flush_all();
552 /****f* silcutil/SilcLogAPI/silc_log_reset_all
556 * void silc_log_reset_all();
560 * Forces all logging channels to close and reopen their streams. Useful
561 * for example after a SIGHUP signal.
562 * Please note that this function could generate some warning messages if
563 * one or more logging channels point to an illegal filename.
566 void silc_log_reset_all();
568 /****f* silcutil/SilcLogAPI/silc_log_output_debug
572 * void silc_log_output_debug(char *file, const char *function,
573 * int line, char *string);
577 * This is the main function for debug output. Please note that you should
578 * rather use the wrapper macro SILC_LOG_DEBUG.
579 * If you want to use it anyway, the `file', `function', and `line' are the
580 * corresponding offsets in the source files, while `string' must be a
581 * dynamic allocated (null-terminated) buffer.
584 void silc_log_output_debug(char *file, const char *function,
585 int line, char *string);
587 /****f* silcutil/SilcLogAPI/silc_log_output_hexdump
591 * void silc_log_output_hexdump(char *file, char *function,
592 * int line, void *data_in,
593 * SilcUInt32 len, char *string);
597 * This is the main function for hexdump output. Please note that you
598 * should rather use the wrapper macro SILC_LOG_HEXDUMP.
599 * If you want to use it anyway, the `file', `function', and `line' are the
600 * corresponding offsets in the source files, `data_in' is the beginning
601 * of the buffer you wish to hexdump, which is `len' bytes long.
602 * `string' must be a dynamic allocated (null-terminated) buffer.
605 void silc_log_output_hexdump(char *file, const char *function,
606 int line, void *data_in,
607 SilcUInt32 len, char *string);
609 /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks
613 * void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
614 * void *debug_context,
615 * SilcLogHexdumpCb hexdump_cb,
616 * void *hexdump_context);
620 * Sets `debug_cb' as the the default callback function for the debug
621 * output, that will be called with the `debug_context' parameter.
622 * When SilcLog receives a debug message, it will trigger the callback
623 * function. If the callback function returns TRUE SilcLog will assume
624 * the input as handled and won't run its default handler.
625 * `hexdump_cb' and `hexdump_context' works the same way, except that they
626 * are referred to SILC_LOG_HEXDUMP requests.
627 * You can disable/remove a callback by setting it to NULL.
628 * If set, each callback function must be either in the form described by
629 * SilcLogDebugCb or SilcLogHexdumpCb.
632 * SilcLogDebugCb, SilcLogHexdumpCb
635 void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
637 SilcLogHexdumpCb hexdump_cb,
638 void *hexdump_context);
640 /****f* silcutil/SilcLogAPI/silc_log_set_debug_string
644 * void silc_log_set_debug_string(const char *debug_string);
648 * Sets `debug_string' as the regexp string for filtering debugging
649 * output. The string is copied and it can be modified/destroyed after
650 * this function call.
653 void silc_log_set_debug_string(const char *debug_string);
655 #endif /* !SILCLOG_H */