lib/silcutil/silclog.h

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