lib/silcutil/silclog.h

   1 /*
   2
   3   silclog.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2006 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 /****h* silcutil/SILC Logging Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * The SILC logging APIs provide a powerful and easy-to-use interface to
  25  * the logging system and debugging output.
  26  *
  27  ***/
  28
  29 #ifndef SILCLOG_H
  30 #define SILCLOG_H
  31
  32 /****d* silcutil/SilcLogAPI/SilcLogType
  33  *
  34  * NAME
  35  *
  36  *    typedef enum { ... } SilcLogType;
  37  *
  38  * DESCRIPTION
  39  *
  40  *    The log type.  This can be given to various silc_log_* routines.
  41  *
  42  * SOURCE
  43  */
  44 typedef enum {
  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 */
  49 } SilcLogType;
  50 /***/
  51
  52 #include "silclog_i.h"
  53
  54 /****f* silcutil/SilcLogAPI/SilcLogCb
  55  *
  56  * SYNOPSIS
  57  *
  58  *    typedef SilcBool (*SilcLogCb)(SilcLogType type, char *message,
  59  *                              void *context);
  60  *
  61  * DESCRIPTION
  62  *
  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.
  66  *
  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  *
  71  * SEE ALSO
  72  *    silc_log_set_callback
  73  *
  74  ***/
  75 typedef SilcBool (*SilcLogCb)(SilcLogType type, char *message, void *context);
  76
  77 /****f* silcutil/SilcLogAPI/SilcLogDebugCb
  78  *
  79  * SYNOPSIS
  80  *
  81  *    typedef SilcBool (*SilcLogDebugCb)(char *file, char *function, int line,
  82  *                                   char *message, void *context);
  83  *
  84  * DESCRIPTION
  85  *
  86  *    The debug logging callback function.  The default behaviour is to
  87  *    output messages to stderr.  `file', `function', and `line' are the
  88  *    corresponding offsets in the source files.  `message' points to a
  89  *    null-terminated buffer containing the debugging message, and `context'
  90  *    is the caller-specified context.
  91  *
  92  *    The message must not be modified or freed by the callback function.
  93  *    If the function returns TRUE, SilcLog will assume the message as handled
  94  *    and won't run its default handler.
  95  *
  96  * SEE ALSO
  97  *    silc_debug, silc_log_set_debug_callbacks
  98  *
  99  ***/
 100 typedef SilcBool (*SilcLogDebugCb)(char *file, char *function, int line,
 101                                char *message, void *context);
 102
 103 /****f* silcutil/SilcLogAPI/SilcLogHexdumpCb
 104  *
 105  * SYNOPSIS
 106  *
 107  *    typedef SilcBool (*SilcDebugHexdumpCb)(char *file, char *function, int line,
 108  *                                       unsigned char *data,
 109  *                                       SilcUInt32 data_len,
 110  *                                       char *message, void *context;
 111  *
 112  * DESCRIPTION
 113  *
 114  *    The hexdump logging callback function.  The default behaviour is to
 115  *    print a formatted hexdump to stderr, and is commonly what you would
 116  *    like it to be.  `file', `function', and `line' are the corresponding
 117  *    offsets in the source files.  `data' is the begin of the buffer that
 118  *    should be hexdumped, which is `data_len' bytes long.
 119  *
 120  *    The `message' parameter points to a null-terminated buffer containing
 121  *    the received message, while `context' is the caller-specified context.
 122  *    The message must not be modified or freed by the callback function.
 123  *    If the function returns TRUE, SilcLog will assume the message as handled
 124  *    and won't run its default handler.
 125  *
 126  * SEE ALSO
 127  *    silc_debug_hexdump, silc_log_set_debug_callbacks
 128  *
 129  ***/
 130 typedef SilcBool (*SilcLogHexdumpCb)(char *file, char *function, int line,
 131                                  unsigned char *data, SilcUInt32 data_len,
 132                                  char *message, void *context);
 133
 134 /* Macros */
 135
 136 /****d* silcutil/SilcLogAPI/SILC_LOG_INFO
 137  *
 138  * NAME
 139  *
 140  *    #define SILC_LOG_INFO(...)
 141  *
 142  * DESCRIPTION
 143  *
 144  *    This macro is a wrapper to the main logging function.
 145  *    It supports variable argument list formatting, and *automatically*
 146  *    appends newline at the end of the string.
 147  *
 148  * NOTES
 149  *
 150  *    This macro requires double parenthesis to ensure that the VA list
 151  *    formatting would work correctly.
 152  *
 153  * EXAMPLE
 154  *
 155  *    SILC_LOG_INFO(("Today i feel %s", core->mood));
 156  *
 157  * SOURCE
 158  */
 159 #define SILC_LOG_INFO(fmt) silc_log_output(SILC_LOG_INFO, silc_format fmt)
 160 /***/
 161
 162 /****d* silcutil/SilcLogAPI/SILC_LOG_WARNING
 163  *
 164  * NAME
 165  *
 166  *    #define SILC_LOG_WARNING(...)
 167  *
 168  * DESCRIPTION
 169  *
 170  *    Wrapper to the WARNING logging channel.
 171  *    Please see the SILC_LOG_INFO macro.
 172  *
 173  * SEE ALSO
 174  *    SILC_LOG_INFO
 175  *
 176  * SOURCE
 177  */
 178 #define SILC_LOG_WARNING(fmt) silc_log_output(SILC_LOG_WARNING, silc_format fmt)
 179 /***/
 180
 181 /****d* silcutil/SilcLogAPI/SILC_LOG_ERROR
 182  *
 183  * NAME
 184  *
 185  *    #define SILC_LOG_ERROR(...)
 186  *
 187  * DESCRIPTION
 188  *
 189  *    Wrapper to the ERROR logging channel.
 190  *    Please see the SILC_LOG_INFO macro.
 191  *
 192  * SEE ALSO
 193  *    SILC_LOG_INFO
 194  *
 195  * SOURCE
 196  */
 197 #define SILC_LOG_ERROR(fmt) silc_log_output(SILC_LOG_ERROR, silc_format fmt)
 198 /***/
 199
 200 /****d* silcutil/SilcLogAPI/SILC_LOG_FATAL
 201  *
 202  * NAME
 203  *
 204  *    #define SILC_LOG_FATAL(...)
 205  *
 206  * DESCRIPTION
 207  *
 208  *    Wrapper to the FATAL logging channel.
 209  *    Please see the SILC_LOG_INFO macro.
 210  *
 211  * SEE ALSO
 212  *    SILC_LOG_INFO
 213  *
 214  * SOURCE
 215  */
 216 #define SILC_LOG_FATAL(fmt) silc_log_output(SILC_LOG_FATAL, silc_format fmt)
 217 /***/
 218
 219 /****d* silcutil/SilcLogAPI/SILC_LOG_DEBUG
 220  *
 221  * NAME
 222  *
 223  *    #define SILC_LOG_DEBUG(...)
 224  *
 225  * DESCRIPTION
 226  *
 227  *    This is a special wrapper to the debugging output (usually stderr).
 228  *    The standard behaviour is the same as SILC_LOG_INFO, with the difference
 229  *    that this macro also depends on the global define SILC_DEBUG.
 230  *
 231  *    Undefining SILC_DEBUG causes these functions to be defined to an empty
 232  *    value, thus removing all debug logging calls from the compiled
 233  *    application.
 234  *
 235  * SOURCE
 236  */
 237 #if defined(SILC_DEBUG)
 238 #define SILC_LOG_DEBUG(fmt) silc_log_output_debug(__FILE__,     \
 239                                 __FUNCTION__,                   \
 240                                 __LINE__,                       \
 241                                 silc_format fmt)
 242 #define SILC_NOT_IMPLEMENTED(string)                                    \
 243   SILC_LOG_INFO(("*********** %s: NOT IMPLEMENTED YET", string));
 244 #else
 245 #define SILC_LOG_DEBUG(fmt) do { } while(0)
 246 #define SILC_NOT_IMPLEMENTED(string) do { } while(0)
 247 #endif  /* SILC_DEBUG */
 248 /***/
 249
 250 /****d* silcutil/SilcLogAPI/SILC_LOG_HEXDUMP
 251  *
 252  * NAME
 253  *
 254  *    #define SILC_LOG_HEXDUMP(...)
 255  *
 256  * DESCRIPTION
 257  *
 258  *    This is a special wrapper to the hexdump output function.  This macro
 259  *    behaves slightly differently from other logging wrappers.
 260  *    The first parameter, is composed by a group of parameters delimited by
 261  *    parenthesis.
 262  *    The second parameter is a `char *' pointer pointing to the beginning
 263  *    of the memory section that should be hexdumped, and the third parameter
 264  *    is the length of this memory section.
 265  *    Undefining the global SILC_DEBUG define causes these functions to be
 266  *    defined to an empty value, thus removing all debug logging calls from
 267  *    the compiled application.
 268  *    This macro is also affected by the global variable silc_debug_hexdump.
 269  *
 270  * EXAMPLE
 271  *
 272  *    SILC_LOG_HEXDUMP(("Outgoing packet [%d], len %d", pckt->seq, pckt->len),
 273  *                     pckt->data, pckt->datalen);
 274  *
 275  * SOURCE
 276  */
 277 #if defined(SILC_DEBUG)
 278 #define SILC_LOG_HEXDUMP(fmt, data, len) silc_log_output_hexdump(__FILE__, \
 279                                 __FUNCTION__,                              \
 280                                 __LINE__,                                  \
 281                                 (void *)(data), (len),                     \
 282                                 silc_format fmt)
 283 #else
 284 #define SILC_LOG_HEXDUMP(fmt, data, len) do { } while(0)
 285 #endif  /* SILC_DEBUG */
 286 /***/
 287
 288 /****d* silcutil/SilcLogAPI/SILC_ASSERT
 289  *
 290  * NAME
 291  *
 292  *    #define SILC_ASSERT(experssion)
 293  *
 294  * DESCRIPTION
 295  *
 296  *    Assert macro that prints error message to stderr and calls abort()
 297  *    if the `expression' is is false (ie. compares equal to zero).  If
 298  *    SILC_DEBUG is not defined this macro as no effect.
 299  *
 300  * SOURCE
 301  */
 302 #if defined(SILC_DEBUG)
 303 #define SILC_ASSERT(expr) assert((expr));
 304 #else
 305 #define SILC_ASSERT(expr) do { } while(0)
 306 #endif /* SILC_DEBUG */
 307 /***/
 308
 309 /* Prototypes */
 310
 311 /****f* silcutil/SilcLogAPI/silc_log_set_file
 312  *
 313  * SYNOPSIS
 314  *
 315  *    SilcBool silc_log_set_file(SilcLogType type, char *filename,
 316  *                           SilcUInt32 maxsize,
 317  *                           SilcSchedule scheduler);
 318  *
 319  * DESCRIPTION
 320  *
 321  *    Sets `filename', which can be maximum `maxsize' bytes long, as the new
 322  *    logging file for the channel `type'.  If you specify an illegal filename
 323  *    a warning message is printed and FALSE is returned.  In this case
 324  *    logging settings are not changed.
 325  *
 326  *    You can disable logging for a channel by specifying NULL filename, the
 327  *    maxsize in this case is not important.  The `scheduler' parameter is
 328  *    needed by the internal logging to allow buffered output and thus to
 329  *    save HD activity.
 330  *
 331  ***/
 332 SilcBool silc_log_set_file(SilcLogType type, char *filename,
 333                            SilcUInt32 maxsize, SilcSchedule scheduler);
 334
 335 /****f* silcutil/SilcLogAPI/silc_log_get_file
 336  *
 337  * SYNOPSIS
 338  *
 339  *    char *silc_log_get_file(SilcLogType type);
 340  *
 341  * DESCRIPTION
 342  *
 343  *    Returns the current logging file for the channel `type'.
 344  *    If there has been an error during the opening of this channel, NULL
 345  *    is returned, even if the file has been previously set with
 346  *    silc_log_set_file().
 347  *
 348  *    The returned pointer points to internally allocated storage and must
 349  *    not be freed, modified or stored.
 350  *
 351  ***/
 352 char *silc_log_get_file(SilcLogType type);
 353
 354 /****f* silcutil/SilcLogAPI/silc_log_set_callback
 355  *
 356  * SYNOPSIS
 357  *
 358  *    void silc_log_set_callback(SilcLogType type, SilcLogCb cb,
 359  *                               void *context);
 360  *
 361  * DESCRIPTION
 362  *
 363  *    Set `cb' as the default callback function for the logging channel
 364  *    `type'.  When SilcLog receives a message for this channel, it will
 365  *    trigger the callback function.  If the callback function returns TRUE
 366  *    SilcLog will assume the input as handled and won't run its default
 367  *    handler.
 368  *
 369  *    You can disable/remove a callback by setting it to NULL or calling the
 370  *    function silc_log_reset_callbacks.  If set, the callback function
 371  *    must be in the form described by SilcLogCb.
 372  *
 373  * SEE ALSO
 374  *    silc_log_reset_callbacks
 375  *
 376  ***/
 377 void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context);
 378
 379 /****f* silcutil/SilcLogAPI/silc_log_reset_callbacks
 380  *
 381  * SYNOPSIS
 382  *
 383  *    void silc_log_reset_callbacks();
 384  *
 385  * DESCRIPTION
 386  *
 387  *    Removes all logging callbacks for normal channels.  This function does
 388  *    NOT remove callbacks for debugging channels (debug and hexdump), you
 389  *    rather need to call silc_log_set_debug_callbacks() with NULL callbacks.
 390  *
 391  ***/
 392 void silc_log_reset_callbacks(void);
 393
 394 /****f* silcutil/SilcLogAPI/silc_log_flush_all
 395  *
 396  * SYNOPSIS
 397  *
 398  *    void silc_log_flush_all();
 399  *
 400  * DESCRIPTION
 401  *
 402  *    Forces flushing for all logging channels.  This should be called for
 403  *    example after receiving special signals.
 404  *
 405  * SEE ALSO
 406  *    silc_log_quick
 407  *
 408  ***/
 409 void silc_log_flush_all(void);
 410
 411 /****f* silcutil/SilcLogAPI/silc_log_reset_all
 412  *
 413  * SYNOPSIS
 414  *
 415  *    void silc_log_reset_all();
 416  *
 417  * DESCRIPTION
 418  *
 419  *    Forces all logging channels to close and reopen their streams.  Useful
 420  *    for example after a SIGHUP signal.
 421  *
 422  *    Please note that this function could generate some warning messages if
 423  *    one or more logging channels point to an illegal filename.
 424  *
 425  ***/
 426 void silc_log_reset_all(void);
 427
 428 /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks
 429  *
 430  * SYNOPSIS
 431  *
 432  *    void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
 433  *                                      void *debug_context,
 434  *                                      SilcLogHexdumpCb hexdump_cb,
 435  *                                      void *hexdump_context);
 436  *
 437  * DESCRIPTION
 438  *
 439  *    Sets `debug_cb' as the the default callback function for the debug
 440  *    output, that will be called with the `debug_context' parameter.
 441  *    When SilcLog receives a debug message, it will trigger the callback
 442  *    function.  If the callback function returns TRUE SilcLog will assume
 443  *    the input as handled and won't run its default handler.  The `hexdump_cb'
 444  *    and `hexdump_context' works the same way, except that they are referred
 445  *    to SILC_LOG_HEXDUMP requests.
 446  *
 447  *    You can disable/remove a callback by setting it to NULL.  If set, each
 448  *    callback function must be either in the form described by SilcLogDebugCb
 449  *    or SilcLogHexdumpCb.
 450  *
 451  ***/
 452 void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
 453                                   void *debug_context,
 454                                   SilcLogHexdumpCb hexdump_cb,
 455                                   void *hexdump_context);
 456
 457 /****f* silcutil/SilcLogAPI/silc_log_reset_debug_callbacks
 458  *
 459  * SYNOPSIS
 460  *
 461  *    void silc_log_reset_debug_callbacks();
 462  *
 463  * DESCRIPTION
 464  *
 465  *    Resets debug callbacks set with silc_log_set_debug_callbacks.
 466  *
 467  ***/
 468 void silc_log_reset_debug_callbacks(void);
 469
 470 /****f* silcutil/SilcLogAPI/silc_log_set_debug_string
 471  *
 472  * SYNOPSIS
 473  *
 474  *    void silc_log_set_debug_string(const char *debug_string);
 475  *
 476  * DESCRIPTION
 477  *
 478  *    Sets `debug_string' as the regexp string for filtering debugging
 479  *    output.  The string is copied and it can be modified/destroyed after
 480  *    this function call.
 481  *
 482  ***/
 483 void silc_log_set_debug_string(const char *debug_string);
 484
 485 /****f* silcutil/SilcLogAPI/silc_log_timestamp
 486  *
 487  * NAME
 488  *
 489  *    void silc_log_timestamp(SilcBool enable);
 490  *
 491  * DESCRIPTION
 492  *
 493  *    Use timestamp in log messages.  Set `enable' to TRUE to enable
 494  *    timestamp and to FALSE to disable it.  Default is TRUE.
 495  *
 496  ***/
 497 void silc_log_timestamp(SilcBool enable);
 498
 499 /****f* silcutil/SilcLogAPI/silc_log_flushdelay
 500  *
 501  * NAME
 502  *
 503  *    void silc_log_flushdelay(SilcUInt32 flushdelay);
 504  *
 505  * DESCRIPTION
 506  *
 507  *    Sets the logfiles flushing delay in seconds.  Default is 300 seconds.
 508  *
 509  ***/
 510 void silc_log_flushdelay(SilcUInt32 flushdelay);
 511
 512 /****f* silcutil/SilcLogAPI/silc_log_quick
 513  *
 514  * NAME
 515  *
 516  *    void silc_log_quick(SilcBool enable);
 517  *
 518  * DESCRIPTION
 519  *
 520  *    SilcLog makes use of libc stream buffering output, which means that it
 521  *    saves HD activity by buffering the logging messages and writing them
 522  *    all together every some minutes (default is 5 minutes).
 523  *
 524  *    Setting `enable' to TRUE will force SilcLog to write messages to the
 525  *    filesystem as soon as they are received. This increases the CPU activity
 526  *    notably on bigger servers, but reduces memory usage.
 527  *
 528  *    If you want to change the logging style on-the-fly, make sure to call
 529  *    silc_log_flush_all() after setting `enable'  to TRUE.
 530  *
 531  *    Default is FALSE.
 532  *
 533  ***/
 534 void silc_log_quick(SilcBool enable);
 535
 536 /****v* silcutil/SilcLogAPI/silc_log_debug
 537  *
 538  * NAME
 539  *
 540  *    void silc_log_debug(SilcBool enable);
 541  *
 542  * DESCRIPTION
 543  *
 544  *    If `enable' is set to FALSE, debugging functions won't procude any
 545  *    output and if set to TRUE prints debug messages to stderr.  Default
 546  *    is FALSE.
 547  *
 548  * SEE ALSO
 549  *    SILC_LOG_DEBUG
 550  *
 551  ***/
 552 void silc_log_debug(SilcBool enable);
 553
 554 /****v* silcutil/SilcLogAPI/silc_log_debug_hexdump
 555  *
 556  * NAME
 557  *
 558  *    void silc_log_debug_hexdump(SilcBool enable);
 559  *
 560  * DESCRIPTION
 561  *
 562  *    If `enable' is set to FALSE, debugging functions won't produce
 563  *    any output anf if set to TRUE prints hexdump debug message to
 564  *    stderr.  Default is FALSE.
 565  *
 566  * SEE ALSO
 567  *    SILC_LOG_HEXDUMP
 568  *
 569  ***/
 570 void silc_log_debug_hexdump(SilcBool enable);
 571
 572 #endif  /* !SILCLOG_H */