X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilclog.h;h=624120356e8dbd9a35752e7559832ac19d199aa6;hb=c257b555225193e54d85daf541d29578b3c93882;hp=76f8f67c7a8c5a8520cafa1563d1d9a5a8bd1a01;hpb=0a1c9639d647b4cd77ebdb79b95e9076ca240b9c;p=silc.git diff --git a/lib/silcutil/silclog.h b/lib/silcutil/silclog.h index 76f8f67c..62412035 100644 --- a/lib/silcutil/silclog.h +++ b/lib/silcutil/silclog.h @@ -2,9 +2,9 @@ silclog.h - Author: Johnny Mnemonic + Author: Giovanni Giacobbi - Copyright (C) 1997 - 2002 Pekka Riikonen + Copyright (C) 1997 - 2005 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 @@ -18,7 +18,7 @@ */ -/****h* silcutil/SilcLogAPI +/****h* silcutil/SILC Logging Interface * * DESCRIPTION * @@ -41,7 +41,8 @@ * 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 choosing + * + * See the source code for SILC coding conventions about how to choose * the right output channel. * * SOURCE @@ -53,13 +54,13 @@ typedef enum { /* This should be used for warnings and non critical failures */ SILC_LOG_WARNING, - /* Generic error and critical failures messages */ + /* Generic error and critical failure messages */ SILC_LOG_ERROR, /* Fatal messages (usually situations that will lead to a program crash */ SILC_LOG_FATAL, - /* Total logging channels */ + /* Total number logging channels */ SILC_LOG_MAX } SilcLogType; /***/ @@ -116,14 +117,14 @@ typedef bool (*SilcLogDebugCb)(char *file, char *function, int line, * SYNOPSIS * * typedef bool (*SilcDebugHexdumpCb)(char *file, char *function, int line, - * unsigned char *data, uint32 data_len, + * 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 it - * like to be. `file', `function', and `line' are the corresponding + * 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 @@ -137,11 +138,27 @@ typedef bool (*SilcLogDebugCb)(char *file, char *function, int line, * ***/ typedef bool (*SilcLogHexdumpCb)(char *file, char *function, int line, - unsigned char *data, uint32 data_len, + unsigned char *data, SilcUInt32 data_len, char *message, void *context); /* Global Variables */ +/****v* silcutil/SilcLogAPI/silc_log_timestamp + * + * NAME + * + * bool silc_log_timestamp -- enable/disable fast logging timestamp + * + * DESCRIPTION + * + * Causes SilcLog to add a timestamp as returned by silc_get_time(). + * This may be useful for example if you run your application under a + * daemon helper like watchdog that adds its own timestamp. Defaults to + * true. + * + ***/ +extern DLLAPI bool silc_log_timestamp; + /****v* silcutil/SilcLogAPI/silc_log_quick * * NAME @@ -220,9 +237,38 @@ extern DLLAPI bool silc_debug_hexdump; /* Macros */ -#ifdef WIN32 +#if defined(WIN32) +#ifndef __FUNCTION__ #define __FUNCTION__ "" #endif +#endif + +/****d* silcutil/SilcLogAPI/SILC_ENABLE_DEBUG + * + * NAME + * + * #define SILC_ENABLE_DEBUG + * + * DESCRIPTION + * + * Use this macro to enable the debugging in your application. If + * SILC was compiled with debugging enabled, this macro enables it. + * Use this macro in your application's main header, or in place where + * you need to enable the debugging. + * + * NOTES + * + * You still can control the debugging with silc_debug variable, on + * whether to actually print the debugging or not. This macro is + * used to enable debugging, not to say it is printed or not. + * + * SOURCE + */ +#define SILC_ENABLE_DEBUG \ + #ifndef SILC_DEBUG \ + #define SILC_DEBUG 1 \ + #endif +/***/ /****d* silcutil/SilcLogAPI/SILC_LOG_INFO * @@ -316,24 +362,25 @@ extern DLLAPI bool silc_debug_hexdump; * DESCRIPTION * * This is a special wrapper to the debugging output (usually stderr). - * The standard behaviour is the same as SILC_LOG_INFO, but this macro - * also depends on the global debugging macro SILC_DEBUG. - * Undefining the global SILC_DEBUG define causes these functions to be - * defined to an empty value, thus removing all logging calls from the - * compiled program. - * - * SEE ALSO - * SILC_LOG_INFO + * 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 +#if defined(SILC_DEBUG) #define SILC_LOG_DEBUG(fmt) silc_log_output_debug(__FILE__, \ __FUNCTION__, \ __LINE__, \ silc_format fmt) +#define SILC_NOT_IMPLEMENTED(string) \ + SILC_LOG_INFO(("*********** %s: NOT IMPLEMENTED YET", string)); #else -#define SILC_LOG_DEBUG(fmt) +#define SILC_LOG_DEBUG(fmt) do { } while(0) +#define SILC_NOT_IMPLEMENTED(string) do { } while(0) #endif /* SILC_DEBUG */ /***/ @@ -349,13 +396,13 @@ extern DLLAPI bool silc_debug_hexdump; * 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 to the beginning of the - * memory section that should be hexdumped, and the third parameter is - * the length of this memory section. - * This macro is also affected by the global variable silc_debug_hexdump. + * 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 logging calls from the - * compiled program. + * 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 * @@ -364,14 +411,14 @@ extern DLLAPI bool silc_debug_hexdump; * * SOURCE */ -#ifdef SILC_DEBUG +#if defined(SILC_DEBUG) #define SILC_LOG_HEXDUMP(fmt, data, len) silc_log_output_hexdump(__FILE__, \ - __FUNCTION__, \ - __LINE__, \ - (data), (len), \ + __FUNCTION__, \ + __LINE__, \ + (void *)(data), (len), \ silc_format fmt) #else -#define SILC_LOG_HEXDUMP(fmt, data, len) +#define SILC_LOG_HEXDUMP(fmt, data, len) do { } while(0) #endif /* SILC_DEBUG */ /***/ @@ -387,6 +434,7 @@ extern DLLAPI bool silc_debug_hexdump; * * 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 @@ -413,8 +461,9 @@ void silc_log_output(SilcLogType type, char *string); * 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 - * must not be freed, modified or stored. + * not be freed, modified or stored. * ***/ char *silc_log_get_file(SilcLogType type); @@ -423,7 +472,8 @@ char *silc_log_get_file(SilcLogType type); * * SYNOPSIS * - * bool silc_log_set_file(SilcLogType type, char *filename, uint32 maxsize, + * bool silc_log_set_file(SilcLogType type, char *filename, + * SilcUInt32 maxsize, * SilcSchedule scheduler); * * DESCRIPTION @@ -432,13 +482,14 @@ char *silc_log_get_file(SilcLogType type); * 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. + * 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, uint32 maxsize, +bool silc_log_set_file(SilcLogType type, char *filename, SilcUInt32 maxsize, SilcSchedule scheduler); /****f* silcutil/SilcLogAPI/silc_log_set_callback @@ -455,13 +506,13 @@ bool silc_log_set_file(SilcLogType type, char *filename, uint32 maxsize, * 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. + * function silc_log_reset_callbacks. If set, the callback function + * must be in the form described by SilcLogCb. * * SEE ALSO - * SilcLogCb, silc_log_reset_callbacks + * silc_log_reset_callbacks * ***/ void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context); @@ -508,8 +559,8 @@ void silc_log_flush_all(); * * 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. + * Please note that this function could generate some warning messages if + * one or more logging channels point to an illegal filename. * ***/ void silc_log_reset_all(); @@ -518,7 +569,7 @@ void silc_log_reset_all(); * * SYNOPSIS * - * void silc_log_output_debug(char *file, char *function, + * void silc_log_output_debug(char *file, const char *function, * int line, char *string); * * DESCRIPTION @@ -530,7 +581,7 @@ void silc_log_reset_all(); * dynamic allocated (null-terminated) buffer. * ***/ -void silc_log_output_debug(char *file, char *function, +void silc_log_output_debug(char *file, const char *function, int line, char *string); /****f* silcutil/SilcLogAPI/silc_log_output_hexdump @@ -539,7 +590,7 @@ void silc_log_output_debug(char *file, char *function, * * void silc_log_output_hexdump(char *file, char *function, * int line, void *data_in, - * uint32 len, char *string); + * SilcUInt32 len, char *string); * * DESCRIPTION * @@ -551,9 +602,9 @@ void silc_log_output_debug(char *file, char *function, * `string' must be a dynamic allocated (null-terminated) buffer. * ***/ -void silc_log_output_hexdump(char *file, char *function, +void silc_log_output_hexdump(char *file, const char *function, int line, void *data_in, - uint32 len, char *string); + SilcUInt32 len, char *string); /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks *