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