5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2007 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; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/SILC Logging Interface
24 * The SILC logging APIs provide a powerful and easy-to-use interface to
25 * the logging system and debugging output.
32 /****d* silcutil/SilcLogAPI/SilcLogType
36 * typedef enum { ... } SilcLogType;
40 * The log type. This can be given to various silc_log_* routines.
45 SILC_LOG_INFO = 1, /* Generic info */
46 SILC_LOG_WARNING = 2, /* Warnings and non-critical failures */
47 SILC_LOG_ERROR = 3, /* Generic error and critical failure */
48 SILC_LOG_FATAL = 4, /* Fatal error */
52 #include "silclog_i.h"
54 /****f* silcutil/SilcLogAPI/SilcLogCb
58 * typedef SilcBool (*SilcLogCb)(SilcLogType type, char *message,
63 * The logging custom callback function. The `type' is the channel ID
64 * that triggered the event, which allows you to use the same callback
65 * function for multiple logging channels.
67 * The `message' parameter points to a null-terminated buffer containing
68 * the received message, while `context' is the caller-specified context.
69 * The message must not be modified or freed by the callback function.
70 * If the function returns TRUE, SilcLog will assume the message was
71 * handled and won't run its default handler.
74 * silc_log_set_callback
77 typedef SilcBool (*SilcLogCb)(SilcLogType type, char *message, void *context);
79 /****f* silcutil/SilcLogAPI/SilcLogDebugCb
83 * typedef SilcBool (*SilcLogDebugCb)(char *file, char *function, int line,
84 * char *message, void *context);
88 * The debug logging callback function. The default behaviour is to
89 * output messages to stderr. `file', `function', and `line' are the
90 * corresponding offsets in the source files. `message' points to a
91 * null-terminated buffer containing the debugging message, and `context'
92 * is the caller-specified context.
94 * The message must not be modified or freed by the callback function.
95 * If the function returns TRUE, SilcLog will assume the message as handled
96 * and won't run its default handler.
99 * silc_debug, silc_log_set_debug_callbacks
102 typedef SilcBool (*SilcLogDebugCb)(char *file, char *function, int line,
103 char *message, void *context);
105 /****f* silcutil/SilcLogAPI/SilcLogHexdumpCb
110 * (*SilcDebugHexdumpCb)(char *file, char *function, int line,
111 * unsigned char *data,
112 * SilcUInt32 data_len,
113 * char *message, void *context;
117 * The hexdump logging callback function. The default behaviour is to
118 * print a formatted hexdump to stderr, and is commonly what you would
119 * like it to be. `file', `function', and `line' are the corresponding
120 * offsets in the source files. `data' is the begin of the buffer that
121 * should be hexdumped, which is `data_len' bytes long.
123 * The `message' parameter points to a null-terminated buffer containing
124 * the received message, while `context' is the caller-specified context.
125 * The message must not be modified or freed by the callback function.
126 * If the function returns TRUE, SilcLog will assume the message as handled
127 * and won't run its default handler.
130 * silc_debug_hexdump, silc_log_set_debug_callbacks
133 typedef SilcBool (*SilcLogHexdumpCb)(char *file, char *function, int line,
134 unsigned char *data, SilcUInt32 data_len,
135 char *message, void *context);
139 /****d* silcutil/SilcLogAPI/SILC_LOG_INFO
143 * #define SILC_LOG_INFO(...)
147 * This macro is a wrapper to the main logging function.
148 * It supports variable argument list formatting, and *automatically*
149 * appends newline at the end of the string.
153 * This macro requires double parenthesis to ensure that the VA list
154 * formatting would work correctly.
158 * SILC_LOG_INFO(("Today i feel %s", core->mood));
162 #define SILC_LOG_INFO(fmt) silc_log_output(SILC_LOG_INFO, silc_format fmt)
165 /****d* silcutil/SilcLogAPI/SILC_LOG_WARNING
169 * #define SILC_LOG_WARNING(...)
173 * Wrapper to the WARNING logging channel.
174 * Please see the SILC_LOG_INFO macro.
181 #define SILC_LOG_WARNING(fmt) silc_log_output(SILC_LOG_WARNING, silc_format fmt)
184 /****d* silcutil/SilcLogAPI/SILC_LOG_ERROR
188 * #define SILC_LOG_ERROR(...)
192 * Wrapper to the ERROR logging channel.
193 * Please see the SILC_LOG_INFO macro.
200 #define SILC_LOG_ERROR(fmt) silc_log_output(SILC_LOG_ERROR, silc_format fmt)
203 /****d* silcutil/SilcLogAPI/SILC_LOG_FATAL
207 * #define SILC_LOG_FATAL(...)
211 * Wrapper to the FATAL logging channel.
212 * Please see the SILC_LOG_INFO macro.
219 #define SILC_LOG_FATAL(fmt) silc_log_output(SILC_LOG_FATAL, silc_format fmt)
222 /****d* silcutil/SilcLogAPI/SILC_LOG_DEBUG
226 * #define SILC_LOG_DEBUG(...)
230 * This is a special wrapper to the debugging output (usually stderr).
231 * The standard behaviour is the same as SILC_LOG_INFO, with the difference
232 * that this macro also depends on the global define SILC_DEBUG.
234 * Undefining SILC_DEBUG causes these functions to be defined to an empty
235 * value, thus removing all debug logging calls from the compiled
240 #if defined(SILC_DEBUG)
241 #define SILC_LOG_DEBUG(fmt) silc_log_output_debug(__FILE__, \
245 #define SILC_NOT_IMPLEMENTED(string) \
246 SILC_LOG_INFO(("*********** %s: NOT IMPLEMENTED YET", string));
248 #define SILC_LOG_DEBUG(fmt) do { } while(0)
249 #define SILC_NOT_IMPLEMENTED(string) do { } while(0)
250 #endif /* SILC_DEBUG */
253 /****d* silcutil/SilcLogAPI/SILC_LOG_HEXDUMP
257 * #define SILC_LOG_HEXDUMP(...)
261 * This is a special wrapper to the hexdump output function. This macro
262 * behaves slightly differently from other logging wrappers.
263 * The first parameter, is composed by a group of parameters delimited by
265 * The second parameter is a `char *' pointer pointing to the beginning
266 * of the memory section that should be hexdumped, and the third parameter
267 * is the length of this memory section.
268 * Undefining the global SILC_DEBUG define causes these functions to be
269 * defined to an empty value, thus removing all debug logging calls from
270 * the compiled application.
271 * This macro is also affected by the global variable silc_debug_hexdump.
275 * SILC_LOG_HEXDUMP(("Outgoing packet [%d], len %d", pckt->seq, pckt->len),
276 * pckt->data, pckt->datalen);
280 #if defined(SILC_DEBUG)
281 #define SILC_LOG_HEXDUMP(fmt, data, len) silc_log_output_hexdump(__FILE__, \
284 (void *)(data), (len), \
287 #define SILC_LOG_HEXDUMP(fmt, data, len) do { } while(0)
288 #endif /* SILC_DEBUG */
291 /****d* silcutil/SilcLogAPI/SILC_ASSERT
295 * #define SILC_ASSERT(experssion)
299 * Assert macro that prints error message to stderr and calls abort()
300 * if the `expression' is false (ie. compares equal to zero). If
301 * SILC_DEBUG is not defined this macro has no effect.
305 #if defined(SILC_DEBUG)
306 #define SILC_ASSERT(expr) assert((expr));
308 #define SILC_ASSERT(expr) do { } while(0)
309 #endif /* SILC_DEBUG */
312 /****d* silcutil/SilcLogAPI/SILC_VERIFY
316 * #define SILC_VERIFY(experssion)
320 * Verification macro that prints error message to stderr and calls
321 * abort() if the `expression' is false (ie. compares equal to zero)
322 * on debug builds (SILC_DEBUG defined), and prints error message to
323 * stderr on release builds (SILC_DEBUG undefined) but does not abort().
324 * This macro is always compiled even if debugging (SILC_DEBUG) is not
329 #if defined(SILC_DEBUG)
330 #define SILC_VERIFY(expr) assert((expr));
332 #define SILC_VERIFY(expr) \
333 if (silc_unlikely(!(expr))) { \
334 SILC_LOG_ERROR(("SILC_VERIFY %s:%s:%d", \
335 __FILE__, __FUNCTION__, __LINE__)); \
336 silc_set_errno_reason_nofail(SILC_ERR_ASSERT, "SILC_VERIFY %s:%s:%d", \
337 __FILE__, __FUNCTION__, __LINE__); \
339 #endif /* SILC_DEBUG */
344 /****f* silcutil/SilcLogAPI/silc_log_set_file
348 * SilcBool silc_log_set_file(SilcLogType type, char *filename,
349 * SilcUInt32 maxsize,
350 * SilcSchedule scheduler);
354 * Sets `filename', which can be maximum `maxsize' bytes long, as the new
355 * logging file for the channel `type'. If you specify an illegal filename
356 * a warning message is printed and FALSE is returned. In this case
357 * logging settings are not changed.
359 * You can disable logging for a channel by specifying NULL filename, the
360 * maxsize in this case is not important. The `scheduler' parameter is
361 * needed by the internal logging to allow buffered output and thus to
362 * save HD activity. If `scheduler' is NULL this will call
363 * silc_schedule_get_global to try to get global scheduler.
366 SilcBool silc_log_set_file(SilcLogType type, char *filename,
367 SilcUInt32 maxsize, SilcSchedule scheduler);
369 /****f* silcutil/SilcLogAPI/silc_log_get_file
373 * char *silc_log_get_file(SilcLogType type);
377 * Returns the current logging file for the channel `type'.
378 * If there has been an error during the opening of this channel, NULL
379 * is returned, even if the file has been previously set with
380 * silc_log_set_file().
382 * The returned pointer points to internally allocated storage and must
383 * not be freed, modified or stored.
386 char *silc_log_get_file(SilcLogType type);
388 /****f* silcutil/SilcLogAPI/silc_log_set_callback
392 * void silc_log_set_callback(SilcLogType type, SilcLogCb cb,
397 * Set `cb' as the default callback function for the logging channel
398 * `type'. When SilcLog receives a message for this channel, it will
399 * trigger the callback function. If the callback function returns TRUE
400 * SilcLog will assume the input as handled and won't run its default
403 * You can disable/remove a callback by setting it to NULL or calling the
404 * function silc_log_reset_callbacks. If set, the callback function
405 * must be in the form described by SilcLogCb.
408 * silc_log_reset_callbacks
411 void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context);
413 /****f* silcutil/SilcLogAPI/silc_log_reset_callbacks
417 * void silc_log_reset_callbacks();
421 * Removes all logging callbacks for normal channels. This function does
422 * NOT remove callbacks for debugging channels (debug and hexdump), you
423 * rather need to call silc_log_set_debug_callbacks() with NULL callbacks.
426 void silc_log_reset_callbacks(void);
428 /****f* silcutil/SilcLogAPI/silc_log_flush_all
432 * void silc_log_flush_all();
436 * Forces flushing for all logging channels. This should be called for
437 * example after receiving special signals.
443 void silc_log_flush_all(void);
445 /****f* silcutil/SilcLogAPI/silc_log_reset_all
449 * void silc_log_reset_all();
453 * Forces all logging channels to close and reopen their streams. Useful
454 * for example after a SIGHUP signal.
456 * Please note that this function could generate some warning messages if
457 * one or more logging channels point to an illegal filename.
460 void silc_log_reset_all(void);
462 /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks
466 * void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
467 * void *debug_context,
468 * SilcLogHexdumpCb hexdump_cb,
469 * void *hexdump_context);
473 * Sets `debug_cb' as the the default callback function for the debug
474 * output, that will be called with the `debug_context' parameter.
475 * When SilcLog receives a debug message, it will trigger the callback
476 * function. If the callback function returns TRUE SilcLog will assume
477 * the input as handled and won't run its default handler. The `hexdump_cb'
478 * and `hexdump_context' works the same way, except that they are referred
479 * to SILC_LOG_HEXDUMP requests.
481 * You can disable/remove a callback by setting it to NULL. If set, each
482 * callback function must be either in the form described by SilcLogDebugCb
483 * or SilcLogHexdumpCb.
486 void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
488 SilcLogHexdumpCb hexdump_cb,
489 void *hexdump_context);
491 /****f* silcutil/SilcLogAPI/silc_log_reset_debug_callbacks
495 * void silc_log_reset_debug_callbacks();
499 * Resets debug callbacks set with silc_log_set_debug_callbacks.
502 void silc_log_reset_debug_callbacks(void);
504 /****f* silcutil/SilcLogAPI/silc_log_set_debug_string
508 * void silc_log_set_debug_string(const char *debug_string);
512 * Sets `debug_string' as the regexp string for filtering debugging
513 * output. The string is copied and it can be modified/destroyed after
514 * this function call.
517 void silc_log_set_debug_string(const char *debug_string);
519 /****f* silcutil/SilcLogAPI/silc_log_timestamp
523 * void silc_log_timestamp(SilcBool enable);
527 * Use timestamp in log messages. Set `enable' to TRUE to enable
528 * timestamp and to FALSE to disable it. Default is TRUE.
531 void silc_log_timestamp(SilcBool enable);
533 /****f* silcutil/SilcLogAPI/silc_log_flushdelay
537 * void silc_log_flushdelay(SilcUInt32 flushdelay);
541 * Sets the logfiles flushing delay in seconds. Default is 300 seconds.
544 void silc_log_flushdelay(SilcUInt32 flushdelay);
546 /****f* silcutil/SilcLogAPI/silc_log_quick
550 * void silc_log_quick(SilcBool enable);
554 * SilcLog makes use of libc stream buffering output, which means that it
555 * saves HD activity by buffering the logging messages and writing them
556 * all together every some minutes (default is 5 minutes).
558 * Setting `enable' to TRUE will force SilcLog to write messages to the
559 * filesystem as soon as they are received. This increases the CPU activity
560 * notably on bigger servers, but reduces memory usage.
562 * If you want to change the logging style on-the-fly, make sure to call
563 * silc_log_flush_all() after setting `enable' to TRUE.
568 void silc_log_quick(SilcBool enable);
570 /****v* silcutil/SilcLogAPI/silc_log_debug
574 * void silc_log_debug(SilcBool enable);
578 * If `enable' is set to FALSE, debugging functions won't procude any
579 * output and if set to TRUE prints debug messages to stderr. Default
586 void silc_log_debug(SilcBool enable);
588 /****v* silcutil/SilcLogAPI/silc_log_debug_hexdump
592 * void silc_log_debug_hexdump(SilcBool enable);
596 * If `enable' is set to FALSE, debugging functions won't produce
597 * any output anf if set to TRUE prints hexdump debug message to
598 * stderr. Default is FALSE.
604 void silc_log_debug_hexdump(SilcBool enable);
606 #endif /* !SILCLOG_H */