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