X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilclog.h;h=01425a89c859473a71f336317d48f9d95121f1e5;hp=94cb814a1afb1c5cfb070f003412b3504e391221;hb=a818c5b5411bbc4436d1c5f011236985c96bb787;hpb=72cfa31520ebc0058763a30e21c13f6e9a964aa0 diff --git a/lib/silcutil/silclog.h b/lib/silcutil/silclog.h index 94cb814a..01425a89 100644 --- a/lib/silcutil/silclog.h +++ b/lib/silcutil/silclog.h @@ -2,15 +2,15 @@ silclog.h - Author: Pekka Riikonen + Author: Johnny Mnemonic - Copyright (C) 1997 - 2000 Pekka Riikonen + Copyright (C) 1997 - 2002 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. - + This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -18,107 +18,585 @@ */ +/****h* silcutil/SilcLogAPI + * + * DESCRIPTION + * + * The SILC logging APIs provide a powerful and easy-to-use interface to + * the logging system and debugging output. + * + ***/ + #ifndef SILCLOG_H #define SILCLOG_H -/* Set TRUE/FALSE to enable/disable debugging */ -extern int silc_debug; - -/* SILC Log types */ +/****d* silcutil/SilcLogAPI/SilcLogType + * + * NAME + * + * typedef enum { ... } SilcLogType; + * + * DESCRIPTION + * + * This is the main logging channel id. There are currently four known + * logging channels (plus the debugging output channel), and they are + * ordered by importance. + * See the source code for SILC coding conventions about how to choose + * the right output channel. + * + * SOURCE + */ typedef enum { + /* Generic info channel file */ SILC_LOG_INFO, + + /* This should be used for warnings and non critical failures */ SILC_LOG_WARNING, + + /* Generic error and critical failures messages */ SILC_LOG_ERROR, - SILC_LOG_FATAL + + /* Fatal messages (usually situations that will lead to a program crash */ + SILC_LOG_FATAL, + + /* Total number logging channels */ + SILC_LOG_MAX } SilcLogType; +/***/ + +/****f* silcutil/SilcLogAPI/SilcLogCb + * + * SYNOPSIS + * + * typedef bool (*SilcLogCb)(SilcLogType type, char *message, + * void *context); + * + * DESCRIPTION + * + * The logging custom callback function. The `type' is the channel ID + * that triggered the event, which allows you to use the same callback + * function for multiple logging channels. + * The `message' parameter points to a null-terminated buffer containing + * the received message, while `context' is the caller-specified context. + * The message must not be modified or freed by the callback function. + * + * SEE ALSO + * silc_log_set_callback + * + ***/ +typedef bool (*SilcLogCb)(SilcLogType type, char *message, void *context); + +/****f* silcutil/SilcLogAPI/SilcLogDebugCb + * + * SYNOPSIS + * + * typedef bool (*SilcLogDebugCb)(char *file, char *function, int line, + * char *message, void *context); + * + * DESCRIPTION + * + * The debug logging callback function. The default behaviour is to + * output messages to stderr. `file', `function', and `line' are the + * corresponding offsets in the source files. `message' points to a + * null-terminated buffer containing the debugging message, and `context' + * is the caller-specified context. + * The message must not be modified or freed by the callback function. + * If the function returns TRUE, SilcLog will assume the message as handled + * and won't run its default handler. + * + * SEE ALSO + * silc_debug, silc_log_set_debug_callbacks + * + ***/ +typedef bool (*SilcLogDebugCb)(char *file, char *function, int line, + char *message, void *context); + +/****f* silcutil/SilcLogAPI/SilcLogHexdumpCb + * + * SYNOPSIS + * + * typedef bool (*SilcDebugHexdumpCb)(char *file, char *function, int line, + * unsigned char *data, SilcUInt32 data_len, + * char *message, void *context; + * + * DESCRIPTION + * + * The hexdump logging callback function. The default behaviour is to + * print a formatted hexdump to stderr, and is commonly what you would + * like it to be. `file', `function', and `line' are the corresponding + * offsets in the source files. `data' is the begin of the buffer that + * should be hexdumped, which is `data_len' bytes long. + * The `message' parameter points to a null-terminated buffer containing + * the received message, while `context' is the caller-specified context. + * The message must not be modified or freed by the callback function. + * If the function returns TRUE, SilcLog will assume the message as handled + * and won't run its default handler. + * + * SEE ALSO + * silc_debug_hexdump, silc_log_set_debug_callbacks + * + ***/ +typedef bool (*SilcLogHexdumpCb)(char *file, char *function, int line, + unsigned char *data, SilcUInt32 data_len, + char *message, void *context); + +/* Global Variables */ + +/****v* silcutil/SilcLogAPI/silc_log_quick + * + * NAME + * + * bool silc_log_quick -- enable/disable fast logging output + * + * DESCRIPTION + * + * SilcLog makes use of libc stream buffering output, which means that it + * saves HD activity by buffering the logging messages and writing them + * all together every some minutes (default is 5 minutes). + * Setting this variable to TRUE will force SilcLog to write messages to the + * filesystem as soon as they are received. This increases the CPU activity + * notably on bigger servers, but reduces memory usage. + * If you want to change the logging style on-the-fly, make sure to call + * silc_log_flush_all() after setting this variable to TRUE. + * + ***/ +extern DLLAPI bool silc_log_quick; + +/****v* silcutil/SilcLogAPI/silc_log_flushdelay + * + * NAME + * + * long silc_log_flushdelay -- flushing time delay + * + * DESCRIPTION + * + * Sets the logfiles flushing delay in seconds. As for now, changing this + * value AFTER logfiles initialization won't take effect until previous + * delay time will expire; for example if you change from 300 seconds to + * 60 seconds you will have to wait up to 300 seconds for this change to + * take effect. + * This value must be greater than 2 seconds. + * + ***/ +extern DLLAPI long silc_log_flushdelay; + +/****v* silcutil/SilcLogAPI/silc_debug + * + * NAME + * + * bool silc_debug -- enable/disable debugging output + * + * DESCRIPTION + * + * If silc_debug is set to FALSE, debugging functions won't procude any + * output. This is useful when for example you compile in the debugging + * support but at a certain point you want to send the program in the + * background. + * + * SEE ALSO + * SILC_LOG_DEBUG + * + ***/ +extern DLLAPI bool silc_debug; + +/****v* silcutil/SilcLogAPI/silc_debug_hexdump + * + * NAME + * + * bool silc_debug_hexdump -- enable/disable debugging output + * + * DESCRIPTION + * + * If silc_debug_hexdump is set to FALSE, debugging functions won't produce + * any output. This is useful when for example you compile in the debugging + * support but at a certain point you want to send the program in the + * background. + * + * SEE ALSO + * SILC_LOG_HEXDUMP + * + ***/ +extern DLLAPI bool silc_debug_hexdump; + +/* Macros */ + +#ifdef WIN32 +#define __FUNCTION__ "" +#endif + +/****d* silcutil/SilcLogAPI/SILC_LOG_INFO + * + * NAME + * + * #define SILC_LOG_INFO(...) + * + * DESCRIPTION + * + * This macro is a wrapper to the main logging function. + * It supports variable argument list formatting, and *automatically* + * appends newline at the end of the string. + * + * NOTES + * + * This macro requires double parenthesis to ensure that the VA list + * formatting would work correctly. + * + * EXAMPLE + * + * SILC_LOG_INFO(("Today i feel %s", core->mood)); + * + * SOURCE + */ +#define SILC_LOG_INFO(fmt) silc_log_output(SILC_LOG_INFO, silc_format fmt) +/***/ + +/****d* silcutil/SilcLogAPI/SILC_LOG_WARNING + * + * NAME + * + * #define SILC_LOG_WARNING(...) + * + * DESCRIPTION + * + * Wrapper to the WARNING logging channel. + * Please see the SILC_LOG_INFO macro. + * + * SEE ALSO + * SILC_LOG_INFO + * + * SOURCE + */ +#define SILC_LOG_WARNING(fmt) silc_log_output(SILC_LOG_WARNING, silc_format fmt) +/***/ -/* Log type name structure. */ -typedef struct { - char *name; - SilcLogType type; -} SilcLogTypeName; - -/* Log function callback. */ -typedef void (*SilcLogCb)(char *message); - -/* Debug function callback. */ -typedef void (*SilcDebugCb)(char *file, char *function, - int line, char *message); - -/* Debug hexdump function callback. */ -typedef void (*SilcDebugHexdumpCb)(char *file, char *function, - int line, unsigned char *data, - uint32 data_len, char *message); - -/* Default log filenames */ -#define SILC_LOG_FILE_INFO "silcd.log" -#define SILC_LOG_FILE_WARNING "silcd_error.log" -#define SILC_LOG_FILE_ERROR SILC_LOG_FILE_WARNING -#define SILC_LOG_FILE_FATAL SILC_LOG_FILE_WARNING - -/* Log files. Set by silc_log_set_logfiles. */ -extern char *log_info_file; -extern char *log_warning_file; -extern char *log_error_file; -extern char *log_fatal_file; -extern uint32 log_info_size; -extern uint32 log_warning_size; -extern uint32 log_error_size; -extern uint32 log_fatal_size; - -/* Log macros. */ -#define SILC_LOG_INFO(fmt) (silc_log_output(log_info_file, \ - log_info_size, \ - SILC_LOG_INFO, \ - silc_format fmt)) -#define SILC_LOG_WARNING(fmt) (silc_log_output(log_warning_file, \ - log_warning_size, \ - SILC_LOG_WARNING, \ - silc_format fmt)) -#define SILC_LOG_ERROR(fmt) (silc_log_output(log_error_file, \ - log_error_size, \ - SILC_LOG_ERROR, \ - silc_format fmt)) -#define SILC_LOG_FATAL(fmt) (silc_log_output(log_fatal_file, \ - log_fatal_size, \ - SILC_LOG_FATAL, \ - silc_format fmt)) - -/* Debug macro is a bit different from other logging macros and it - is compiled in only if debugging is enabled. */ +/****d* silcutil/SilcLogAPI/SILC_LOG_ERROR + * + * NAME + * + * #define SILC_LOG_ERROR(...) + * + * DESCRIPTION + * + * Wrapper to the ERROR logging channel. + * Please see the SILC_LOG_INFO macro. + * + * SEE ALSO + * SILC_LOG_INFO + * + * SOURCE + */ +#define SILC_LOG_ERROR(fmt) silc_log_output(SILC_LOG_ERROR, silc_format fmt) +/***/ + +/****d* silcutil/SilcLogAPI/SILC_LOG_FATAL + * + * NAME + * + * #define SILC_LOG_FATAL(...) + * + * DESCRIPTION + * + * Wrapper to the FATAL logging channel. + * Please see the SILC_LOG_INFO macro. + * + * SEE ALSO + * SILC_LOG_INFO + * + * SOURCE + */ +#define SILC_LOG_FATAL(fmt) silc_log_output(SILC_LOG_FATAL, silc_format fmt) +/***/ + +/****d* silcutil/SilcLogAPI/SILC_LOG_DEBUG + * + * NAME + * + * #define SILC_LOG_DEBUG(...) + * + * DESCRIPTION + * + * This is a special wrapper to the debugging output (usually stderr). + * The standard behaviour is the same as SILC_LOG_INFO, with the difference + * that this macro also depends on the global define SILC_DEBUG. + * Undefining SILC_DEBUG causes these functions to be defined to an empty + * value, thus removing all debug logging calls from the compiled + * application. + * This macro is also affected by the global variable silc_debug. + * + * SOURCE + */ #ifdef SILC_DEBUG -#define SILC_LOG_DEBUG(fmt) (silc_log_output_debug(__FILE__, \ - __FUNCTION__, \ - __LINE__, \ - silc_format fmt)) -#define SILC_LOG_HEXDUMP(fmt, data, len) \ - (silc_log_output_hexdump(__FILE__, \ - __FUNCTION__, \ - __LINE__, \ - (data), (len), \ - silc_format fmt)) +#define SILC_LOG_DEBUG(fmt) silc_log_output_debug(__FILE__, \ + __FUNCTION__, \ + __LINE__, \ + silc_format fmt) #else #define SILC_LOG_DEBUG(fmt) +#endif /* SILC_DEBUG */ +/***/ + +/****d* silcutil/SilcLogAPI/SILC_LOG_HEXDUMP + * + * NAME + * + * #define SILC_LOG_HEXDUMP(...) + * + * DESCRIPTION + * + * This is a special wrapper to the hexdump output function. This macro + * behaves slightly differently from other logging wrappers. + * The first parameter, is composed by a group of parameters delimited by + * parenthesis. + * The second parameter is a `char *' pointer pointing to the beginning + * of the memory section that should be hexdumped, and the third parameter + * is the length of this memory section. + * Undefining the global SILC_DEBUG define causes these functions to be + * defined to an empty value, thus removing all debug logging calls from + * the compiled application. + * This macro is also affected by the global variable silc_debug_hexdump. + * + * EXAMPLE + * + * SILC_LOG_HEXDUMP(("Outgoing packet [%d], len %d", pckt->seq, pckt->len), + * pckt->data, pckt->datalen); + * + * SOURCE + */ +#ifdef SILC_DEBUG +#define SILC_LOG_HEXDUMP(fmt, data, len) silc_log_output_hexdump(__FILE__, \ + __FUNCTION__, \ + __LINE__, \ + (data), (len), \ + silc_format fmt) +#else #define SILC_LOG_HEXDUMP(fmt, data, len) -#endif +#endif /* SILC_DEBUG */ +/***/ /* Prototypes */ -void silc_log_output_debug(char *file, char *function, - int line, char *string); -void silc_log_output(const char *filename, uint32 maxsize, - SilcLogType type, char *string); -void silc_log_output_hexdump(char *file, char *function, - int line, void *data_in, - uint32 len, char *string); -void silc_log_set_files(char *info, uint32 info_size, - char *warning, uint32 warning_size, - char *error, uint32 error_size, - char *fatal, uint32 fatal_size); -void silc_log_set_callbacks(SilcLogCb info, SilcLogCb warning, - SilcLogCb error, SilcLogCb fatal); + +/****f* silcutil/SilcLogAPI/silc_log_output + * + * SYNOPSIS + * + * void silc_log_output(SilcLogType type, char *string); + * + * DESCRIPTION + * + * This is the main function for logging output. Please note that you + * should rather use one of the logging wrapper macros. + * If you really want to use this function, its usage is quite simple. + * The `type' parameter identifies the channel to use, while the `string' + * parameter must be a dynamic allocated (null-terminated) buffer, because + * it will be freed at the end of this function, for internal reasons. + * If there are registered callbacks for the specified type, this function + * will first trigger those callbacks. The callback functions must NOT + * free or modify the original buffer. + * + * SEE ALSO + * SILC_LOG_INFO, SILC_LOG_WARNING, SILC_LOG_ERROR, SILC_LOG_FATAL + * + ***/ +void silc_log_output(SilcLogType type, char *string); + +/****f* silcutil/SilcLogAPI/silc_log_get_file + * + * SYNOPSIS + * + * char *silc_log_get_file(SilcLogType type); + * + * DESCRIPTION + * + * Returns the current logging file for the channel `type'. + * If there has been an error during the opening of this channel, NULL + * is returned, even if the file has been previously set with + * silc_log_set_file(). + * The returned pointer points to internally allocated storage and must + * not be freed, modified or stored. + * + ***/ +char *silc_log_get_file(SilcLogType type); + +/****f* silcutil/SilcLogAPI/silc_log_set_file + * + * SYNOPSIS + * + * bool silc_log_set_file(SilcLogType type, char *filename, SilcUInt32 maxsize, + * SilcSchedule scheduler); + * + * DESCRIPTION + * + * Sets `filename', which can be maximum `maxsize' bytes long, as the new + * logging file for the channel `type'. If you specify an illegal filename + * a warning message is printed and FALSE is returned. In this case + * logging settings are not changed. + * You can disable logging for a channel by specifying NULL filename, the + * maxsize in this case is not important. + * The `scheduler' parameter is needed by the internal logging to allow + * buffered output and thus to save HD activity. + * + ***/ +bool silc_log_set_file(SilcLogType type, char *filename, SilcUInt32 maxsize, + SilcSchedule scheduler); + +/****f* silcutil/SilcLogAPI/silc_log_set_callback + * + * SYNOPSIS + * + * void silc_log_set_callback(SilcLogType type, SilcLogCb cb, + * void *context); + * + * DESCRIPTION + * + * Set `cb' as the default callback function for the logging channel + * `type'. When SilcLog receives a message for this channel, it will + * trigger the callback function. If the callback function returns TRUE + * SilcLog will assume the input as handled and won't run its default + * handler. + * You can disable/remove a callback by setting it to NULL or calling the + * function silc_log_reset_callbacks. + * If set, the callback function must be in the form described by + * SilcLogCb. + * + * SEE ALSO + * silc_log_reset_callbacks + * + ***/ +void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context); + +/****f* silcutil/SilcLogAPI/silc_log_reset_callbacks + * + * SYNOPSIS + * + * void silc_log_reset_callbacks(); + * + * DESCRIPTION + * + * Removes all logging callbacks for normal channels. This function does + * NOT remove callbacks for debugging channels (debug and hexdump), you + * rather need to call silc_log_set_debug_callbacks() with NULL callbacks. + * + ***/ void silc_log_reset_callbacks(); -void silc_log_set_debug_callbacks(SilcDebugCb debug, - SilcDebugHexdumpCb debug_hexdump); -void silc_log_reset_debug_callbacks(); -#endif +/****f* silcutil/SilcLogAPI/silc_log_flush_all + * + * SYNOPSIS + * + * void silc_log_flush_all(); + * + * DESCRIPTION + * + * Forces flushing for all logging channels. This should be called for + * example after receiving special signals. + * + * SEE ALSO + * silc_log_quick + * + ***/ +void silc_log_flush_all(); + +/****f* silcutil/SilcLogAPI/silc_log_reset_all + * + * SYNOPSIS + * + * void silc_log_reset_all(); + * + * DESCRIPTION + * + * Forces all logging channels to close and reopen their streams. Useful + * for example after a SIGHUP signal. + * Please note that this function could cause some warning messages if + * some logging channel points to an illegal filename. + * + ***/ +void silc_log_reset_all(); + +/****f* silcutil/SilcLogAPI/silc_log_output_debug + * + * SYNOPSIS + * + * void silc_log_output_debug(char *file, char *function, + * int line, char *string); + * + * DESCRIPTION + * + * This is the main function for debug output. Please note that you should + * rather use the wrapper macro SILC_LOG_DEBUG. + * If you want to use it anyway, the `file', `function', and `line' are the + * corresponding offsets in the source files, while `string' must be a + * dynamic allocated (null-terminated) buffer. + * + ***/ +void silc_log_output_debug(char *file, char *function, + int line, char *string); + +/****f* silcutil/SilcLogAPI/silc_log_output_hexdump + * + * SYNOPSIS + * + * void silc_log_output_hexdump(char *file, char *function, + * int line, void *data_in, + * SilcUInt32 len, char *string); + * + * DESCRIPTION + * + * This is the main function for hexdump output. Please note that you + * should rather use the wrapper macro SILC_LOG_HEXDUMP. + * If you want to use it anyway, the `file', `function', and `line' are the + * corresponding offsets in the source files, `data_in' is the beginning + * of the buffer you wish to hexdump, which is `len' bytes long. + * `string' must be a dynamic allocated (null-terminated) buffer. + * + ***/ +void silc_log_output_hexdump(char *file, char *function, + int line, void *data_in, + SilcUInt32 len, char *string); + +/****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks + * + * SYNOPSIS + * + * void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb, + * void *debug_context, + * SilcLogHexdumpCb hexdump_cb, + * void *hexdump_context); + * + * DESCRIPTION + * + * Sets `debug_cb' as the the default callback function for the debug + * output, that will be called with the `debug_context' parameter. + * When SilcLog receives a debug message, it will trigger the callback + * function. If the callback function returns TRUE SilcLog will assume + * the input as handled and won't run its default handler. + * `hexdump_cb' and `hexdump_context' works the same way, except that they + * are referred to SILC_LOG_HEXDUMP requests. + * You can disable/remove a callback by setting it to NULL. + * If set, each callback function must be either in the form described by + * SilcLogDebugCb or SilcLogHexdumpCb. + * + * SEE ALSO + * SilcLogDebugCb, SilcLogHexdumpCb + * + ***/ +void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb, + void *debug_context, + SilcLogHexdumpCb hexdump_cb, + void *hexdump_context); + +/****f* silcutil/SilcLogAPI/silc_log_set_debug_string + * + * SYNOPSIS + * + * void silc_log_set_debug_string(const char *debug_string); + * + * DESCRIPTION + * + * Sets `debug_string' as the regexp string for filtering debugging + * output. The string is copied and it can be modified/destroyed after + * this function call. + * + ***/ +void silc_log_set_debug_string(const char *debug_string); + +#endif /* !SILCLOG_H */