lib/silcutil/silclog.h

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