X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilclog.h;h=eeaee1edf9283fab06005477da91c21f625835a3;hb=413da0f8686910f5e627393157566ae729ca99c4;hp=6a476e6ecc621670e9a4ff054eef0458cd506b13;hpb=d8414257c2a60e775002e7550feeaa63c17e6f62;p=silc.git diff --git a/lib/silcutil/silclog.h b/lib/silcutil/silclog.h index 6a476e6e..eeaee1ed 100644 --- a/lib/silcutil/silclog.h +++ b/lib/silcutil/silclog.h @@ -2,7 +2,7 @@ silclog.h - Author: Johnny Mnemonic + Author: Giovanni Giacobbi Copyright (C) 1997 - 2002 Pekka Riikonen @@ -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 @@ -160,7 +177,7 @@ typedef bool (*SilcLogHexdumpCb)(char *file, char *function, int line, * silc_log_flush_all() after setting this variable to TRUE. * ***/ -extern bool silc_log_quick; +extern DLLAPI bool silc_log_quick; /****v* silcutil/SilcLogAPI/silc_log_flushdelay * @@ -175,9 +192,10 @@ extern bool silc_log_quick; * 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 long silc_log_flushdelay; +extern DLLAPI long silc_log_flushdelay; /****v* silcutil/SilcLogAPI/silc_debug * @@ -196,7 +214,7 @@ extern long silc_log_flushdelay; * SILC_LOG_DEBUG * ***/ -extern bool silc_debug; +extern DLLAPI bool silc_debug; /****v* silcutil/SilcLogAPI/silc_debug_hexdump * @@ -215,13 +233,42 @@ extern bool silc_debug; * SILC_LOG_HEXDUMP * ***/ -extern bool silc_debug_hexdump; +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 * @@ -315,24 +362,25 @@ extern 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_NOT_IMPLEMENTED(string) #endif /* SILC_DEBUG */ /***/ @@ -348,13 +396,13 @@ extern 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 * @@ -363,7 +411,7 @@ extern 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__, \ @@ -386,6 +434,7 @@ extern 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 @@ -412,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); @@ -422,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 @@ -431,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 @@ -454,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); @@ -507,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(); @@ -538,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 * @@ -552,7 +604,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); /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks *