lib/silcutil/silclog.h

   1 /*
   2
   3   silclog.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2005 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 bool (*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 bool (*SilcLogCb)(SilcLogType type, char *message, void *context);
  76
  77 /****f* silcutil/SilcLogAPI/SilcLogDebugCb
  78  *
  79  * SYNOPSIS
  80  *
  81  *    typedef bool (*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 bool (*SilcLogDebugCb)(char *file, char *function, int line,
 101                                char *message, void *context);
 102
 103 /****f* silcutil/SilcLogAPI/SilcLogHexdumpCb
 104  *
 105  * SYNOPSIS
 106  *
 107  *    typedef bool (*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 bool (*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 /* Prototypes */
 289
 290 /****f* silcutil/SilcLogAPI/silc_log_set_file
 291  *
 292  * SYNOPSIS
 293  *
 294  *    bool silc_log_set_file(SilcLogType type, char *filename,
 295  *                           SilcUInt32 maxsize,
 296  *                           SilcSchedule scheduler);
 297  *
 298  * DESCRIPTION
 299  *
 300  *    Sets `filename', which can be maximum `maxsize' bytes long, as the new
 301  *    logging file for the channel `type'.  If you specify an illegal filename
 302  *    a warning message is printed and FALSE is returned.  In this case
 303  *    logging settings are not changed.
 304  *
 305  *    You can disable logging for a channel by specifying NULL filename, the
 306  *    maxsize in this case is not important.  The `scheduler' parameter is
 307  *    needed by the internal logging to allow buffered output and thus to
 308  *    save HD activity.
 309  *
 310  ***/
 311 bool silc_log_set_file(SilcLogType type, char *filename, SilcUInt32 maxsize,
 312                        SilcSchedule scheduler);
 313
 314 /****f* silcutil/SilcLogAPI/silc_log_get_file
 315  *
 316  * SYNOPSIS
 317  *
 318  *    char *silc_log_get_file(SilcLogType type);
 319  *
 320  * DESCRIPTION
 321  *
 322  *    Returns the current logging file for the channel `type'.
 323  *    If there has been an error during the opening of this channel, NULL
 324  *    is returned, even if the file has been previously set with
 325  *    silc_log_set_file().
 326  *
 327  *    The returned pointer points to internally allocated storage and must
 328  *    not be freed, modified or stored.
 329  *
 330  ***/
 331 char *silc_log_get_file(SilcLogType type);
 332
 333 /****f* silcutil/SilcLogAPI/silc_log_set_callback
 334  *
 335  * SYNOPSIS
 336  *
 337  *    void silc_log_set_callback(SilcLogType type, SilcLogCb cb,
 338  *                               void *context);
 339  *
 340  * DESCRIPTION
 341  *
 342  *    Set `cb' as the default callback function for the logging channel
 343  *    `type'.  When SilcLog receives a message for this channel, it will
 344  *    trigger the callback function.  If the callback function returns TRUE
 345  *    SilcLog will assume the input as handled and won't run its default
 346  *    handler.
 347  *
 348  *    You can disable/remove a callback by setting it to NULL or calling the
 349  *    function silc_log_reset_callbacks.  If set, the callback function
 350  *    must be in the form described by SilcLogCb.
 351  *
 352  * SEE ALSO
 353  *    silc_log_reset_callbacks
 354  *
 355  ***/
 356 void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context);
 357
 358 /****f* silcutil/SilcLogAPI/silc_log_reset_callbacks
 359  *
 360  * SYNOPSIS
 361  *
 362  *    void silc_log_reset_callbacks();
 363  *
 364  * DESCRIPTION
 365  *
 366  *    Removes all logging callbacks for normal channels.  This function does
 367  *    NOT remove callbacks for debugging channels (debug and hexdump), you
 368  *    rather need to call silc_log_set_debug_callbacks() with NULL callbacks.
 369  *
 370  ***/
 371 void silc_log_reset_callbacks(void);
 372
 373 /****f* silcutil/SilcLogAPI/silc_log_flush_all
 374  *
 375  * SYNOPSIS
 376  *
 377  *    void silc_log_flush_all();
 378  *
 379  * DESCRIPTION
 380  *
 381  *    Forces flushing for all logging channels.  This should be called for
 382  *    example after receiving special signals.
 383  *
 384  * SEE ALSO
 385  *    silc_log_quick
 386  *
 387  ***/
 388 void silc_log_flush_all(void);
 389
 390 /****f* silcutil/SilcLogAPI/silc_log_reset_all
 391  *
 392  * SYNOPSIS
 393  *
 394  *    void silc_log_reset_all();
 395  *
 396  * DESCRIPTION
 397  *
 398  *    Forces all logging channels to close and reopen their streams.  Useful
 399  *    for example after a SIGHUP signal.
 400  *
 401  *    Please note that this function could generate some warning messages if
 402  *    one or more logging channels point to an illegal filename.
 403  *
 404  ***/
 405 void silc_log_reset_all(void);
 406
 407 /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks
 408  *
 409  * SYNOPSIS
 410  *
 411  *    void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
 412  *                                      void *debug_context,
 413  *                                      SilcLogHexdumpCb hexdump_cb,
 414  *                                      void *hexdump_context);
 415  *
 416  * DESCRIPTION
 417  *
 418  *    Sets `debug_cb' as the the default callback function for the debug
 419  *    output, that will be called with the `debug_context' parameter.
 420  *    When SilcLog receives a debug message, it will trigger the callback
 421  *    function.  If the callback function returns TRUE SilcLog will assume
 422  *    the input as handled and won't run its default handler.  The `hexdump_cb'
 423  *    and `hexdump_context' works the same way, except that they are referred
 424  *    to SILC_LOG_HEXDUMP requests.
 425  *
 426  *    You can disable/remove a callback by setting it to NULL.  If set, each
 427  *    callback function must be either in the form described by SilcLogDebugCb
 428  *    or SilcLogHexdumpCb.
 429  *
 430  ***/
 431 void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
 432                                   void *debug_context,
 433                                   SilcLogHexdumpCb hexdump_cb,
 434                                   void *hexdump_context);
 435
 436 /****f* silcutil/SilcLogAPI/silc_log_reset_debug_callbacks
 437  *
 438  * SYNOPSIS
 439  *
 440  *    void silc_log_reset_debug_callbacks();
 441  *
 442  * DESCRIPTION
 443  *
 444  *    Resets debug callbacks set with silc_log_set_debug_callbacks.
 445  *
 446  ***/
 447 void silc_log_reset_debug_callbacks(void);
 448
 449 /****f* silcutil/SilcLogAPI/silc_log_set_debug_string
 450  *
 451  * SYNOPSIS
 452  *
 453  *    void silc_log_set_debug_string(const char *debug_string);
 454  *
 455  * DESCRIPTION
 456  *
 457  *    Sets `debug_string' as the regexp string for filtering debugging
 458  *    output.  The string is copied and it can be modified/destroyed after
 459  *    this function call.
 460  *
 461  ***/
 462 void silc_log_set_debug_string(const char *debug_string);
 463
 464 /****f* silcutil/SilcLogAPI/silc_log_timestamp
 465  *
 466  * NAME
 467  *
 468  *    void silc_log_timestamp(bool enable);
 469  *
 470  * DESCRIPTION
 471  *
 472  *    Use timestamp in log messages.  Set `enable' to TRUE to enable
 473  *    timestamp and to FALSE to disable it.  Default is TRUE.
 474  *
 475  ***/
 476 void silc_log_timestamp(bool enable);
 477
 478 /****f* silcutil/SilcLogAPI/silc_log_flushdelay
 479  *
 480  * NAME
 481  *
 482  *    void silc_log_flushdelay(SilcUInt32 flushdelay);
 483  *
 484  * DESCRIPTION
 485  *
 486  *    Sets the logfiles flushing delay in seconds.  Default is 300 seconds.
 487  *
 488  ***/
 489 void silc_log_flushdelay(SilcUInt32 flushdelay);
 490
 491 /****f* silcutil/SilcLogAPI/silc_log_quick
 492  *
 493  * NAME
 494  *
 495  *    void silc_log_quick(bool enable);
 496  *
 497  * DESCRIPTION
 498  *
 499  *    SilcLog makes use of libc stream buffering output, which means that it
 500  *    saves HD activity by buffering the logging messages and writing them
 501  *    all together every some minutes (default is 5 minutes).
 502  *
 503  *    Setting `enable' to TRUE will force SilcLog to write messages to the
 504  *    filesystem as soon as they are received. This increases the CPU activity
 505  *    notably on bigger servers, but reduces memory usage.
 506  *
 507  *    If you want to change the logging style on-the-fly, make sure to call
 508  *    silc_log_flush_all() after setting `enable'  to TRUE.
 509  *
 510  *    Default is FALSE.
 511  *
 512  ***/
 513 void silc_log_quick(bool enable);
 514
 515 /****v* silcutil/SilcLogAPI/silc_log_debug
 516  *
 517  * NAME
 518  *
 519  *    void silc_log_debug(bool enable);
 520  *
 521  * DESCRIPTION
 522  *
 523  *    If `enable' is set to FALSE, debugging functions won't procude any
 524  *    output and if set to TRUE prints debug messages to stderr.  Default
 525  *    is FALSE.
 526  *
 527  * SEE ALSO
 528  *    SILC_LOG_DEBUG
 529  *
 530  ***/
 531 void silc_log_debug(bool enable);
 532
 533 /****v* silcutil/SilcLogAPI/silc_log_debug_hexdump
 534  *
 535  * NAME
 536  *
 537  *    void silc_log_debug_hexdump(bool enable);
 538  *
 539  * DESCRIPTION
 540  *
 541  *    If `enable' is set to FALSE, debugging functions won't produce
 542  *    any output anf if set to TRUE prints hexdump debug message to
 543  *    stderr.  Default is FALSE.
 544  *
 545  * SEE ALSO
 546  *    SILC_LOG_HEXDUMP
 547  *
 548  ***/
 549 void silc_log_debug_hexdump(bool enable);
 550
 551 #endif  /* !SILCLOG_H */