log.h

bind-3.2.

isc_log_usechannel(isc_logconfig_t *lcfg, const char *name,
		   const isc_logcategory_t *category,
		   const isc_logmodule_t *module);
/*
 * Associate a named logging channel with a category and module that
 * will use it.
 *
 * Notes:
 *	The name is searched for linearly in the set of known channel names
 *	until a match is found.  (Note the performance impact of a very large
 *	number of named channels.)  When multiple channels of the same
 *	name are defined, the most recent definition is found.
 *
 *	Specifing a very large number of channels for a category will have
 *	a moderate impact on performance in isc_log_write(), as each
 *	call looks up the category for the start of a linked list, which
 *	it follows all the way to the end to find matching modules.  The
 *	test for matching modules is  integral, though.
 *
 *	If category is NULL, then the channel is associated with the indicated
 *	module for all known categories (including the "default" category).
 *
 *	If module is NULL, then the channel is associated with every module
 *	that uses that category.
 *
 *	Passing both category and module as NULL would make every log message
 *	use the indicated channel.
 *
 * 	Specifying a channel that is ISC_LOG_TONULL for a category/module pair
 *	has no effect on any other channels associated with that pair,
 *	regardless of ordering.  Thus you cannot use it to "mask out" one
 *	category/module pair when you have specified some other channel that
 * 	is also used by that category/module pair.
 *
 * Requires:
 *	lcfg is a valid logging configuration.
 *
 *	category is NULL or has an id that is in the range of known ids.
 *
 *	module is NULL or has an id that is in the range of known ids.
 *
 * Ensures:
 *	ISC_R_SUCCESS
 *		The channel will be used by the indicated category/module
 *		arguments.
 *
 *	ISC_R_NOMEMORY
 *		If assignment for a specific category has been requested,
 *		the channel has not been associated with the indicated
 *		category/module arguments and no additional memory is
 *		used by the logging context.
 *
 *		If assignment for all categories has been requested
 *		then _some_ may have succeeded (starting with category
 *		"default" and progressing through the order of categories
 *		passed to isc_log_registercategories) and additional memory
 *		is being used by whatever assignments succeeded.
 *
 * Returns:
 *	ISC_R_SUCCESS	Success
 *	ISC_R_NOMEMORY	Resource limit: Out of memory
 */

void
isc_log_write(isc_log_t *lctx, isc_logcategory_t *category,
	      isc_logmodule_t *module, int level,
	      const char *format, ...)
ISC_FORMAT_PRINTF(5, 6);
/*
 * Write a message to the log channels.
 *
 * Notes:
 *	Log messages containing natural language text should be logged with
 *	isc_log_iwrite() to allow for localization.
 *
 *	lctx can be NULL; this is allowed so that programs which use
 *	libraries that use the ISC logging system are not required to
 *	also use it.
 *
 *	The format argument is a printf(3) string, with additional arguments
 *	as necessary.
 *
 * Requires:
 *	lctx is a valid logging context.
 *
 *	The category and module arguments must have ids that are in the
 *	range of known ids, as estabished by isc_log_registercategories()
 *	and isc_log_registermodules().
 *
 *	level != ISC_LOG_DYNAMIC.  ISC_LOG_DYNAMIC is used only to define
 *	channels, and explicit debugging level must be identified for
 *	isc_log_write() via ISC_LOG_DEBUG(level).
 *
 *	format != NULL.
 *
 * Ensures:
 *	The log message is written to every channel associated with the
 *	indicated category/module pair.
 *
 * Returns:
 *	Nothing.  Failure to log a message is not construed as a
 *	meaningful error.
 */

void
isc_log_vwrite(isc_log_t *lctx, isc_logcategory_t *category,
	       isc_logmodule_t *module, int level,
	       const char *format, va_list args)
ISC_FORMAT_PRINTF(5, 0);
/*
 * Write a message to the log channels.
 *
 * Notes:
 *	lctx can be NULL; this is allowed so that programs which use
 *	libraries that use the ISC logging system are not required to
 *	also use it.
 *
 *	The format argument is a printf(3) string, with additional arguments
 *	as necessary.
 *
 * Requires:
 *	lctx is a valid logging context.
 *
 *	The category and module arguments must have ids that are in the
 *	range of known ids, as estabished by isc_log_registercategories()
 *	and isc_log_registermodules().
 *
 *	level != ISC_LOG_DYNAMIC.  ISC_LOG_DYNAMIC is used only to define
 *	channels, and explicit debugging level must be identified for
 *	isc_log_write() via ISC_LOG_DEBUG(level).
 *
 *	format != NULL.
 *
 * Ensures:
 *	The log message is written to every channel associated with the
 *	indicated category/module pair.
 *
 * Returns:
 *	Nothing.  Failure to log a message is not construed as a
 *	meaningful error.
 */

void
isc_log_write1(isc_log_t *lctx, isc_logcategory_t *category,
	       isc_logmodule_t *module, int level, const char *format, ...)
ISC_FORMAT_PRINTF(5, 6);
/*
 * Write a message to the log channels, pruning duplicates that occur within
 * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval).
 * This function is otherwise identical to isc_log_write().
 */

void
isc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category,
		isc_logmodule_t *module, int level, const char *format,
		va_list args)
ISC_FORMAT_PRINTF(5, 0);
/*
 * Write a message to the log channels, pruning duplicates that occur within
 * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval).
 * This function is otherwise identical to isc_log_vwrite().
 */

void
isc_log_iwrite(isc_log_t *lctx, isc_logcategory_t *category,
	      isc_logmodule_t *module, int level,
	      isc_msgcat_t *msgcat, int msgset, int message,
	      const char *format, ...)
ISC_FORMAT_PRINTF(8, 9);

void
isc_log_ivwrite(isc_log_t *lctx, isc_logcategory_t *category,
		isc_logmodule_t *module, int level,
		isc_msgcat_t *msgcat, int msgset, int message,
		const char *format, va_list args)
ISC_FORMAT_PRINTF(8, 0);

void
isc_log_iwrite1(isc_log_t *lctx, isc_logcategory_t *category,
		isc_logmodule_t *module, int level,
		isc_msgcat_t *msgcat, int msgset, int message,
		const char *format, ...)
ISC_FORMAT_PRINTF(8, 9);

void
isc_log_ivwrite1(isc_log_t *lctx, isc_logcategory_t *category,
		 isc_logmodule_t *module, int level,
		 isc_msgcat_t *msgcat, int msgset, int message,
		 const char *format, va_list args)
ISC_FORMAT_PRINTF(8, 0);
/*
 * These are four internationalized versions of the the isc_log_[v]write[1]
 * functions.  The only difference is that they take arguments for a message
 * catalog, message set, and message number, all immediately preceding the
 * format argument.  The format argument becomes the default text, a la
 * isc_msgcat_get.  If the message catalog is NULL, no lookup is attempted
 * for a message -- which makes the message set and message number irrelevant,
 * and the non-internationalized call should have probably been used instead.
 *
 * Yes, that means there are now *eight* interfaces to logging a message.
 * Sheesh.   Make the madness stop!
 */

void
isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level);
/*
 * Set the debugging level used for logging.
 *
 * Notes:
 *	Setting the debugging level to 0 disables debugging log messages.
 *
 * Requires:
 *	lctx is a valid logging context.
 *
 * Ensures:
 *	The debugging level is set to the requested value.
 */

unsigned int
isc_log_getdebuglevel(isc_log_t *lctx);
/*
 * Get the current debugging level.
 *
 * Notes:
 *	This is provided so that a program can have a notion of
 *	"increment debugging level" or "decrement debugging level"
 *	without needing to keep track of what the current level is.
 *
 *	A return value of 0 indicates that debugging messages are disabled.
 *
 * Requires:
 *	lctx is a valid logging context.
 *
 * Ensures:
 *	The current logging debugging level is returned.
 */

isc_boolean_t
isc_log_wouldlog(isc_log_t *lctx, int level);
/*
 * Determine whether logging something to 'lctx' at 'level' would
 * actually cause something to be logged somewhere.
 *
 * If ISC_FALSE is returned, it is guaranteed that nothing would
 * be logged, allowing the caller to omit unnecessary
 * isc_log_write() calls and possible message preformatting.
 */

void
isc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval);
/*
 * Set the interval over which duplicate log messages will be ignored
 * by isc_log_[v]write1(), in seconds.
 *
 * Notes:
 *	Increasing the duplicate interval from X to Y will not necessarily
 *	filter out duplicates of messages logged in Y - X seconds since the
 *	increase.  (Example: Message1 is logged at midnight.  Message2
 *	is logged at 00:01:00, when the interval is only 30 seconds, causing
 *	Message1 to be expired from the log message history.  Then the interval
 *	is increased to 3000 (five minutes) and at 00:04:00 Message1 is logged
 *	again.  It will appear the second time even though less than five
 *	passed since the first occurrence.
 *
 * Requires:
 *	lctx is a valid logging context.
 */

unsigned int
isc_log_getduplicateinterval(isc_logconfig_t *lcfg);
/*
 * Get the current duplicate filtering interval.
 *
 * Requires:
 *	lctx is a valid logging context.
 *
 * Returns:
 *	The current duplicate filtering interval.
 */

isc_result_t
isc_log_settag(isc_logconfig_t *lcfg, const char *tag);
/*
 * Set the program name or other identifier for ISC_LOG_PRINTTAG.
 *
 * Requires:
 *	lcfg is a valid logging configuration.
 *
 * Notes:
 *	If this function has not set the tag to a non-NULL, non-empty value,
 *	then the ISC_LOG_PRINTTAG channel flag will not print anything.
 *	Unlike some implementations of syslog on Unix systems, you *must* set
 *	the tag in order to get it logged.  It is not implicitly derived from
 *	the program name (which is pretty impossible to infer portably).
 *
 *	Setting the tag to NULL or the empty string will also cause the
 *	ISC_LOG_PRINTTAG channel flag to not print anything.  If tag equals the
 *	empty string, calls to isc_log_gettag will return NULL.
 *
 *	Because the name is used by ISC_LOG_PRINTTAG, it should not be
 *	altered or destroyed after isc_log_settag().
 *
 * Returns:
 *	ISC_R_SUCCESS	Success
 *	ISC_R_NOMEMORY  Resource Limit: Out of memory
 *
 * XXXDCL when creating a new isc_logconfig_t, it might be nice if the tag
 * of the currently active isc_logconfig_t was inherited.  this does not
 * currently happen.
 */

char *
isc_log_gettag(isc_logconfig_t *lcfg);
/*
 * Get the current identifier printed with ISC_LOG_PRINTTAG.
 *
 * Requires:
 *	lcfg is a valid logging configuration.
 *
 * Notes:
 *	Since isc_log_settag() will not associate a zero-length string
 *	with the logging configuration, attempts to do so will cause
 *	this function to return NULL.  However, a determined programmer
 *	will observe that (currently) a tag of length greater than zero
 *	could be set, and then modified to be zero length.
 *
 * Returns:
 *	A pointer to the current identifier, or NULL if none has been set.
 */

void
isc_log_opensyslog(const char *tag, int options, int facility);
/*
 * Initialize syslog logging.
 *
 * Notes:
 *	XXXDCL NT
 *	This is currently equivalent to openlog(), but is not going to remain
 *	that way.  In the meantime, the arguments are all identical to
 *	those used by openlog(3), as follows:
 *		tag: The string to use in the position of the program
 *			name in syslog messages.  Most (all?) syslogs
 *			will use basename(argv[0]) if tag is NULL.
 *
 *		options: LOG_CONS, LOG_PID, LOG_NDELAY ... whatever your
 *			syslog supports.
 *
 *		facility: The default syslog facility.  This is irrelevant
 *			since isc_log_write will ALWAYS use the channel's
 *			declared facility.
 *
 *	Zero effort has been made (yet) to accomodate systems with openlog()
 *	that only takes two arguments, or to identify valid syslog
 *	facilities or options for any given architecture.
 *
 *	It is necessary to call isc_log_opensyslog() to initialize
 *	syslogging on machines which do not support network connections to
 *	syslogd because they require a Unix domain socket to be used.  Since
 *	this is a chore to determine at run-time, it is suggested that it
 *	always be called by programs using the ISC logging system.
 *
 * Requires:
 *	Nothing.
 *
 * Ensures:
 *	openlog() is called to initialize the syslog system.
 */

void
isc_log_closefilelogs(isc_log_t *lctx);
/*
 * Close all open files used by ISC_LOG_TOFILE channels.
 *
 * Notes:
 *	This function is provided for programs that want to use their own
 *	log rolling mechanism rather than the one provided internally.
 *	For example, a program that wanted to keep daily logs would define
 *	a channel which used ISC_LOG_ROLLNEVER, then once a day would
 *	rename the log file and call isc_log_closefilelogs().
 *
 *	ISC_LOG_TOFILEDESC channels are unaffected.
 *
 * Requires:
 *	lctx is a valid context.
 *
 * Ensures:
 *	The open files are closed and will be reopened when they are
 *	next needed.
 */

isc_logcategory_t *
isc_log_categorybyname(isc_log_t *lctx, const char *name);
/*
 * Find a category by its name.
 *
 * Notes:
 *	The string name of a category is not required to be unique.
 *
 * Requires:
 *	lctx is a valid context.
 *	name is not NULL.
 *
 * Returns:
 *	A pointer to the _first_ isc_logcategory_t structure used by "name".
 *
 *	NULL if no category exists by that name.
 */

isc_logmodule_t *
isc_log_modulebyname(isc_log_t *lctx, const char *name);
/*
 * Find a module by its name.
 *
 * Notes:
 *	The string name of a module is not required to be unique.
 *
 * Requires:
 *	lctx is a valid context.
 *	name is not NULL.
 *
 * Returns:
 *	A pointer to the _first_ isc_logmodule_t structure used by "name".
 *
 *	NULL if no module exists by that name.
 */

void
isc_log_setcontext(isc_log_t *lctx);
/*
 * Sets the context used by the libisc for logging.
 *
 * Requires:
 *	lctx be a valid context.
 */

ISC_LANG_ENDDECLS

#endif /* ISC_LOG_H */