lib/silcutil/silclog.h

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