"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.16.7/lib/isc/include/isc/log.h" (4 Sep 2020, 26498 Bytes) of package /linux/misc/dns/bind9/9.16.7/bind-9.16.7.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "log.h" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 9.17.1_vs_9.17.2.

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