lib/silcutil/silclog.h

   1 /*
   2
   3   silclog.h
   4
   5   Author: Giovanni Giacobbi <giovanni@giacobbi.net>
   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  *    This is the main logging channel id. There are currently four known
  41  *    logging channels (plus the debugging output channel), and they are
  42  *    ordered by importance.
  43  *
  44  *    See the source code for SILC coding conventions about how to choose
  45  *    the right output channel.
  46  *
  47  * SOURCE
  48  */
  49 typedef enum {
  50   /* Generic info channel file */
  51   SILC_LOG_INFO,
  52
  53   /* This should be used for warnings and non critical failures */
  54   SILC_LOG_WARNING,
  55
  56   /* Generic error and critical failure messages */
  57   SILC_LOG_ERROR,
  58
  59   /* Fatal messages (usually situations that will lead to a program crash */
  60   SILC_LOG_FATAL,
  61
  62   /* Total number logging channels */
  63   SILC_LOG_MAX
  64 } SilcLogType;
  65 /***/
  66
  67 /****f* silcutil/SilcLogAPI/SilcLogCb
  68  *
  69  * SYNOPSIS
  70  *
  71  *    typedef bool (*SilcLogCb)(SilcLogType type, char *message,
  72  *                              void *context);
  73  *
  74  * DESCRIPTION
  75  *
  76  *    The logging custom callback function.  The `type' is the channel ID
  77  *    that triggered the event, which allows you to use the same callback
  78  *    function for multiple logging channels.
  79  *    The `message' parameter points to a null-terminated buffer containing
  80  *    the received message, while `context' is the caller-specified context.
  81  *    The message must not be modified or freed by the callback function.
  82  *
  83  * SEE ALSO
  84  *    silc_log_set_callback
  85  *
  86  ***/
  87 typedef bool (*SilcLogCb)(SilcLogType type, char *message, void *context);
  88
  89 /****f* silcutil/SilcLogAPI/SilcLogDebugCb
  90  *
  91  * SYNOPSIS
  92  *
  93  *    typedef bool (*SilcLogDebugCb)(char *file, char *function, int line,
  94  *                                   char *message, void *context);
  95  *
  96  * DESCRIPTION
  97  *
  98  *    The debug logging callback function.  The default behaviour is to
  99  *    output messages to stderr.  `file', `function', and `line' are the
 100  *    corresponding offsets in the source files.  `message' points to a
 101  *    null-terminated buffer containing the debugging message, and `context'
 102  *    is the caller-specified context.
 103  *    The message must not be modified or freed by the callback function.
 104  *    If the function returns TRUE, SilcLog will assume the message as handled
 105  *    and won't run its default handler.
 106  *
 107  * SEE ALSO
 108  *    silc_debug, silc_log_set_debug_callbacks
 109  *
 110  ***/
 111 typedef bool (*SilcLogDebugCb)(char *file, char *function, int line,
 112                                char *message, void *context);
 113
 114 /****f* silcutil/SilcLogAPI/SilcLogHexdumpCb
 115  *
 116  * SYNOPSIS
 117  *
 118  *    typedef bool (*SilcDebugHexdumpCb)(char *file, char *function, int line,
 119  *                                       unsigned char *data, SilcUInt32 data_len,
 120  *                                       char *message, void *context;
 121  *
 122  * DESCRIPTION
 123  *
 124  *    The hexdump logging callback function.  The default behaviour is to
 125  *    print a formatted hexdump to stderr, and is commonly what you would
 126  *    like it to be.  `file', `function', and `line' are the corresponding
 127  *    offsets in the source files.  `data' is the begin of the buffer that
 128  *    should be hexdumped, which is `data_len' bytes long.
 129  *    The `message' parameter points to a null-terminated buffer containing
 130  *    the received message, while `context' is the caller-specified context.
 131  *    The message must not be modified or freed by the callback function.
 132  *    If the function returns TRUE, SilcLog will assume the message as handled
 133  *    and won't run its default handler.
 134  *
 135  * SEE ALSO
 136  *    silc_debug_hexdump, silc_log_set_debug_callbacks
 137  *
 138  ***/
 139 typedef bool (*SilcLogHexdumpCb)(char *file, char *function, int line,
 140                                  unsigned char *data, SilcUInt32 data_len,
 141                                  char *message, void *context);
 142
 143 /* Global Variables */
 144
 145 /****v* silcutil/SilcLogAPI/silc_log_timestamp
 146  *
 147  * NAME
 148  *
 149  *    bool silc_log_timestamp -- enable/disable fast logging timestamp
 150  *
 151  * DESCRIPTION
 152  *
 153  *    Causes SilcLog to add a timestamp as returned by silc_get_time().
 154  *    This may be useful for example if you run your application under a
 155  *    daemon helper like watchdog that adds its own timestamp.  Defaults to
 156  *    true.
 157  *
 158  ***/
 159 extern DLLAPI bool silc_log_timestamp;
 160
 161 /****v* silcutil/SilcLogAPI/silc_log_quick
 162  *
 163  * NAME
 164  *
 165  *    bool silc_log_quick -- enable/disable fast logging output
 166  *
 167  * DESCRIPTION
 168  *
 169  *    SilcLog makes use of libc stream buffering output, which means that it
 170  *    saves HD activity by buffering the logging messages and writing them
 171  *    all together every some minutes (default is 5 minutes).
 172  *    Setting this variable to TRUE will force SilcLog to write messages to the
 173  *    filesystem as soon as they are received. This increases the CPU activity
 174  *    notably on bigger servers, but reduces memory usage.
 175  *    If you want to change the logging style on-the-fly, make sure to call
 176  *    silc_log_flush_all() after setting this variable to TRUE.
 177  *
 178  ***/
 179 extern DLLAPI bool silc_log_quick;
 180
 181 /****v* silcutil/SilcLogAPI/silc_log_flushdelay
 182  *
 183  * NAME
 184  *
 185  *    long silc_log_flushdelay -- flushing time delay
 186  *
 187  * DESCRIPTION
 188  *
 189  *    Sets the logfiles flushing delay in seconds.  As for now, changing this
 190  *    value AFTER logfiles initialization won't take effect until previous
 191  *    delay time will expire; for example if you change from 300 seconds to
 192  *    60 seconds you will have to wait up to 300 seconds for this change to
 193  *    take effect.
 194  *    This value must be greater than 2 seconds.
 195  *
 196  ***/
 197 extern DLLAPI long silc_log_flushdelay;
 198
 199 /****v* silcutil/SilcLogAPI/silc_debug
 200  *
 201  * NAME
 202  *
 203  *    bool silc_debug -- enable/disable debugging output
 204  *
 205  * DESCRIPTION
 206  *
 207  *    If silc_debug is set to FALSE, debugging functions won't procude any
 208  *    output.  This is useful when for example you compile in the debugging
 209  *    support but at a certain point you want to send the program in the
 210  *    background.
 211  *
 212  * SEE ALSO
 213  *    SILC_LOG_DEBUG
 214  *
 215  ***/
 216 extern DLLAPI bool silc_debug;
 217
 218 /****v* silcutil/SilcLogAPI/silc_debug_hexdump
 219  *
 220  * NAME
 221  *
 222  *    bool silc_debug_hexdump -- enable/disable debugging output
 223  *
 224  * DESCRIPTION
 225  *
 226  *    If silc_debug_hexdump is set to FALSE, debugging functions won't produce
 227  *    any output.  This is useful when for example you compile in the debugging
 228  *    support but at a certain point you want to send the program in the
 229  *    background.
 230  *
 231  * SEE ALSO
 232  *    SILC_LOG_HEXDUMP
 233  *
 234  ***/
 235 extern DLLAPI bool silc_debug_hexdump;
 236
 237 /* Macros */
 238
 239 #if defined(WIN32)
 240 #ifndef __FUNCTION__
 241 #define __FUNCTION__ ""
 242 #endif
 243 #endif
 244
 245 /****d* silcutil/SilcLogAPI/SILC_ENABLE_DEBUG
 246  *
 247  * NAME
 248  *
 249  *    #define SILC_ENABLE_DEBUG
 250  *
 251  * DESCRIPTION
 252  *
 253  *    Use this macro to enable the debugging in your application.  If
 254  *    SILC was compiled with debugging enabled, this macro enables it.
 255  *    Use this macro in your application's main header, or in place where
 256  *    you need to enable the debugging.
 257  *
 258  * NOTES
 259  *
 260  *    You still can control the debugging with silc_debug variable, on
 261  *    whether to actually print the debugging or not.  This macro is
 262  *    used to enable debugging, not to say it is printed or not.
 263  *
 264  * SOURCE
 265  */
 266 #define SILC_ENABLE_DEBUG       \
 267   #ifndef SILC_DEBUG            \
 268   #define SILC_DEBUG 1          \
 269   #endif
 270 /***/
 271
 272 /****d* silcutil/SilcLogAPI/SILC_LOG_INFO
 273  *
 274  * NAME
 275  *
 276  *    #define SILC_LOG_INFO(...)
 277  *
 278  * DESCRIPTION
 279  *
 280  *    This macro is a wrapper to the main logging function.
 281  *    It supports variable argument list formatting, and *automatically*
 282  *    appends newline at the end of the string.
 283  *
 284  * NOTES
 285  *
 286  *    This macro requires double parenthesis to ensure that the VA list
 287  *    formatting would work correctly.
 288  *
 289  * EXAMPLE
 290  *
 291  *    SILC_LOG_INFO(("Today i feel %s", core->mood));
 292  *
 293  * SOURCE
 294  */
 295 #define SILC_LOG_INFO(fmt) silc_log_output(SILC_LOG_INFO, silc_format fmt)
 296 /***/
 297
 298 /****d* silcutil/SilcLogAPI/SILC_LOG_WARNING
 299  *
 300  * NAME
 301  *
 302  *    #define SILC_LOG_WARNING(...)
 303  *
 304  * DESCRIPTION
 305  *
 306  *    Wrapper to the WARNING logging channel.
 307  *    Please see the SILC_LOG_INFO macro.
 308  *
 309  * SEE ALSO
 310  *    SILC_LOG_INFO
 311  *
 312  * SOURCE
 313  */
 314 #define SILC_LOG_WARNING(fmt) silc_log_output(SILC_LOG_WARNING, silc_format fmt)
 315 /***/
 316
 317 /****d* silcutil/SilcLogAPI/SILC_LOG_ERROR
 318  *
 319  * NAME
 320  *
 321  *    #define SILC_LOG_ERROR(...)
 322  *
 323  * DESCRIPTION
 324  *
 325  *    Wrapper to the ERROR logging channel.
 326  *    Please see the SILC_LOG_INFO macro.
 327  *
 328  * SEE ALSO
 329  *    SILC_LOG_INFO
 330  *
 331  * SOURCE
 332  */
 333 #define SILC_LOG_ERROR(fmt) silc_log_output(SILC_LOG_ERROR, silc_format fmt)
 334 /***/
 335
 336 /****d* silcutil/SilcLogAPI/SILC_LOG_FATAL
 337  *
 338  * NAME
 339  *
 340  *    #define SILC_LOG_FATAL(...)
 341  *
 342  * DESCRIPTION
 343  *
 344  *    Wrapper to the FATAL logging channel.
 345  *    Please see the SILC_LOG_INFO macro.
 346  *
 347  * SEE ALSO
 348  *    SILC_LOG_INFO
 349  *
 350  * SOURCE
 351  */
 352 #define SILC_LOG_FATAL(fmt) silc_log_output(SILC_LOG_FATAL, silc_format fmt)
 353 /***/
 354
 355 /****d* silcutil/SilcLogAPI/SILC_LOG_DEBUG
 356  *
 357  * NAME
 358  *
 359  *    #define SILC_LOG_DEBUG(...)
 360  *
 361  * DESCRIPTION
 362  *
 363  *    This is a special wrapper to the debugging output (usually stderr).
 364  *    The standard behaviour is the same as SILC_LOG_INFO, with the difference
 365  *    that this macro also depends on the global define SILC_DEBUG.
 366  *    Undefining SILC_DEBUG causes these functions to be defined to an empty
 367  *    value, thus removing all debug logging calls from the compiled
 368  *    application.
 369  *    This macro is also affected by the global variable silc_debug.
 370  *
 371  * SOURCE
 372  */
 373 #if defined(SILC_DEBUG)
 374 #define SILC_LOG_DEBUG(fmt) silc_log_output_debug(__FILE__, \
 375                                 __FUNCTION__, \
 376                                 __LINE__, \
 377                                 silc_format fmt)
 378 #define SILC_NOT_IMPLEMENTED(string) \
 379   SILC_LOG_INFO(("*********** %s: NOT IMPLEMENTED YET", string));
 380 #else
 381 #define SILC_LOG_DEBUG(fmt) do { } while(0)
 382 #define SILC_NOT_IMPLEMENTED(string) do { } while(0)
 383 #endif  /* SILC_DEBUG */
 384 /***/
 385
 386 /****d* silcutil/SilcLogAPI/SILC_LOG_HEXDUMP
 387  *
 388  * NAME
 389  *
 390  *    #define SILC_LOG_HEXDUMP(...)
 391  *
 392  * DESCRIPTION
 393  *
 394  *    This is a special wrapper to the hexdump output function.  This macro
 395  *    behaves slightly differently from other logging wrappers.
 396  *    The first parameter, is composed by a group of parameters delimited by
 397  *    parenthesis.
 398  *    The second parameter is a `char *' pointer pointing to the beginning
 399  *    of the memory section that should be hexdumped, and the third parameter
 400  *    is the length of this memory section.
 401  *    Undefining the global SILC_DEBUG define causes these functions to be
 402  *    defined to an empty value, thus removing all debug logging calls from
 403  *    the compiled application.
 404  *    This macro is also affected by the global variable silc_debug_hexdump.
 405  *
 406  * EXAMPLE
 407  *
 408  *    SILC_LOG_HEXDUMP(("Outgoing packet [%d], len %d", pckt->seq, pckt->len),
 409  *                     pckt->data, pckt->datalen);
 410  *
 411  * SOURCE
 412  */
 413 #if defined(SILC_DEBUG)
 414 #define SILC_LOG_HEXDUMP(fmt, data, len) silc_log_output_hexdump(__FILE__, \
 415                                 __FUNCTION__,                              \
 416                                 __LINE__,                                  \
 417                                 (void *)(data), (len),                     \
 418                                 silc_format fmt)
 419 #else
 420 #define SILC_LOG_HEXDUMP(fmt, data, len) do { } while(0)
 421 #endif  /* SILC_DEBUG */
 422 /***/
 423
 424 /* Prototypes */
 425
 426 /****f* silcutil/SilcLogAPI/silc_log_output
 427  *
 428  * SYNOPSIS
 429  *
 430  *    void silc_log_output(SilcLogType type, char *string);
 431  *
 432  * DESCRIPTION
 433  *
 434  *    This is the main function for logging output. Please note that you
 435  *    should rather use one of the logging wrapper macros.
 436  *
 437  *    If you really want to use this function, its usage is quite simple.
 438  *    The `type' parameter identifies the channel to use, while the `string'
 439  *    parameter must be a dynamic allocated (null-terminated) buffer, because
 440  *    it will be freed at the end of this function, for internal reasons.
 441  *    If there are registered callbacks for the specified type, this function
 442  *    will first trigger those callbacks.  The callback functions must NOT
 443  *    free or modify the original buffer.
 444  *
 445  * SEE ALSO
 446  *    SILC_LOG_INFO, SILC_LOG_WARNING, SILC_LOG_ERROR, SILC_LOG_FATAL
 447  *
 448  ***/
 449 void silc_log_output(SilcLogType type, char *string);
 450
 451 /****f* silcutil/SilcLogAPI/silc_log_get_file
 452  *
 453  * SYNOPSIS
 454  *
 455  *    char *silc_log_get_file(SilcLogType type);
 456  *
 457  * DESCRIPTION
 458  *
 459  *    Returns the current logging file for the channel `type'.
 460  *    If there has been an error during the opening of this channel, NULL
 461  *    is returned, even if the file has been previously set with
 462  *    silc_log_set_file().
 463  *
 464  *    The returned pointer points to internally allocated storage and must
 465  *    not be freed, modified or stored.
 466  *
 467  ***/
 468 char *silc_log_get_file(SilcLogType type);
 469
 470 /****f* silcutil/SilcLogAPI/silc_log_set_file
 471  *
 472  * SYNOPSIS
 473  *
 474  *    bool silc_log_set_file(SilcLogType type, char *filename,
 475  *                           SilcUInt32 maxsize,
 476  *                           SilcSchedule scheduler);
 477  *
 478  * DESCRIPTION
 479  *
 480  *    Sets `filename', which can be maximum `maxsize' bytes long, as the new
 481  *    logging file for the channel `type'.  If you specify an illegal filename
 482  *    a warning message is printed and FALSE is returned.  In this case
 483  *    logging settings are not changed.
 484  *
 485  *    You can disable logging for a channel by specifying NULL filename, the
 486  *    maxsize in this case is not important.  The `scheduler' parameter is
 487  *    needed by the internal logging to allow buffered output and thus to
 488  *    save HD activity.
 489  *
 490  ***/
 491 bool silc_log_set_file(SilcLogType type, char *filename, SilcUInt32 maxsize,
 492                        SilcSchedule scheduler);
 493
 494 /****f* silcutil/SilcLogAPI/silc_log_set_callback
 495  *
 496  * SYNOPSIS
 497  *
 498  *    void silc_log_set_callback(SilcLogType type, SilcLogCb cb,
 499  *                               void *context);
 500  *
 501  * DESCRIPTION
 502  *
 503  *    Set `cb' as the default callback function for the logging channel
 504  *    `type'.  When SilcLog receives a message for this channel, it will
 505  *    trigger the callback function.  If the callback function returns TRUE
 506  *    SilcLog will assume the input as handled and won't run its default
 507  *    handler.
 508  *
 509  *    You can disable/remove a callback by setting it to NULL or calling the
 510  *    function silc_log_reset_callbacks.  If set, the callback function
 511  *    must be in the form described by SilcLogCb.
 512  *
 513  * SEE ALSO
 514  *    silc_log_reset_callbacks
 515  *
 516  ***/
 517 void silc_log_set_callback(SilcLogType type, SilcLogCb cb, void *context);
 518
 519 /****f* silcutil/SilcLogAPI/silc_log_reset_callbacks
 520  *
 521  * SYNOPSIS
 522  *
 523  *    void silc_log_reset_callbacks();
 524  *
 525  * DESCRIPTION
 526  *
 527  *    Removes all logging callbacks for normal channels.  This function does
 528  *    NOT remove callbacks for debugging channels (debug and hexdump), you
 529  *    rather need to call silc_log_set_debug_callbacks() with NULL callbacks.
 530  *
 531  ***/
 532 void silc_log_reset_callbacks();
 533
 534 /****f* silcutil/SilcLogAPI/silc_log_flush_all
 535  *
 536  * SYNOPSIS
 537  *
 538  *    void silc_log_flush_all();
 539  *
 540  * DESCRIPTION
 541  *
 542  *    Forces flushing for all logging channels.  This should be called for
 543  *    example after receiving special signals.
 544  *
 545  * SEE ALSO
 546  *    silc_log_quick
 547  *
 548  ***/
 549 void silc_log_flush_all();
 550
 551 /****f* silcutil/SilcLogAPI/silc_log_reset_all
 552  *
 553  * SYNOPSIS
 554  *
 555  *    void silc_log_reset_all();
 556  *
 557  * DESCRIPTION
 558  *
 559  *    Forces all logging channels to close and reopen their streams.  Useful
 560  *    for example after a SIGHUP signal.
 561  *    Please note that this function could generate some warning messages if
 562  *    one or more logging channels point to an illegal filename.
 563  *
 564  ***/
 565 void silc_log_reset_all();
 566
 567 /****f* silcutil/SilcLogAPI/silc_log_output_debug
 568  *
 569  * SYNOPSIS
 570  *
 571  *    void silc_log_output_debug(char *file, const char *function,
 572  *                               int line, char *string);
 573  *
 574  * DESCRIPTION
 575  *
 576  *    This is the main function for debug output.  Please note that you should
 577  *    rather use the wrapper macro SILC_LOG_DEBUG.
 578  *    If you want to use it anyway, the `file', `function', and `line' are the
 579  *    corresponding offsets in the source files, while `string' must be a
 580  *    dynamic allocated (null-terminated) buffer.
 581  *
 582  ***/
 583 void silc_log_output_debug(char *file, const char *function,
 584                            int line, char *string);
 585
 586 /****f* silcutil/SilcLogAPI/silc_log_output_hexdump
 587  *
 588  * SYNOPSIS
 589  *
 590  *    void silc_log_output_hexdump(char *file, char *function,
 591  *                                 int line, void *data_in,
 592  *                                 SilcUInt32 len, char *string);
 593  *
 594  * DESCRIPTION
 595  *
 596  *    This is the main function for hexdump output.  Please note that you
 597  *    should rather use the wrapper macro SILC_LOG_HEXDUMP.
 598  *    If you want to use it anyway, the `file', `function', and `line' are the
 599  *    corresponding offsets in the source files, `data_in' is the beginning
 600  *    of the buffer you wish to hexdump, which is `len' bytes long.
 601  *    `string' must be a dynamic allocated (null-terminated) buffer.
 602  *
 603  ***/
 604 void silc_log_output_hexdump(char *file, const char *function,
 605                              int line, void *data_in,
 606                              SilcUInt32 len, char *string);
 607
 608 /****f* silcutil/SilcLogAPI/silc_log_set_debug_callbacks
 609  *
 610  * SYNOPSIS
 611  *
 612  *    void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
 613  *                                      void *debug_context,
 614  *                                      SilcLogHexdumpCb hexdump_cb,
 615  *                                      void *hexdump_context);
 616  *
 617  * DESCRIPTION
 618  *
 619  *    Sets `debug_cb' as the the default callback function for the debug
 620  *    output, that will be called with the `debug_context' parameter.
 621  *    When SilcLog receives a debug message, it will trigger the callback
 622  *    function.  If the callback function returns TRUE SilcLog will assume
 623  *    the input as handled and won't run its default handler.
 624  *    `hexdump_cb' and `hexdump_context' works the same way, except that they
 625  *    are referred to SILC_LOG_HEXDUMP requests.
 626  *    You can disable/remove a callback by setting it to NULL.
 627  *    If set, each callback function must be either in the form described by
 628  *    SilcLogDebugCb or SilcLogHexdumpCb.
 629  *
 630  * SEE ALSO
 631  *    SilcLogDebugCb,  SilcLogHexdumpCb
 632  *
 633  ***/
 634 void silc_log_set_debug_callbacks(SilcLogDebugCb debug_cb,
 635                                   void *debug_context,
 636                                   SilcLogHexdumpCb hexdump_cb,
 637                                   void *hexdump_context);
 638
 639 /****f* silcutil/SilcLogAPI/silc_log_set_debug_string
 640  *
 641  * SYNOPSIS
 642  *
 643  *    void silc_log_set_debug_string(const char *debug_string);
 644  *
 645  * DESCRIPTION
 646  *
 647  *    Sets `debug_string' as the regexp string for filtering debugging
 648  *    output.  The string is copied and it can be modified/destroyed after
 649  *    this function call.
 650  *
 651  ***/
 652 void silc_log_set_debug_string(const char *debug_string);
 653
 654 #endif  /* !SILCLOG_H */