contrib/bind-9.5.2/lib/isc/include/isc/log.h

   1 /*
   2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: log.h,v 1.54.128.5 2009/02/16 02:10:58 marka Exp $ */
  19
  20 #ifndef ISC_LOG_H
  21 #define ISC_LOG_H 1
  22
  23 /*! \file isc/log.h */
  24
  25 #include <stdio.h>
  26 #include <stdarg.h>
  27 #include <syslog.h> /* XXXDCL NT */
  28
  29 #include <isc/formatcheck.h>
  30 #include <isc/lang.h>
  31 #include <isc/platform.h>
  32 #include <isc/types.h>
  33
  34 /*@{*/
  35 /*!
  36  * \brief Severity levels, patterned after Unix's syslog levels.
  37  *
  38  */
  39 #define ISC_LOG_DEBUG(level)    (level)
  40 /*!
  41  * #ISC_LOG_DYNAMIC can only be used for defining channels with
  42  * isc_log_createchannel(), not to specify a level in isc_log_write().
  43  */
  44 #define ISC_LOG_DYNAMIC           0
  45 #define ISC_LOG_INFO            (-1)
  46 #define ISC_LOG_NOTICE          (-2)
  47 #define ISC_LOG_WARNING         (-3)
  48 #define ISC_LOG_ERROR           (-4)
  49 #define ISC_LOG_CRITICAL        (-5)
  50 /*@}*/
  51
  52 /*@{*/
  53 /*!
  54  * \brief Destinations.
  55  */
  56 #define ISC_LOG_TONULL          1
  57 #define ISC_LOG_TOSYSLOG        2
  58 #define ISC_LOG_TOFILE          3
  59 #define ISC_LOG_TOFILEDESC      4
  60 /*@}*/
  61
  62 /*@{*/
  63 /*%
  64  * Channel flags.
  65  */
  66 #define ISC_LOG_PRINTTIME       0x0001
  67 #define ISC_LOG_PRINTLEVEL      0x0002
  68 #define ISC_LOG_PRINTCATEGORY   0x0004
  69 #define ISC_LOG_PRINTMODULE     0x0008
  70 #define ISC_LOG_PRINTTAG        0x0010
  71 #define ISC_LOG_PRINTALL        0x001F
  72 #define ISC_LOG_DEBUGONLY       0x1000
  73 #define ISC_LOG_OPENERR         0x8000          /* internal */
  74 /*@}*/
  75
  76 /*@{*/
  77 /*!
  78  * \brief Other options.
  79  *
  80  * XXXDCL INFINITE doesn't yet work.  Arguably it isn't needed, but
  81  *   since I am intend to make large number of versions work efficiently,
  82  *   INFINITE is going to be trivial to add to that.
  83  */
  84 #define ISC_LOG_ROLLINFINITE    (-1)
  85 #define ISC_LOG_ROLLNEVER       (-2)
  86 /*@}*/
  87
  88 /*!
  89  * \brief Used to name the categories used by a library.
  90  *
  91  * An array of isc_logcategory
  92  * structures names each category, and the id value is initialized by calling
  93  * isc_log_registercategories.
  94  */
  95 struct isc_logcategory {
  96         const char *name;
  97         unsigned int id;
  98 };
  99
 100 /*%
 101  * Similar to isc_logcategory, but for all the modules a library defines.
 102  */
 103 struct isc_logmodule {
 104         const char *name;
 105         unsigned int id;
 106 };
 107
 108 /*%
 109  * The isc_logfile structure is initialized as part of an isc_logdestination
 110  * before calling isc_log_createchannel().
 111  *
 112  * When defining an #ISC_LOG_TOFILE
 113  * channel the name, versions and maximum_size should be set before calling
 114  * isc_log_createchannel().  To define an #ISC_LOG_TOFILEDESC channel set only
 115  * the stream before the call.
 116  *
 117  * Setting maximum_size to zero implies no maximum.
 118  */
 119 typedef struct isc_logfile {
 120         FILE *stream;           /*%< Initialized to NULL for #ISC_LOG_TOFILE. */
 121         const char *name;       /*%< NULL for #ISC_LOG_TOFILEDESC. */
 122         int versions;   /* >= 0, #ISC_LOG_ROLLNEVER, #ISC_LOG_ROLLINFINITE. */
 123         /*%
 124          * stdio's ftell is standardized to return a long, which may well not
 125          * be big enough for the largest file supportable by the operating
 126          * system (though it is _probably_ big enough for the largest log
 127          * anyone would want).  st_size returned by fstat should be typedef'd
 128          * to a size large enough for the largest possible file on a system.
 129          */
 130         isc_offset_t maximum_size;
 131         isc_boolean_t maximum_reached; /*%< Private. */
 132 } isc_logfile_t;
 133
 134 /*%
 135  * Passed to isc_log_createchannel to define the attributes of either
 136  * a stdio or a syslog log.
 137  */
 138 typedef union isc_logdestination {
 139         isc_logfile_t file;
 140         int facility;           /* XXXDCL NT */
 141 } isc_logdestination_t;
 142
 143 /*@{*/
 144 /*%
 145  * The built-in categories of libisc.
 146  *
 147  * Each library registering categories should provide library_LOGCATEGORY_name
 148  * definitions with indexes into its isc_logcategory structure corresponding to
 149  * the order of the names.
 150  */
 151 LIBISC_EXTERNAL_DATA extern isc_logcategory_t isc_categories[];
 152 LIBISC_EXTERNAL_DATA extern isc_log_t *isc_lctx;
 153 LIBISC_EXTERNAL_DATA extern isc_logmodule_t isc_modules[];
 154 /*@}*/
 155
 156 /*@{*/
 157 /*%
 158  * Do not log directly to DEFAULT.  Use another category.  When in doubt,
 159  * use GENERAL.
 160  */
 161 #define ISC_LOGCATEGORY_DEFAULT (&isc_categories[0])
 162 #define ISC_LOGCATEGORY_GENERAL (&isc_categories[1])
 163 /*@}*/
 164
 165 #define ISC_LOGMODULE_SOCKET (&isc_modules[0])
 166 #define ISC_LOGMODULE_TIME (&isc_modules[1])
 167 #define ISC_LOGMODULE_INTERFACE (&isc_modules[2])
 168 #define ISC_LOGMODULE_TIMER (&isc_modules[3])
 169 #define ISC_LOGMODULE_FILE (&isc_modules[4])
 170
 171 ISC_LANG_BEGINDECLS
 172
 173 isc_result_t
 174 isc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp);
 175 /*%<
 176  * Establish a new logging context, with default channels.
 177  *
 178  * Notes:
 179  *\li   isc_log_create() calls isc_logconfig_create(), so see its comment
 180  *      below for more information.
 181  *
 182  * Requires:
 183  *\li   mctx is a valid memory context.
 184  *\li   lctxp is not null and *lctxp is null.
 185  *\li   lcfgp is null or lcfgp is not null and *lcfgp is null.
 186  *
 187  * Ensures:
 188  *\li   *lctxp will point to a valid logging context if all of the necessary
 189  *      memory was allocated, or NULL otherwise.
 190  *\li   *lcfgp will point to a valid logging configuration if all of the
 191  *      necessary memory was allocated, or NULL otherwise.
 192  *\li   On failure, no additional memory is allocated.
 193  *
 194  * Returns:
 195  *\li   #ISC_R_SUCCESS          Success
 196  *\li   #ISC_R_NOMEMORY         Resource limit: Out of memory
 197  */
 198
 199 isc_result_t
 200 isc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp);
 201 /*%<
 202  * Create the data structure that holds all of the configurable information
 203  * about where messages are actually supposed to be sent -- the information
 204  * that could changed based on some configuration file, as opposed to the
 205  * the category/module specification of isc_log_[v]write[1] that is compiled
 206  * into a program, or the debug_level which is dynamic state information.
 207  *
 208  * Notes:
 209  *\li   It is necessary to specify the logging context the configuration
 210  *      will be used with because the number of categories and modules
 211  *      needs to be known in order to set the configuration.  However,
 212  *      the configuration is not used by the logging context until the
 213  *      isc_logconfig_use function is called.
 214  *
 215  *\li   The memory context used for operations that allocate memory for
 216  *      the configuration is that of the logging context, as specified
 217  *      in the isc_log_create call.
 218  *
 219  *\li   Four default channels are established:
 220  *\verbatim
 221  *              default_syslog
 222  *               - log to syslog's daemon facility #ISC_LOG_INFO or higher
 223  *              default_stderr
 224  *               - log to stderr #ISC_LOG_INFO or higher
 225  *              default_debug
 226  *               - log to stderr #ISC_LOG_DEBUG dynamically
 227  *              null
 228  *               - log nothing
 229  *\endverbatim
 230  *
 231  * Requires:
 232  *\li   lctx is a valid logging context.
 233  *\li   lcftp is not null and *lcfgp is null.
 234  *
 235  * Ensures:
 236  *\li   *lcfgp will point to a valid logging context if all of the necessary
 237  *      memory was allocated, or NULL otherwise.
 238  *\li   On failure, no additional memory is allocated.
 239  *
 240  * Returns:
 241  *\li   #ISC_R_SUCCESS          Success
 242  *\li   #ISC_R_NOMEMORY         Resource limit: Out of memory
 243  */
 244
 245 isc_logconfig_t *
 246 isc_logconfig_get(isc_log_t *lctx);
 247 /*%<
 248  * Returns a pointer to the configuration currently in use by the log context.
 249  *
 250  * Requires:
 251  *\li   lctx is a valid context.
 252  *
 253  * Ensures:
 254  *\li   The configuration pointer is non-null.
 255  *
 256  * Returns:
 257  *\li   The configuration pointer.
 258  */
 259
 260 isc_result_t
 261 isc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg);
 262 /*%<
 263  * Associate a new configuration with a logging context.
 264  *
 265  * Notes:
 266  *\li   This is thread safe.  The logging context will lock a mutex
 267  *      before attempting to swap in the new configuration, and isc_log_doit
 268  *      (the internal function used by all of isc_log_[v]write[1]) locks
 269  *      the same lock for the duration of its use of the configuration.
 270  *
 271  * Requires:
 272  *\li   lctx is a valid logging context.
 273  *\li   lcfg is a valid logging configuration.
 274  *\li   lctx is the same configuration given to isc_logconfig_create
 275  *              when the configuration was created.
 276  *
 277  * Ensures:
 278  *\li   Future calls to isc_log_write will use the new configuration.
 279  *
 280  * Returns:
 281  *\li   #ISC_R_SUCCESS          Success
 282  *\li   #ISC_R_NOMEMORY         Resource limit: Out of memory
 283  */
 284
 285 void
 286 isc_log_destroy(isc_log_t **lctxp);
 287 /*%<
 288  * Deallocate the memory associated with a logging context.
 289  *
 290  * Requires:
 291  *\li   *lctx is a valid logging context.
 292  *
 293  * Ensures:
 294  *\li   All of the memory associated with the logging context is returned
 295  *      to the free memory pool.
 296  *
 297  *\li   Any open files are closed.
 298  *
 299  *\li   The logging context is marked as invalid.
 300  */
 301
 302 void
 303 isc_logconfig_destroy(isc_logconfig_t **lcfgp);
 304 /*%<
 305  * Destroy a logging configuration.
 306  *
 307  * Notes:
 308  *\li   This function cannot be used directly with the return value of
 309  *      isc_logconfig_get, because a logging context must always have
 310  *      a valid configuration associated with it.
 311  *
 312  * Requires:
 313  *\li   lcfgp is not null and *lcfgp is a valid logging configuration.
 314  *\li   The logging configuration is not in use by an existing logging context.
 315  *
 316  * Ensures:
 317  *\li   All memory allocated for the configuration is freed.
 318  *
 319  *\li   The configuration is marked as invalid.
 320  */
 321
 322 void
 323 isc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]);
 324 /*%<
 325  * Identify logging categories a library will use.
 326  *
 327  * Notes:
 328  *\li   A category should only be registered once, but no mechanism enforces
 329  *      this rule.
 330  *
 331  *\li   The end of the categories array is identified by a NULL name.
 332  *
 333  *\li   Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not
 334  *      be altered or destroyed after isc_log_registercategories().
 335  *
 336  *\li   Because each element of the categories array is used by
 337  *      isc_log_categorybyname, it should not be altered or destroyed
 338  *      after registration.
 339  *
 340  *\li   The value of the id integer in each structure is overwritten
 341  *      by this function, and so id need not be initialized to any particular
 342  *      value prior to the function call.
 343  *
 344  *\li   A subsequent call to isc_log_registercategories with the same
 345  *      logging context (but new categories) will cause the last
 346  *      element of the categories array from the prior call to have
 347  *      its "name" member changed from NULL to point to the new
 348  *      categories array, and its "id" member set to UINT_MAX.
 349  *
 350  * Requires:
 351  *\li   lctx is a valid logging context.
 352  *\li   categories != NULL.
 353  *\li   categories[0].name != NULL.
 354  *
 355  * Ensures:
 356  * \li  There are references to each category in the logging context,
 357  *      so they can be used with isc_log_usechannel() and isc_log_write().
 358  */
 359
 360 void
 361 isc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]);
 362 /*%<
 363  * Identify logging categories a library will use.
 364  *
 365  * Notes:
 366  *\li   A module should only be registered once, but no mechanism enforces
 367  *      this rule.
 368  *
 369  *\li   The end of the modules array is identified by a NULL name.
 370  *
 371  *\li   Because the name is used by #ISC_LOG_PRINTMODULE, it should not
 372  *      be altered or destroyed after isc_log_registermodules().
 373  *
 374  *\li   Because each element of the modules array is used by
 375  *      isc_log_modulebyname, it should not be altered or destroyed
 376  *      after registration.
 377  *
 378  *\li   The value of the id integer in each structure is overwritten
 379  *      by this function, and so id need not be initialized to any particular
 380  *      value prior to the function call.
 381  *
 382  *\li   A subsequent call to isc_log_registermodules with the same
 383  *      logging context (but new modules) will cause the last
 384  *      element of the modules array from the prior call to have
 385  *      its "name" member changed from NULL to point to the new
 386  *      modules array, and its "id" member set to UINT_MAX.
 387  *
 388  * Requires:
 389  *\li   lctx is a valid logging context.
 390  *\li   modules != NULL.
 391  *\li   modules[0].name != NULL;
 392  *
 393  * Ensures:
 394  *\li   Each module has a reference in the logging context, so they can be
 395  *      used with isc_log_usechannel() and isc_log_write().
 396  */
 397
 398 isc_result_t
 399 isc_log_createchannel(isc_logconfig_t *lcfg, const char *name,
 400                       unsigned int type, int level,
 401                       const isc_logdestination_t *destination,
 402                       unsigned int flags);
 403 /*%<
 404  * Specify the parameters of a logging channel.
 405  *
 406  * Notes:
 407  *\li   The name argument is copied to memory in the logging context, so
 408  *      it can be altered or destroyed after isc_log_createchannel().
 409  *
 410  *\li   Defining a very large number of channels will have a performance
 411  *      impact on isc_log_usechannel(), since the names are searched
 412  *      linearly until a match is made.  This same issue does not affect
 413  *      isc_log_write, however.
 414  *
 415  *\li   Channel names can be redefined; this is primarily useful for programs
 416  *      that want their own definition of default_syslog, default_debug
 417  *      and default_stderr.
 418  *
 419  *\li   Any channel that is redefined will not affect logging that was
 420  *      already directed to its original definition, _except_ for the
 421  *      default_stderr channel.  This case is handled specially so that
 422  *      the default logging category can be changed by redefining
 423  *      default_stderr.  (XXXDCL Though now that I think of it, the default
 424  *      logging category can be changed with only one additional function
 425  *      call by defining a new channel and then calling isc_log_usechannel()
 426  *      for #ISC_LOGCATEGORY_DEFAULT.)
 427  *
 428  *\li   Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is allowed,
 429  *      but probably not what you wanted to do.
 430  *
 431  *      #ISC_LOG_DEBUGONLY will mark the channel as usable only when the
 432  *      debug level of the logging context (see isc_log_setdebuglevel)
 433  *      is non-zero.
 434  *
 435  * Requires:
 436  *\li   lcfg is a valid logging configuration.
 437  *
 438  *\li   name is not NULL.
 439  *
 440  *\li   type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or
 441  *              #ISC_LOG_TONULL.
 442  *
 443  *\li   destination is not NULL unless type is #ISC_LOG_TONULL.
 444  *
 445  *\li   level is >= #ISC_LOG_CRITICAL (the most negative logging level).
 446  *
 447  *\li   flags does not include any bits aside from the ISC_LOG_PRINT* bits
 448  *      or #ISC_LOG_DEBUGONLY.
 449  *
 450  * Ensures:
 451  *\li   #ISC_R_SUCCESS
 452  *              A channel with the given name is usable with
 453  *              isc_log_usechannel().
 454  *
 455  *\li   #ISC_R_NOMEMORY or #ISC_R_UNEXPECTED
 456  *              No additional memory is being used by the logging context.
 457  *              Any channel that previously existed with the given name
 458  *              is not redefined.
 459  *
 460  * Returns:
 461  *\li   #ISC_R_SUCCESS          Success
 462  *\li   #ISC_R_NOMEMORY         Resource limit: Out of memory
 463  *\li   #ISC_R_UNEXPECTED       type was out of range and REQUIRE()
 464  *                                      was disabled.
 465  */
 466
 467 isc_result_t
 468 isc_log_usechannel(isc_logconfig_t *lcfg, const char *name,
 469                    const isc_logcategory_t *category,
 470                    const isc_logmodule_t *module);
 471 /*%<
 472  * Associate a named logging channel with a category and module that
 473  * will use it.
 474  *
 475  * Notes:
 476  *\li   The name is searched for linearly in the set of known channel names
 477  *      until a match is found.  (Note the performance impact of a very large
 478  *      number of named channels.)  When multiple channels of the same
 479  *      name are defined, the most recent definition is found.
 480  *
 481  *\li   Specifying a very large number of channels for a category will have
 482  *      a moderate impact on performance in isc_log_write(), as each
 483  *      call looks up the category for the start of a linked list, which
 484  *      it follows all the way to the end to find matching modules.  The
 485  *      test for matching modules is  integral, though.
 486  *
 487  *\li   If category is NULL, then the channel is associated with the indicated
 488  *      module for all known categories (including the "default" category).
 489  *
 490  *\li   If module is NULL, then the channel is associated with every module
 491  *      that uses that category.
 492  *
 493  *\li   Passing both category and module as NULL would make every log message
 494  *      use the indicated channel.
 495  *
 496  * \li  Specifying a channel that is #ISC_LOG_TONULL for a category/module pair
 497  *      has no effect on any other channels associated with that pair,
 498  *      regardless of ordering.  Thus you cannot use it to "mask out" one
 499  *      category/module pair when you have specified some other channel that
 500  *      is also used by that category/module pair.
 501  *
 502  * Requires:
 503  *\li   lcfg is a valid logging configuration.
 504  *
 505  *\li   category is NULL or has an id that is in the range of known ids.
 506  *
 507  *      module is NULL or has an id that is in the range of known ids.
 508  *
 509  * Ensures:
 510  *\li   #ISC_R_SUCCESS
 511  *              The channel will be used by the indicated category/module
 512  *              arguments.
 513  *
 514  *\li   #ISC_R_NOMEMORY
 515  *              If assignment for a specific category has been requested,
 516  *              the channel has not been associated with the indicated
 517  *              category/module arguments and no additional memory is
 518  *              used by the logging context.
 519  *              If assignment for all categories has been requested
 520  *              then _some_ may have succeeded (starting with category
 521  *              "default" and progressing through the order of categories
 522  *              passed to isc_log_registercategories()) and additional memory
 523  *              is being used by whatever assignments succeeded.
 524  *
 525  * Returns:
 526  *\li   #ISC_R_SUCCESS  Success
 527  *\li   #ISC_R_NOMEMORY Resource limit: Out of memory
 528  */
 529
 530 /* Attention: next four comments PRECEED code */
 531 /*!
 532  *   \brief
 533  * Write a message to the log channels.
 534  *
 535  * Notes:
 536  *\li   Log messages containing natural language text should be logged with
 537  *      isc_log_iwrite() to allow for localization.
 538  *
 539  *\li   lctx can be NULL; this is allowed so that programs which use
 540  *      libraries that use the ISC logging system are not required to
 541  *      also use it.
 542  *
 543  *\li   The format argument is a printf(3) string, with additional arguments
 544  *      as necessary.
 545  *
 546  * Requires:
 547  *\li   lctx is a valid logging context.
 548  *
 549  *\li   The category and module arguments must have ids that are in the
 550  *      range of known ids, as established by isc_log_registercategories()
 551  *      and isc_log_registermodules().
 552  *
 553  *\li   level != #ISC_LOG_DYNAMIC.  ISC_LOG_DYNAMIC is used only to define
 554  *      channels, and explicit debugging level must be identified for
 555  *      isc_log_write() via ISC_LOG_DEBUG(level).
 556  *
 557  *\li   format != NULL.
 558  *
 559  * Ensures:
 560  *\li   The log message is written to every channel associated with the
 561  *      indicated category/module pair.
 562  *
 563  * Returns:
 564  *\li   Nothing.  Failure to log a message is not construed as a
 565  *      meaningful error.
 566  */
 567 void
 568 isc_log_write(isc_log_t *lctx, isc_logcategory_t *category,
 569                isc_logmodule_t *module, int level,
 570               const char *format, ...)
 571
 572 ISC_FORMAT_PRINTF(5, 6);
 573
 574 /*%
 575  * Write a message to the log channels.
 576  *
 577  * Notes:
 578  *\li   lctx can be NULL; this is allowed so that programs which use
 579  *      libraries that use the ISC logging system are not required to
 580  *      also use it.
 581  *
 582  *\li   The format argument is a printf(3) string, with additional arguments
 583  *      as necessary.
 584  *
 585  * Requires:
 586  *\li   lctx is a valid logging context.
 587  *
 588  *\li   The category and module arguments must have ids that are in the
 589  *      range of known ids, as established by isc_log_registercategories()
 590  *      and isc_log_registermodules().
 591  *
 592  *\li   level != #ISC_LOG_DYNAMIC.  ISC_LOG_DYNAMIC is used only to define
 593  *      channels, and explicit debugging level must be identified for
 594  *      isc_log_write() via ISC_LOG_DEBUG(level).
 595  *
 596  *\li   format != NULL.
 597  *
 598  * Ensures:
 599  *\li   The log message is written to every channel associated with the
 600  *      indicated category/module pair.
 601  *
 602  * Returns:
 603  *\li   Nothing.  Failure to log a message is not construed as a
 604  *      meaningful error.
 605  */
 606 void
 607 isc_log_vwrite(isc_log_t *lctx, isc_logcategory_t *category,
 608                isc_logmodule_t *module, int level,
 609                const char *format, va_list args)
 610
 611 ISC_FORMAT_PRINTF(5, 0);
 612
 613 /*%
 614  * Write a message to the log channels, pruning duplicates that occur within
 615  * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval).
 616  * This function is otherwise identical to isc_log_write().
 617  */
 618 void
 619 isc_log_write1(isc_log_t *lctx, isc_logcategory_t *category,
 620                isc_logmodule_t *module, int level, const char *format, ...)
 621
 622 ISC_FORMAT_PRINTF(5, 6);
 623
 624 /*%
 625  * Write a message to the log channels, pruning duplicates that occur within
 626  * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval).
 627  * This function is otherwise identical to isc_log_vwrite().
 628  */
 629 void
 630 isc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category,
 631                 isc_logmodule_t *module, int level, const char *format,
 632                 va_list args)
 633
 634 ISC_FORMAT_PRINTF(5, 0);
 635
 636 /*%
 637  * These are four internationalized versions of the isc_log_[v]write[1]
 638  * functions.
 639  *
 640  * The only difference is that they take arguments for a message
 641  * catalog, message set, and message number, all immediately preceding the
 642  * format argument.  The format argument becomes the default text, a la
 643  * isc_msgcat_get.  If the message catalog is NULL, no lookup is attempted
 644  * for a message -- which makes the message set and message number irrelevant,
 645  * and the non-internationalized call should have probably been used instead.
 646  *
 647  * Yes, that means there are now *eight* interfaces to logging a message.
 648  * Sheesh.   Make the madness stop!
 649  */
 650 /*@{*/
 651 void
 652 isc_log_iwrite(isc_log_t *lctx, isc_logcategory_t *category,
 653               isc_logmodule_t *module, int level,
 654               isc_msgcat_t *msgcat, int msgset, int message,
 655               const char *format, ...)
 656 ISC_FORMAT_PRINTF(8, 9);
 657
 658 void
 659 isc_log_ivwrite(isc_log_t *lctx, isc_logcategory_t *category,
 660                 isc_logmodule_t *module, int level,
 661                 isc_msgcat_t *msgcat, int msgset, int message,
 662                 const char *format, va_list args)
 663 ISC_FORMAT_PRINTF(8, 0);
 664
 665 void
 666 isc_log_iwrite1(isc_log_t *lctx, isc_logcategory_t *category,
 667                 isc_logmodule_t *module, int level,
 668                 isc_msgcat_t *msgcat, int msgset, int message,
 669                 const char *format, ...)
 670 ISC_FORMAT_PRINTF(8, 9);
 671
 672 void
 673 isc_log_ivwrite1(isc_log_t *lctx, isc_logcategory_t *category,
 674                  isc_logmodule_t *module, int level,
 675                  isc_msgcat_t *msgcat, int msgset, int message,
 676                  const char *format, va_list args)
 677 ISC_FORMAT_PRINTF(8, 0);
 678 /*@}*/
 679
 680 void
 681 isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level);
 682 /*%<
 683  * Set the debugging level used for logging.
 684  *
 685  * Notes:
 686  *\li   Setting the debugging level to 0 disables debugging log messages.
 687  *
 688  * Requires:
 689  *\li   lctx is a valid logging context.
 690  *
 691  * Ensures:
 692  *\li   The debugging level is set to the requested value.
 693  */
 694
 695 unsigned int
 696 isc_log_getdebuglevel(isc_log_t *lctx);
 697 /*%<
 698  * Get the current debugging level.
 699  *
 700  * Notes:
 701  *\li   This is provided so that a program can have a notion of
 702  *      "increment debugging level" or "decrement debugging level"
 703  *      without needing to keep track of what the current level is.
 704  *
 705  *\li   A return value of 0 indicates that debugging messages are disabled.
 706  *
 707  * Requires:
 708  *\li   lctx is a valid logging context.
 709  *
 710  * Ensures:
 711  *\li   The current logging debugging level is returned.
 712  */
 713
 714 isc_boolean_t
 715 isc_log_wouldlog(isc_log_t *lctx, int level);
 716 /*%<
 717  * Determine whether logging something to 'lctx' at 'level' would
 718  * actually cause something to be logged somewhere.
 719  *
 720  * If #ISC_FALSE is returned, it is guaranteed that nothing would
 721  * be logged, allowing the caller to omit unnecessary
 722  * isc_log_write() calls and possible message preformatting.
 723  */
 724
 725 void
 726 isc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval);
 727 /*%<
 728  * Set the interval over which duplicate log messages will be ignored
 729  * by isc_log_[v]write1(), in seconds.
 730  *
 731  * Notes:
 732  *\li   Increasing the duplicate interval from X to Y will not necessarily
 733  *      filter out duplicates of messages logged in Y - X seconds since the
 734  *      increase.  (Example: Message1 is logged at midnight.  Message2
 735  *      is logged at 00:01:00, when the interval is only 30 seconds, causing
 736  *      Message1 to be expired from the log message history.  Then the interval
 737  *      is increased to 3000 (five minutes) and at 00:04:00 Message1 is logged
 738  *      again.  It will appear the second time even though less than five
 739  *      passed since the first occurrence.
 740  *
 741  * Requires:
 742  *\li   lctx is a valid logging context.
 743  */
 744
 745 unsigned int
 746 isc_log_getduplicateinterval(isc_logconfig_t *lcfg);
 747 /*%<
 748  * Get the current duplicate filtering interval.
 749  *
 750  * Requires:
 751  *\li   lctx is a valid logging context.
 752  *
 753  * Returns:
 754  *\li   The current duplicate filtering interval.
 755  */
 756
 757 isc_result_t
 758 isc_log_settag(isc_logconfig_t *lcfg, const char *tag);
 759 /*%<
 760  * Set the program name or other identifier for #ISC_LOG_PRINTTAG.
 761  *
 762  * Requires:
 763  *\li   lcfg is a valid logging configuration.
 764  *
 765  * Notes:
 766  *\li   If this function has not set the tag to a non-NULL, non-empty value,
 767  *      then the #ISC_LOG_PRINTTAG channel flag will not print anything.
 768  *      Unlike some implementations of syslog on Unix systems, you *must* set
 769  *      the tag in order to get it logged.  It is not implicitly derived from
 770  *      the program name (which is pretty impossible to infer portably).
 771  *
 772  *\li   Setting the tag to NULL or the empty string will also cause the
 773  *      #ISC_LOG_PRINTTAG channel flag to not print anything.  If tag equals the
 774  *      empty string, calls to isc_log_gettag will return NULL.
 775  *
 776  * Returns:
 777  *\li   #ISC_R_SUCCESS  Success
 778  *\li   #ISC_R_NOMEMORY  Resource Limit: Out of memory
 779  *
 780  * XXXDCL when creating a new isc_logconfig_t, it might be nice if the tag
 781  * of the currently active isc_logconfig_t was inherited.  this does not
 782  * currently happen.
 783  */
 784
 785 char *
 786 isc_log_gettag(isc_logconfig_t *lcfg);
 787 /*%<
 788  * Get the current identifier printed with #ISC_LOG_PRINTTAG.
 789  *
 790  * Requires:
 791  *\li   lcfg is a valid logging configuration.
 792  *
 793  * Notes:
 794  *\li   Since isc_log_settag() will not associate a zero-length string
 795  *      with the logging configuration, attempts to do so will cause
 796  *      this function to return NULL.  However, a determined programmer
 797  *      will observe that (currently) a tag of length greater than zero
 798  *      could be set, and then modified to be zero length.
 799  *
 800  * Returns:
 801  *\li   A pointer to the current identifier, or NULL if none has been set.
 802  */
 803
 804 void
 805 isc_log_opensyslog(const char *tag, int options, int facility);
 806 /*%<
 807  * Initialize syslog logging.
 808  *
 809  * Notes:
 810  *\li   XXXDCL NT
 811  *      This is currently equivalent to openlog(), but is not going to remain
 812  *      that way.  In the meantime, the arguments are all identical to
 813  *      those used by openlog(3), as follows:
 814  *
 815  * \code
 816  *              tag: The string to use in the position of the program
 817  *                      name in syslog messages.  Most (all?) syslogs
 818  *                      will use basename(argv[0]) if tag is NULL.
 819  *
 820  *              options: LOG_CONS, LOG_PID, LOG_NDELAY ... whatever your
 821  *                      syslog supports.
 822  *
 823  *              facility: The default syslog facility.  This is irrelevant
 824  *                      since isc_log_write will ALWAYS use the channel's
 825  *                      declared facility.
 826  * \endcode
 827  *
 828  *\li   Zero effort has been made (yet) to accommodate systems with openlog()
 829  *      that only takes two arguments, or to identify valid syslog
 830  *      facilities or options for any given architecture.
 831  *
 832  *\li   It is necessary to call isc_log_opensyslog() to initialize
 833  *      syslogging on machines which do not support network connections to
 834  *      syslogd because they require a Unix domain socket to be used.  Since
 835  *      this is a chore to determine at run-time, it is suggested that it
 836  *      always be called by programs using the ISC logging system.
 837  *
 838  * Requires:
 839  *\li   Nothing.
 840  *
 841  * Ensures:
 842  *\li   openlog() is called to initialize the syslog system.
 843  */
 844
 845 void
 846 isc_log_closefilelogs(isc_log_t *lctx);
 847 /*%<
 848  * Close all open files used by #ISC_LOG_TOFILE channels.
 849  *
 850  * Notes:
 851  *\li   This function is provided for programs that want to use their own
 852  *      log rolling mechanism rather than the one provided internally.
 853  *      For example, a program that wanted to keep daily logs would define
 854  *      a channel which used #ISC_LOG_ROLLNEVER, then once a day would
 855  *      rename the log file and call isc_log_closefilelogs().
 856  *
 857  *\li   #ISC_LOG_TOFILEDESC channels are unaffected.
 858  *
 859  * Requires:
 860  *\li   lctx is a valid context.
 861  *
 862  * Ensures:
 863  *\li   The open files are closed and will be reopened when they are
 864  *      next needed.
 865  */
 866
 867 isc_logcategory_t *
 868 isc_log_categorybyname(isc_log_t *lctx, const char *name);
 869 /*%<
 870  * Find a category by its name.
 871  *
 872  * Notes:
 873  *\li   The string name of a category is not required to be unique.
 874  *
 875  * Requires:
 876  *\li   lctx is a valid context.
 877  *\li   name is not NULL.
 878  *
 879  * Returns:
 880  *\li   A pointer to the _first_ isc_logcategory_t structure used by "name".
 881  *
 882  *\li   NULL if no category exists by that name.
 883  */
 884
 885 isc_logmodule_t *
 886 isc_log_modulebyname(isc_log_t *lctx, const char *name);
 887 /*%<
 888  * Find a module by its name.
 889  *
 890  * Notes:
 891  *\li   The string name of a module is not required to be unique.
 892  *
 893  * Requires:
 894  *\li   lctx is a valid context.
 895  *\li   name is not NULL.
 896  *
 897  * Returns:
 898  *\li   A pointer to the _first_ isc_logmodule_t structure used by "name".
 899  *
 900  *\li   NULL if no module exists by that name.
 901  */
 902
 903 void
 904 isc_log_setcontext(isc_log_t *lctx);
 905 /*%<
 906  * Sets the context used by the libisc for logging.
 907  *
 908  * Requires:
 909  *\li   lctx be a valid context.
 910  */
 911
 912 ISC_LANG_ENDDECLS
 913
 914 #endif /* ISC_LOG_H */