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 /****d* silcutil/SilcLogAPI/SILC_VERIFY
 313  *
 314  * NAME
 315  *
 316  *    #define SILC_VERIFY(experssion)
 317  *
 318  * DESCRIPTION
 319  *
 320  *    Verification macro that prints error message to stderr and calls
 321  *    abort() if the `expression' is false (ie. compares equal to zero)
 322  *    on debug builds (SILC_DEBUG defined), and prints error message to
 323  *    stderr on release builds (SILC_DEBUG undefined) but does not abort().
 324  *    This macro is always compiled even if debugging (SILC_DEBUG) is not
 325  *    defined.
 326  *
 327  * SOURCE
 328  */
 329 #if defined(SILC_DEBUG)
 330 #define SILC_VERIFY(expr) assert((expr));
 331 #else
 332 #define SILC_VERIFY(expr)                                               \
 333   if (!(expr))                                                          \
 334     SILC_LOG_ERROR(("SILC_VERIFY %s:%d", __FUNCTION__, __LINE__));
 335 #endif /* SILC_DEBUG */
 336 /***/
 337
 338 /* Prototypes */
 339
 340 /****f* silcutil/SilcLogAPI/silc_log_set_file
 341  *
 342  * SYNOPSIS
 343  *
 344  *    SilcBool silc_log_set_file(SilcLogType type, char *filename,
 345  *                           SilcUInt32 maxsize,
 346  *                           SilcSchedule scheduler);
 347  *
 348  * DESCRIPTION
 349  *
 350  *    Sets `filename', which can be maximum `maxsize' bytes long, as the new
 351  *    logging file for the channel `type'.  If you specify an illegal filename
 352  *    a warning message is printed and FALSE is returned.  In this case
 353  *    logging settings are not changed.
 354  *
 355  *    You can disable logging for a channel by specifying NULL filename, the
 356  *    maxsize in this case is not important.  The `scheduler' parameter is
 357  *    needed by the internal logging to allow buffered output and thus to
 358  *    save HD activity.
 359  *
 360  ***/
 361 SilcBool silc_log_set_file(SilcLogType type, char *filename,
 362                            SilcUInt32 maxsize, SilcSchedule scheduler);
 363
 364 /****f* silcutil/SilcLogAPI/silc_log_get_file
 365  *
 366  * SYNOPSIS
 367  *
 368  *    char *silc_log_get_file(SilcLogType type);
 369  *
 370  * DESCRIPTION
 371  *
 372  *    Returns the current logging file for the channel `type'.
 373  *    If there has been an error during the opening of this channel, NULL
 374  *    is returned, even if the file has been previously set with
 375  *    silc_log_set_file().
 376  *
 377  *    The returned pointer points to internally allocated storage and must
 378  *    not be freed, modified or stored.
 379  *
 380  ***/
 381 char *silc_log_get_file(SilcLogType type);
 382
 383 /****f* silcutil/SilcLogAPI/silc_log_set_callback
 384  *
 385  * SYNOPSIS
 386  *
 387  *    void silc_log_set_callback(SilcLogType type, SilcLogCb cb,
 388  *                               void *context);
 389  *
 390  * DESCRIPTION
 391  *
 392  *    Set `cb' as the default callback function for the logging channel
 393  *    `type'.  When SilcLog receives a message for this channel, it will
 394  *    trigger the callback function.  If the callback function returns TRUE
 395  *    SilcLog will assume the input as handled and won't run its default
 396  *    handler.
 397  *
 398  *    You can disable/remove a callback by setting it to NULL or calling the
 399  *    function silc_log_reset_callbacks.  If set, the callback function
 400  *    must be in the form described by SilcLogCb.
 401  *
 402  * SEE ALSO
 403  *    silc_log_reset_callbacks
 404  *
 405  ***/
 406 void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context);
 407
 408 /****f* silcutil/SilcLogAPI/silc_log_reset_callbacks
 409  *
 410  * SYNOPSIS
 411  *
 412  *    void silc_log_reset_callbacks();
 413  *
 414  * DESCRIPTION
 415  *
 416  *    Removes all logging callbacks for normal channels.  This function does
 417  *    NOT remove callbacks for debugging channels (debug and hexdump), you
 418  *    rather need to call silc_log_set_debug_callbacks() with NULL callbacks.
 419  *
 420  ***/
 421 void silc_log_reset_callbacks(void);
 422
 423 /****f* silcutil/SilcLogAPI/silc_log_flush_all
 424  *
 425  * SYNOPSIS
 426  *
 427  *    void silc_log_flush_all();
 428  *
 429  * DESCRIPTION
 430  *
 431  *    Forces flushing for all logging channels.  This should be called for
 432  *    example after receiving special signals.
 433  *
 434  * SEE ALSO
 435  *    silc_log_quick
 436  *
 437  ***/
 438 void silc_log_flush_all(void);
 439
 440 /****f* silcutil/SilcLogAPI/silc_log_reset_all
 441  *
 442  * SYNOPSIS
 443  *
 444  *    void silc_log_reset_all();
 445  *
 446  * DESCRIPTION
 447  *
 448  *    Forces all logging channels to close and reopen their streams.  Useful
 449  *    for example after a SIGHUP signal.
 450  *
 451  *    Please note that this function could generate some warning messages if
 452  *    one or more logging channels point to an illegal filename.
 453  *
 454  ***/
 455 void silc_log_reset_all(void);
 456
 457 /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks
 458  *
 459  * SYNOPSIS
 460  *
 461  *    void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
 462  *                                      void *debug_context,
 463  *                                      SilcLogHexdumpCb hexdump_cb,
 464  *                                      void *hexdump_context);
 465  *
 466  * DESCRIPTION
 467  *
 468  *    Sets `debug_cb' as the the default callback function for the debug
 469  *    output, that will be called with the `debug_context' parameter.
 470  *    When SilcLog receives a debug message, it will trigger the callback
 471  *    function.  If the callback function returns TRUE SilcLog will assume
 472  *    the input as handled and won't run its default handler.  The `hexdump_cb'
 473  *    and `hexdump_context' works the same way, except that they are referred
 474  *    to SILC_LOG_HEXDUMP requests.
 475  *
 476  *    You can disable/remove a callback by setting it to NULL.  If set, each
 477  *    callback function must be either in the form described by SilcLogDebugCb
 478  *    or SilcLogHexdumpCb.
 479  *
 480  ***/
 481 void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
 482                                   void *debug_context,
 483                                   SilcLogHexdumpCb hexdump_cb,
 484                                   void *hexdump_context);
 485
 486 /****f* silcutil/SilcLogAPI/silc_log_reset_debug_callbacks
 487  *
 488  * SYNOPSIS
 489  *
 490  *    void silc_log_reset_debug_callbacks();
 491  *
 492  * DESCRIPTION
 493  *
 494  *    Resets debug callbacks set with silc_log_set_debug_callbacks.
 495  *
 496  ***/
 497 void silc_log_reset_debug_callbacks(void);
 498
 499 /****f* silcutil/SilcLogAPI/silc_log_set_debug_string
 500  *
 501  * SYNOPSIS
 502  *
 503  *    void silc_log_set_debug_string(const char *debug_string);
 504  *
 505  * DESCRIPTION
 506  *
 507  *    Sets `debug_string' as the regexp string for filtering debugging
 508  *    output.  The string is copied and it can be modified/destroyed after
 509  *    this function call.
 510  *
 511  ***/
 512 void silc_log_set_debug_string(const char *debug_string);
 513
 514 /****f* silcutil/SilcLogAPI/silc_log_timestamp
 515  *
 516  * NAME
 517  *
 518  *    void silc_log_timestamp(SilcBool enable);
 519  *
 520  * DESCRIPTION
 521  *
 522  *    Use timestamp in log messages.  Set `enable' to TRUE to enable
 523  *    timestamp and to FALSE to disable it.  Default is TRUE.
 524  *
 525  ***/
 526 void silc_log_timestamp(SilcBool enable);
 527
 528 /****f* silcutil/SilcLogAPI/silc_log_flushdelay
 529  *
 530  * NAME
 531  *
 532  *    void silc_log_flushdelay(SilcUInt32 flushdelay);
 533  *
 534  * DESCRIPTION
 535  *
 536  *    Sets the logfiles flushing delay in seconds.  Default is 300 seconds.
 537  *
 538  ***/
 539 void silc_log_flushdelay(SilcUInt32 flushdelay);
 540
 541 /****f* silcutil/SilcLogAPI/silc_log_quick
 542  *
 543  * NAME
 544  *
 545  *    void silc_log_quick(SilcBool enable);
 546  *
 547  * DESCRIPTION
 548  *
 549  *    SilcLog makes use of libc stream buffering output, which means that it
 550  *    saves HD activity by buffering the logging messages and writing them
 551  *    all together every some minutes (default is 5 minutes).
 552  *
 553  *    Setting `enable' to TRUE will force SilcLog to write messages to the
 554  *    filesystem as soon as they are received. This increases the CPU activity
 555  *    notably on bigger servers, but reduces memory usage.
 556  *
 557  *    If you want to change the logging style on-the-fly, make sure to call
 558  *    silc_log_flush_all() after setting `enable'  to TRUE.
 559  *
 560  *    Default is FALSE.
 561  *
 562  ***/
 563 void silc_log_quick(SilcBool enable);
 564
 565 /****v* silcutil/SilcLogAPI/silc_log_debug
 566  *
 567  * NAME
 568  *
 569  *    void silc_log_debug(SilcBool enable);
 570  *
 571  * DESCRIPTION
 572  *
 573  *    If `enable' is set to FALSE, debugging functions won't procude any
 574  *    output and if set to TRUE prints debug messages to stderr.  Default
 575  *    is FALSE.
 576  *
 577  * SEE ALSO
 578  *    SILC_LOG_DEBUG
 579  *
 580  ***/
 581 void silc_log_debug(SilcBool enable);
 582
 583 /****v* silcutil/SilcLogAPI/silc_log_debug_hexdump
 584  *
 585  * NAME
 586  *
 587  *    void silc_log_debug_hexdump(SilcBool enable);
 588  *
 589  * DESCRIPTION
 590  *
 591  *    If `enable' is set to FALSE, debugging functions won't produce
 592  *    any output anf if set to TRUE prints hexdump debug message to
 593  *    stderr.  Default is FALSE.
 594  *
 595  * SEE ALSO
 596  *    SILC_LOG_HEXDUMP
 597  *
 598  ***/
 599 void silc_log_debug_hexdump(SilcBool enable);
 600
 601 #endif  /* !SILCLOG_H */