2 * Copyright (C) 2004-2007, 2009 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2002 Internet Software Consortium.
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.
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.
18 /* $Id: log.h,v 1.59 2009/02/16 02:01:16 marka Exp $ */
23 /*! \file isc/log.h */
27 #include <syslog.h> /* XXXDCL NT */
29 #include <isc/formatcheck.h>
31 #include <isc/platform.h>
32 #include <isc/types.h>
36 * \brief Severity levels, patterned after Unix's syslog levels.
39 #define ISC_LOG_DEBUG(level) (level)
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().
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)
54 * \brief Destinations.
56 #define ISC_LOG_TONULL 1
57 #define ISC_LOG_TOSYSLOG 2
58 #define ISC_LOG_TOFILE 3
59 #define ISC_LOG_TOFILEDESC 4
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 */
78 * \brief Other options.
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.
84 #define ISC_LOG_ROLLINFINITE (-1)
85 #define ISC_LOG_ROLLNEVER (-2)
89 * \brief Used to name the categories used by a library.
91 * An array of isc_logcategory
92 * structures names each category, and the id value is initialized by calling
93 * isc_log_registercategories.
95 struct isc_logcategory {
101 * Similar to isc_logcategory, but for all the modules a library defines.
103 struct isc_logmodule {
109 * The isc_logfile structure is initialized as part of an isc_logdestination
110 * before calling isc_log_createchannel().
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.
117 * Setting maximum_size to zero implies no maximum.
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. */
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.
130 isc_offset_t maximum_size;
131 isc_boolean_t maximum_reached; /*%< Private. */
135 * Passed to isc_log_createchannel to define the attributes of either
136 * a stdio or a syslog log.
138 typedef union isc_logdestination {
140 int facility; /* XXXDCL NT */
141 } isc_logdestination_t;
145 * The built-in categories of libisc.
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.
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[];
158 * Do not log directly to DEFAULT. Use another category. When in doubt,
161 #define ISC_LOGCATEGORY_DEFAULT (&isc_categories[0])
162 #define ISC_LOGCATEGORY_GENERAL (&isc_categories[1])
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])
174 isc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp);
176 * Establish a new logging context, with default channels.
179 *\li isc_log_create() calls isc_logconfig_create(), so see its comment
180 * below for more information.
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.
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.
195 *\li #ISC_R_SUCCESS Success
196 *\li #ISC_R_NOMEMORY Resource limit: Out of memory
200 isc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp);
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.
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.
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.
219 *\li Four default channels are established:
222 * - log to syslog's daemon facility #ISC_LOG_INFO or higher
224 * - log to stderr #ISC_LOG_INFO or higher
226 * - log to stderr #ISC_LOG_DEBUG dynamically
232 *\li lctx is a valid logging context.
233 *\li lcftp is not null and *lcfgp is null.
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.
241 *\li #ISC_R_SUCCESS Success
242 *\li #ISC_R_NOMEMORY Resource limit: Out of memory
246 isc_logconfig_get(isc_log_t *lctx);
248 * Returns a pointer to the configuration currently in use by the log context.
251 *\li lctx is a valid context.
254 *\li The configuration pointer is non-null.
257 *\li The configuration pointer.
261 isc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg);
263 * Associate a new configuration with a logging context.
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.
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.
278 *\li Future calls to isc_log_write will use the new configuration.
281 *\li #ISC_R_SUCCESS Success
282 *\li #ISC_R_NOMEMORY Resource limit: Out of memory
286 isc_log_destroy(isc_log_t **lctxp);
288 * Deallocate the memory associated with a logging context.
291 *\li *lctx is a valid logging context.
294 *\li All of the memory associated with the logging context is returned
295 * to the free memory pool.
297 *\li Any open files are closed.
299 *\li The logging context is marked as invalid.
303 isc_logconfig_destroy(isc_logconfig_t **lcfgp);
305 * Destroy a logging configuration.
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.
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.
317 *\li All memory allocated for the configuration is freed.
319 *\li The configuration is marked as invalid.
323 isc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]);
325 * Identify logging categories a library will use.
328 *\li A category should only be registered once, but no mechanism enforces
331 *\li The end of the categories array is identified by a NULL name.
333 *\li Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not
334 * be altered or destroyed after isc_log_registercategories().
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.
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.
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.
351 *\li lctx is a valid logging context.
352 *\li categories != NULL.
353 *\li categories[0].name != NULL.
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().
361 isc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]);
363 * Identify logging categories a library will use.
366 *\li A module should only be registered once, but no mechanism enforces
369 *\li The end of the modules array is identified by a NULL name.
371 *\li Because the name is used by #ISC_LOG_PRINTMODULE, it should not
372 * be altered or destroyed after isc_log_registermodules().
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.
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.
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.
389 *\li lctx is a valid logging context.
390 *\li modules != NULL.
391 *\li modules[0].name != NULL;
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().
399 isc_log_createchannel(isc_logconfig_t *lcfg, const char *name,
400 unsigned int type, int level,
401 const isc_logdestination_t *destination,
404 * Specify the parameters of a logging channel.
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().
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.
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.
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.)
428 *\li Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is allowed,
429 * but probably not what you wanted to do.
431 * #ISC_LOG_DEBUGONLY will mark the channel as usable only when the
432 * debug level of the logging context (see isc_log_setdebuglevel)
436 *\li lcfg is a valid logging configuration.
438 *\li name is not NULL.
440 *\li type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or
443 *\li destination is not NULL unless type is #ISC_LOG_TONULL.
445 *\li level is >= #ISC_LOG_CRITICAL (the most negative logging level).
447 *\li flags does not include any bits aside from the ISC_LOG_PRINT* bits
448 * or #ISC_LOG_DEBUGONLY.
452 * A channel with the given name is usable with
453 * isc_log_usechannel().
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
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()
468 isc_log_usechannel(isc_logconfig_t *lcfg, const char *name,
469 const isc_logcategory_t *category,
470 const isc_logmodule_t *module);
472 * Associate a named logging channel with a category and module that
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.
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.
487 *\li If category is NULL, then the channel is associated with the indicated
488 * module for all known categories (including the "default" category).
490 *\li If module is NULL, then the channel is associated with every module
491 * that uses that category.
493 *\li Passing both category and module as NULL would make every log message
494 * use the indicated channel.
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.
503 *\li lcfg is a valid logging configuration.
505 *\li category is NULL or has an id that is in the range of known ids.
507 * module is NULL or has an id that is in the range of known ids.
511 * The channel will be used by the indicated category/module
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.
526 *\li #ISC_R_SUCCESS Success
527 *\li #ISC_R_NOMEMORY Resource limit: Out of memory
530 /* Attention: next four comments PRECEED code */
533 * Write a message to the log channels.
536 *\li Log messages containing natural language text should be logged with
537 * isc_log_iwrite() to allow for localization.
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
543 *\li The format argument is a printf(3) string, with additional arguments
547 *\li lctx is a valid logging context.
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().
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).
560 *\li The log message is written to every channel associated with the
561 * indicated category/module pair.
564 *\li Nothing. Failure to log a message is not construed as a
568 isc_log_write(isc_log_t *lctx, isc_logcategory_t *category,
569 isc_logmodule_t *module, int level,
570 const char *format, ...)
572 ISC_FORMAT_PRINTF(5, 6);
575 * Write a message to the log channels.
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
582 *\li The format argument is a printf(3) string, with additional arguments
586 *\li lctx is a valid logging context.
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().
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).
599 *\li The log message is written to every channel associated with the
600 * indicated category/module pair.
603 *\li Nothing. Failure to log a message is not construed as a
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)
611 ISC_FORMAT_PRINTF(5, 0);
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().
619 isc_log_write1(isc_log_t *lctx, isc_logcategory_t *category,
620 isc_logmodule_t *module, int level, const char *format, ...)
622 ISC_FORMAT_PRINTF(5, 6);
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().
630 isc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category,
631 isc_logmodule_t *module, int level, const char *format,
634 ISC_FORMAT_PRINTF(5, 0);
637 * These are four internationalized versions of the isc_log_[v]write[1]
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.
647 * Yes, that means there are now *eight* interfaces to logging a message.
648 * Sheesh. Make the madness stop!
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);
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);
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);
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);
681 isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level);
683 * Set the debugging level used for logging.
686 *\li Setting the debugging level to 0 disables debugging log messages.
689 *\li lctx is a valid logging context.
692 *\li The debugging level is set to the requested value.
696 isc_log_getdebuglevel(isc_log_t *lctx);
698 * Get the current debugging level.
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.
705 *\li A return value of 0 indicates that debugging messages are disabled.
708 *\li lctx is a valid logging context.
711 *\li The current logging debugging level is returned.
715 isc_log_wouldlog(isc_log_t *lctx, int level);
717 * Determine whether logging something to 'lctx' at 'level' would
718 * actually cause something to be logged somewhere.
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.
726 isc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval);
728 * Set the interval over which duplicate log messages will be ignored
729 * by isc_log_[v]write1(), in seconds.
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.
742 *\li lctx is a valid logging context.
746 isc_log_getduplicateinterval(isc_logconfig_t *lcfg);
748 * Get the current duplicate filtering interval.
751 *\li lctx is a valid logging context.
754 *\li The current duplicate filtering interval.
758 isc_log_settag(isc_logconfig_t *lcfg, const char *tag);
760 * Set the program name or other identifier for #ISC_LOG_PRINTTAG.
763 *\li lcfg is a valid logging configuration.
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).
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.
777 *\li #ISC_R_SUCCESS Success
778 *\li #ISC_R_NOMEMORY Resource Limit: Out of memory
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
786 isc_log_gettag(isc_logconfig_t *lcfg);
788 * Get the current identifier printed with #ISC_LOG_PRINTTAG.
791 *\li lcfg is a valid logging configuration.
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.
801 *\li A pointer to the current identifier, or NULL if none has been set.
805 isc_log_opensyslog(const char *tag, int options, int facility);
807 * Initialize syslog logging.
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:
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.
820 * options: LOG_CONS, LOG_PID, LOG_NDELAY ... whatever your
823 * facility: The default syslog facility. This is irrelevant
824 * since isc_log_write will ALWAYS use the channel's
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.
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.
842 *\li openlog() is called to initialize the syslog system.
846 isc_log_closefilelogs(isc_log_t *lctx);
848 * Close all open files used by #ISC_LOG_TOFILE channels.
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().
857 *\li #ISC_LOG_TOFILEDESC channels are unaffected.
860 *\li lctx is a valid context.
863 *\li The open files are closed and will be reopened when they are
868 isc_log_categorybyname(isc_log_t *lctx, const char *name);
870 * Find a category by its name.
873 *\li The string name of a category is not required to be unique.
876 *\li lctx is a valid context.
877 *\li name is not NULL.
880 *\li A pointer to the _first_ isc_logcategory_t structure used by "name".
882 *\li NULL if no category exists by that name.
886 isc_log_modulebyname(isc_log_t *lctx, const char *name);
888 * Find a module by its name.
891 *\li The string name of a module is not required to be unique.
894 *\li lctx is a valid context.
895 *\li name is not NULL.
898 *\li A pointer to the _first_ isc_logmodule_t structure used by "name".
900 *\li NULL if no module exists by that name.
904 isc_log_setcontext(isc_log_t *lctx);
906 * Sets the context used by the libisc for logging.
909 *\li lctx be a valid context.
914 #endif /* ISC_LOG_H */