log.c File Reference

#include <config.h>
#include <errno.h>
#include <stdlib.h>
#include <limits.h>
#include <time.h>
#include <sys/types.h>
#include <isc/dir.h>
#include <isc/file.h>
#include <isc/log.h>
#include <isc/magic.h>
#include <isc/mem.h>
#include <isc/msgs.h>
#include <isc/print.h>
#include <isc/stat.h>
#include <isc/stdio.h>
#include <isc/string.h>
#include <isc/time.h>
#include <isc/util.h>

Go to the source code of this file.

Data Structures
struct	isc_logchannel
struct	isc_logchannellist
struct	isc_logmessage
struct	isc_logconfig
struct	isc_log
Defines
#define	LCTX_MAGIC   ISC_MAGIC('L', 'c', 't', 'x')
#define	VALID_CONTEXT(lctx)   ISC_MAGIC_VALID(lctx, LCTX_MAGIC)
#define	LCFG_MAGIC   ISC_MAGIC('L', 'c', 'f', 'g')
#define	VALID_CONFIG(lcfg)   ISC_MAGIC_VALID(lcfg, LCFG_MAGIC)
#define	LOG_BUFFER_SIZE   (8 * 1024)
#define	PATH_MAX   1024
#define	FACILITY(channel)   (channel->destination.facility)
#define	FILE_NAME(channel)   (channel->destination.file.name)
#define	FILE_STREAM(channel)   (channel->destination.file.stream)
#define	FILE_VERSIONS(channel)   (channel->destination.file.versions)
#define	FILE_MAXSIZE(channel)   (channel->destination.file.maximum_size)
#define	FILE_MAXREACHED(channel)   (channel->destination.file.maximum_reached)
Typedefs
typedef struct isc_logchannel	isc_logchannel_t
typedef struct isc_logchannellist	isc_logchannellist_t
typedef struct isc_logmessage	isc_logmessage_t
Functions
static isc_result_t	assignchannel (isc_logconfig_t *lcfg, unsigned int category_id, const isc_logmodule_t *module, isc_logchannel_t *channel)
static isc_result_t	sync_channellist (isc_logconfig_t *lcfg)
static isc_result_t	greatest_version (isc_logchannel_t *channel, int *greatest)
static isc_result_t	roll_log (isc_logchannel_t *channel)
static void	isc_log_doit (isc_log_t *lctx, isc_logcategory_t *category, isc_logmodule_t *module, int level, isc_boolean_t write_once, isc_msgcat_t *msgcat, int msgset, int msg, const char *format, va_list args) ISC_FORMAT_PRINTF(9
isc_result_t	isc_log_create (isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp)
	Establish a new logging context, with default channels.
isc_result_t	isc_logconfig_create (isc_log_t *lctx, isc_logconfig_t **lcfgp)
	Create the data structure that holds all of the configurable information about where messages are actually supposed to be sent -- the information that could changed based on some configuration file, as opposed to the the category/module specification of isc_log_[v]write[1] that is compiled into a program, or the debug_level which is dynamic state information.
isc_logconfig_t *	isc_logconfig_get (isc_log_t *lctx)
	Returns a pointer to the configuration currently in use by the log context.
isc_result_t	isc_logconfig_use (isc_log_t *lctx, isc_logconfig_t *lcfg)
	Associate a new configuration with a logging context.
void	isc_log_destroy (isc_log_t **lctxp)
	Deallocate the memory associated with a logging context.
void	isc_logconfig_destroy (isc_logconfig_t **lcfgp)
	Destroy a logging configuration.
void	isc_log_registercategories (isc_log_t *lctx, isc_logcategory_t categories[])
	Identify logging categories a library will use.
isc_logcategory_t *	isc_log_categorybyname (isc_log_t *lctx, const char *name)
	Find a category by its name.
void	isc_log_registermodules (isc_log_t *lctx, isc_logmodule_t modules[])
	Identify logging categories a library will use.
isc_logmodule_t *	isc_log_modulebyname (isc_log_t *lctx, const char *name)
	Find a module by its name.
isc_result_t	isc_log_createchannel (isc_logconfig_t *lcfg, const char *name, unsigned int type, int level, const isc_logdestination_t *destination, unsigned int flags)
	Specify the parameters of a logging channel.
isc_result_t	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.
void	isc_log_write (isc_log_t *lctx, isc_logcategory_t *category, isc_logmodule_t *module, int level, const char *format,...)
void	isc_log_vwrite (isc_log_t *lctx, isc_logcategory_t *category, isc_logmodule_t *module, int level, const char *format, va_list args)
void	isc_log_write1 (isc_log_t *lctx, isc_logcategory_t *category, isc_logmodule_t *module, int level, const char *format,...)
void	isc_log_vwrite1 (isc_log_t *lctx, isc_logcategory_t *category, isc_logmodule_t *module, int level, const char *format, va_list args)
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 msg, const char *format,...)
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 msg, const char *format, va_list args)
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 msg, const char *format,...)
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 msg, const char *format, va_list args)
void	isc_log_setcontext (isc_log_t *lctx)
	Sets the context used by the libisc for logging.
void	isc_log_setdebuglevel (isc_log_t *lctx, unsigned int level)
	Set the debugging level used for logging.
unsigned int	isc_log_getdebuglevel (isc_log_t *lctx)
	Get the current debugging level.
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.
unsigned int	isc_log_getduplicateinterval (isc_logconfig_t *lcfg)
	Get 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.
char *	isc_log_gettag (isc_logconfig_t *lcfg)
	Get the current identifier printed with ISC_LOG_PRINTTAG.
void	isc_log_opensyslog (const char *tag, int options, int facility)
	Initialize syslog logging.
void	isc_log_closefilelogs (isc_log_t *lctx)
	Close all open files used by ISC_LOG_TOFILE channels.
static isc_result_t	isc_log_open (isc_logchannel_t *channel)
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.
Variables
static const char *	log_level_strings []
static const int	syslog_map []
LIBISC_EXTERNAL_DATA isc_logcategory_t	isc_categories []
	The built-in categories of libisc.
LIBISC_EXTERNAL_DATA isc_logmodule_t	isc_modules []
static isc_logchannellist_t	default_channel
LIBISC_EXTERNAL_DATA isc_log_t *	isc_lctx = NULL

---

Detailed Description

Author:

Principal Authors: DCL

Definition in file log.c.

---

Define Documentation

#define LCTX_MAGIC   ISC_MAGIC('L', 'c', 't', 'x')

Definition at line 45 of file log.c.

Referenced by isc_log_create().

#define VALID_CONTEXT

(

lctx

)

ISC_MAGIC_VALID(lctx, LCTX_MAGIC)

Definition at line 46 of file log.c.

Referenced by isc___mem_putanddetach(), isc___mem_strdup(), isc__mempool_create(), isc_log_categorybyname(), isc_log_closefilelogs(), isc_log_destroy(), isc_log_doit(), isc_log_getdebuglevel(), isc_log_getduplicateinterval(), isc_log_modulebyname(), isc_log_registercategories(), isc_log_registermodules(), isc_log_setdebuglevel(), isc_logconfig_create(), isc_logconfig_get(), isc_logconfig_use(), isc_mem_setquota(), and isc_mem_stats().

#define LCFG_MAGIC   ISC_MAGIC('L', 'c', 'f', 'g')

Definition at line 48 of file log.c.

Referenced by isc_logconfig_create().

#define VALID_CONFIG

(

lcfg

)

ISC_MAGIC_VALID(lcfg, LCFG_MAGIC)

Definition at line 49 of file log.c.

Referenced by assignchannel(), isc_log_createchannel(), isc_log_gettag(), isc_log_setduplicateinterval(), isc_log_settag(), isc_log_usechannel(), isc_logconfig_destroy(), isc_logconfig_use(), and sync_channellist().

#define LOG_BUFFER_SIZE   (8 * 1024)

Definition at line 54 of file log.c.

#define PATH_MAX   1024

Definition at line 57 of file log.c.

Referenced by add_keydata_zone(), isc_file_sanitize(), loadkeyset(), opendb(), and roll_log().

#define FACILITY

(

channel

)

(channel->destination.facility)

Convenience macros.

Definition at line 252 of file log.c.

Referenced by isc_log_createchannel(), and isc_log_doit().

#define FILE_NAME

(

channel

)

(channel->destination.file.name)

Convenience macros.

Definition at line 253 of file log.c.

Referenced by greatest_version(), isc_log_createchannel(), isc_log_doit(), isc_log_open(), isc_logconfig_destroy(), and roll_log().

#define FILE_STREAM

(

channel

)

(channel->destination.file.stream)

Convenience macros.

Definition at line 254 of file log.c.

Referenced by isc_log_closefilelogs(), isc_log_createchannel(), isc_log_doit(), isc_log_open(), isc_log_setdebuglevel(), and isc_logconfig_destroy().

#define FILE_VERSIONS

(

channel

)

(channel->destination.file.versions)

Convenience macros.

Definition at line 255 of file log.c.

Referenced by isc_log_createchannel(), isc_log_doit(), isc_log_open(), and roll_log().

#define FILE_MAXSIZE

(

channel

)

(channel->destination.file.maximum_size)

Convenience macros.

Definition at line 256 of file log.c.

Referenced by isc_log_createchannel(), isc_log_doit(), and isc_log_open().

#define FILE_MAXREACHED

(

channel

)

(channel->destination.file.maximum_reached)

Convenience macros.

Definition at line 257 of file log.c.

Referenced by isc_log_createchannel(), and isc_log_doit().

---

Typedef Documentation

typedef struct isc_logchannel isc_logchannel_t

This is the structure that holds each named channel. A simple linked list chains all of the channels together, so an individual channel is found by doing strcmp()s with the names down the list. Their should be no performance penalty from this as it is expected that the number of named channels will be no more than a dozen or so, and name lookups from the head of the list are only done when isc_log_usechannel() is called, which should also be very infrequent.

Definition at line 69 of file log.c.

typedef struct isc_logchannellist isc_logchannellist_t

The logchannellist structure associates categories and modules with channels. First the appropriate channellist is found based on the category, and then each structure in the linked list is checked for a matching module. It is expected that the number of channels associated with any given category will be very short, no more than three or four in the more unusual cases.

Definition at line 88 of file log.c.

typedef struct isc_logmessage isc_logmessage_t

This structure is used to remember messages for pruning via isc_log_[v]write1().

Definition at line 100 of file log.c.

---

Function Documentation

static isc_result_t assignchannel	(	isc_logconfig_t *	lcfg,
		unsigned int	category_id,
		const isc_logmodule_t *	module,
		isc_logchannel_t *	channel
	)			[static]

Forward declarations.

Definition at line 1058 of file log.c.

References isc_logchannellist::channel, isc_logmodule::id, ISC_LIST_INITANDPREPEND, ISC_LOG_DYNAMIC, ISC_LOG_TONULL, isc_mem_get, ISC_R_NOMEMORY, ISC_R_SUCCESS, ISC_TRUE, isc_logconfig::lctx, isc_logchannel::level, isc_log::mctx, isc_logchannellist::module, isc_log::module_count, REQUIRE, sync_channellist(), isc_logchannel::type, and VALID_CONFIG.

Referenced by isc_log_usechannel().

static isc_result_t sync_channellist

(

isc_logconfig_t *

lcfg

)

[static]

Definition at line 1109 of file log.c.

References isc_log::category_count, ISC_LIST, isc_mem_get, isc_mem_put, ISC_R_NOMEMORY, ISC_R_SUCCESS, isc_logconfig::lctx, isc_log::mctx, REQUIRE, and VALID_CONFIG.

Referenced by assignchannel(), isc_log_create(), and isc_logconfig_use().

static isc_result_t greatest_version	(	isc_logchannel_t *	channel,
		int *	greatest
	)			[static]

Definition at line 1146 of file log.c.

References basenamelen(), DE_CONST, isc_dir::entry, FILE_NAME, isc_dir_close(), isc_dir_init(), isc_dir_open(), isc_dir_read(), ISC_LOG_TOFILE, ISC_R_SUCCESS, isc_direntry::length, isc_direntry::name, REQUIRE, isc_logchannel::type, and version.

Referenced by roll_log().

static isc_result_t roll_log

(

isc_logchannel_t *

channel

)

[static]

Definition at line 1217 of file log.c.

References FILE_NAME, FILE_VERSIONS, greatest_version(), isc_file_remove(), isc_file_rename(), ISC_LOG_ROLLINFINITE, ISC_LOG_ROLLNEVER, ISC_R_FILENOTFOUND, ISC_R_NOSPACE, ISC_R_SUCCESS, isc_result_totext(), and PATH_MAX.

Referenced by isc_log_open().

static void isc_log_doit	(	isc_log_t *	lctx,
		isc_logcategory_t *	category,
		isc_logmodule_t *	module,
		int	level,
		isc_boolean_t	write_once,
		isc_msgcat_t *	msgcat,
		int	msgset,
		int	msg,
		const char *	format,
		va_list	args
	)			[static]

Definition at line 1407 of file log.c.

References isc_log::buffer, isc_log::category_count, isc_logchannellist::channel, isc_log::debug_level, FACILITY, FILE_MAXREACHED, FILE_MAXSIZE, FILE_NAME, FILE_STREAM, FILE_VERSIONS, isc_logchannel::flags, isc_logmodule::id, isc_logcategory::id, INSIST, ISC_FALSE, isc_interval_set(), ISC_LINK_INIT, ISC_LIST_APPEND, ISC_LIST_HEAD, ISC_LIST_NEXT, ISC_LIST_UNLINK, ISC_LOG_BUFFERED, ISC_LOG_CRITICAL, ISC_LOG_DEBUGONLY, ISC_LOG_DYNAMIC, isc_log_open(), ISC_LOG_OPENERR, ISC_LOG_PRINTCATEGORY, ISC_LOG_PRINTLEVEL, ISC_LOG_PRINTMODULE, ISC_LOG_PRINTPREFIX, ISC_LOG_PRINTTAG, ISC_LOG_PRINTTIME, ISC_LOG_ROLLNEVER, ISC_LOG_TOFILE, ISC_LOG_TOFILEDESC, ISC_LOG_TONULL, ISC_LOG_TOSYSLOG, isc_log_wouldlog(), isc_mem_get, isc_mem_put, ISC_MSG_LEVEL, isc_msgcat_get(), ISC_MSGSET_LOG, ISC_R_MAXSIZE, ISC_R_SUCCESS, isc_result_totext(), ISC_TF, isc_time_compare(), isc_time_formattimestamp(), isc_time_subtract(), ISC_TRUE, isc_logchannel::level, isc_log::lock, LOCK, log_level_strings, isc_log::logconfig, isc_log::mctx, isc_logchannellist::module, isc_log::module_count, isc_logmodule::name, isc_logcategory::name, printtime(), REQUIRE, isc_logmessage::text, isc_logmessage::time, TIME_NOW, isc_logchannel::type, UNLOCK, and VALID_CONTEXT.

Referenced by isc_log_ivwrite(), isc_log_ivwrite1(), isc_log_iwrite(), isc_log_iwrite1(), isc_log_vwrite(), isc_log_vwrite1(), isc_log_write(), and isc_log_write1().

isc_result_t isc_log_create	(	isc_mem_t *	mctx,
		isc_log_t **	lctxp,
		isc_logconfig_t **	lcfgp
	)

Establish a new logging context, with default channels.

Notes:

• isc_log_create() calls isc_logconfig_create(), so see its comment below for more information.

Requires:

• mctx is a valid memory context.
• lctxp is not null and *lctxp is null.
• lcfgp is null or lcfgp is not null and *lcfgp is null.

Ensures:

• *lctxp will point to a valid logging context if all of the necessary memory was allocated, or NULL otherwise.
• *lcfgp will point to a valid logging configuration if all of the necessary memory was allocated, or NULL otherwise.
• On failure, no additional memory is allocated.

Returns:

• ISC_R_SUCCESS Success
• ISC_R_NOMEMORY Resource limit: Out of memory

Definition at line 268 of file log.c.

References isc_log::categories, isc_log::category_count, isc_log::debug_level, ISC_LIST_INIT, isc_log_destroy(), isc_log_registercategories(), isc_log_registermodules(), isc_logconfig_create(), isc_logconfig_destroy(), isc_mem_attach(), isc_mem_get, isc_mem_putanddetach, isc_mutex_init, ISC_R_NOMEMORY, ISC_R_SUCCESS, LCTX_MAGIC, isc_log::lock, isc_log::logconfig, isc_log::magic, isc_log::mctx, isc_log::module_count, isc_log::modules, REQUIRE, and sync_channellist().

Referenced by dns_client_create(), dns_test_begin(), isc_test_begin(), main(), ns_log_init(), setup_libs(), setup_logging(), and setup_system().

isc_result_t isc_logconfig_create	(	isc_log_t *	lctx,
		isc_logconfig_t **	lcfgp
	)

Create the data structure that holds all of the configurable information about where messages are actually supposed to be sent -- the information that could changed based on some configuration file, as opposed to the the category/module specification of isc_log_[v]write[1] that is compiled into a program, or the debug_level which is dynamic state information.

Notes:

• It is necessary to specify the logging context the configuration will be used with because the number of categories and modules needs to be known in order to set the configuration. However, the configuration is not used by the logging context until the isc_logconfig_use function is called.

• The memory context used for operations that allocate memory for the configuration is that of the logging context, as specified in the isc_log_create call.

• Four default channels are established:

   *	    	default_syslog
   *		 - log to syslog's daemon facility #ISC_LOG_INFO or higher
   *		default_stderr
   *		 - log to stderr #ISC_LOG_INFO or higher
   *		default_debug
   *		 - log to stderr #ISC_LOG_DEBUG dynamically
   *		null
   *		 - log nothing
   *

Requires:

• lctx is a valid logging context.
• lcftp is not null and *lcfgp is null.

Ensures:

• *lcfgp will point to a valid logging context if all of the necessary memory was allocated, or NULL otherwise.
• On failure, no additional memory is allocated.

Returns:

• ISC_R_SUCCESS Success
• ISC_R_NOMEMORY Resource limit: Out of memory

Definition at line 332 of file log.c.

References isc_logchannellist::channel, isc_logchannel::destination, isc_logdestination::facility, isc_logdestination::file, ISC_FALSE, ISC_LIST_HEAD, ISC_LIST_INIT, isc_log_createchannel(), ISC_LOG_DYNAMIC, ISC_LOG_INFO, ISC_LOG_PRINTTIME, ISC_LOG_ROLLNEVER, ISC_LOG_TOFILEDESC, ISC_LOG_TONULL, ISC_LOG_TOSYSLOG, isc_logconfig_destroy(), isc_mem_get, ISC_R_NOMEMORY, ISC_R_SUCCESS, LCFG_MAGIC, isc_logconfig::lctx, isc_logchannel::level, isc_logconfig::magic, isc_logfile::maximum_size, isc_log::mctx, isc_logfile::name, REQUIRE, isc_logfile::stream, VALID_CONTEXT, and isc_logfile::versions.

Referenced by isc_log_create(), and load_configuration().

isc_logconfig_t* isc_logconfig_get

(

isc_log_t *

lctx

)

Returns a pointer to the configuration currently in use by the log context.

Requires:

• lctx is a valid context.

Ensures:

• The configuration pointer is non-null.

Returns:

• The configuration pointer.

Definition at line 424 of file log.c.

References ENSURE, isc_log::logconfig, REQUIRE, and VALID_CONTEXT.

isc_result_t isc_logconfig_use	(	isc_log_t *	lctx,
		isc_logconfig_t *	lcfg
	)

Associate a new configuration with a logging context.

Notes:

• This is thread safe. The logging context will lock a mutex before attempting to swap in the new configuration, and isc_log_doit (the internal function used by all of isc_log_[v]write[1]) locks the same lock for the duration of its use of the configuration.

Requires:

• lctx is a valid logging context.
• lcfg is a valid logging configuration.
• lctx is the same configuration given to isc_logconfig_create when the configuration was created.

Ensures:

• Future calls to isc_log_write will use the new configuration.

Returns:

• ISC_R_SUCCESS Success
• ISC_R_NOMEMORY Resource limit: Out of memory

Definition at line 433 of file log.c.

References isc_logconfig_destroy(), ISC_R_SUCCESS, isc_logconfig::lctx, isc_log::lock, LOCK, isc_log::logconfig, REQUIRE, sync_channellist(), UNLOCK, VALID_CONFIG, and VALID_CONTEXT.

Referenced by load_configuration().

void isc_log_destroy

(

isc_log_t **

lctxp

)

Deallocate the memory associated with a logging context.

Requires:

• *lctx is a valid logging context.

Ensures:

• All of the memory associated with the logging context is returned to the free memory pool.

• Any open files are closed.

• The logging context is marked as invalid.

Definition at line 463 of file log.c.

References isc_log::buffer, isc_log::categories, isc_log::category_count, isc_log::debug_level, DESTROYLOCK, ISC_LIST_HEAD, ISC_LIST_UNLINK, isc_logconfig_destroy(), isc_mem_put, isc_mem_putanddetach, isc_log::lock, isc_log::logconfig, isc_log::magic, isc_log::mctx, isc_log::module_count, isc_log::modules, REQUIRE, isc_logmessage::text, and VALID_CONTEXT.

Referenced by cleanup(), cleanup_logging(), destroy_libs(), dns_test_end(), isc_log_create(), isc_test_end(), main(), ns_log_init(), and ns_log_shutdown().

void isc_logconfig_destroy

(

isc_logconfig_t **

lcfgp

)

Destroy a logging configuration.

Notes:

• This function cannot be used directly with the return value of isc_logconfig_get, because a logging context must always have a valid configuration associated with it.

Requires:

• lcfgp is not null and *lcfgp is a valid logging configuration.
• The logging configuration is not in use by an existing logging context.

Ensures:

• All memory allocated for the configuration is freed.

• The configuration is marked as invalid.

Definition at line 504 of file log.c.

References DE_CONST, FILE_NAME, FILE_STREAM, ISC_FALSE, ISC_LIST, ISC_LIST_HEAD, ISC_LIST_UNLINK, ISC_LOG_TOFILE, isc_mem_free, isc_mem_put, isc_logconfig::lctx, isc_log::logconfig, isc_logconfig::magic, isc_log::mctx, isc_logchannel::name, REQUIRE, isc_logchannel::type, and VALID_CONFIG.

Referenced by isc_log_create(), isc_log_destroy(), isc_logconfig_create(), isc_logconfig_use(), and load_configuration().

void isc_log_registercategories	(	isc_log_t *	lctx,
		isc_logcategory_t	categories[]
	)

Identify logging categories a library will use.

Notes:

• A category should only be registered once, but no mechanism enforces this rule.

• The end of the categories array is identified by a NULL name.

• Because the name is used by ISC_LOG_PRINTCATEGORY, it should not be altered or destroyed after isc_log_registercategories().

• Because each element of the categories array is used by isc_log_categorybyname, it should not be altered or destroyed after registration.

• The value of the id integer in each structure is overwritten by this function, and so id need not be initialized to any particular value prior to the function call.

• A subsequent call to isc_log_registercategories with the same logging context (but new categories) will cause the last element of the categories array from the prior call to have its "name" member changed from NULL to point to the new categories array, and its "id" member set to UINT_MAX.

Requires:

• lctx is a valid logging context.
• categories != NULL.
• categories[0].name != NULL.

Ensures:

• There are references to each category in the logging context, so they can be used with isc_log_usechannel() and isc_log_write().

Definition at line 570 of file log.c.

References isc_log::categories, isc_log::category_count, DE_CONST, isc_logcategory::id, isc_logcategory::name, isc_logchannel::name, REQUIRE, and VALID_CONTEXT.

Referenced by cfg_log_init(), dns_log_init(), dns_test_begin(), isc_log_create(), isc_test_begin(), ns_log_init(), and setup_logging().

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.

Definition at line 614 of file log.c.

References isc_log::categories, DE_CONST, isc_logcategory::id, isc_logcategory::name, REQUIRE, and VALID_CONTEXT.

Referenced by bind9_check_logging(), and category_fromconf().

void isc_log_registermodules	(	isc_log_t *	lctx,
		isc_logmodule_t	modules[]
	)

Identify logging categories a library will use.

Notes:

• A module should only be registered once, but no mechanism enforces this rule.

• The end of the modules array is identified by a NULL name.

• Because the name is used by ISC_LOG_PRINTMODULE, it should not be altered or destroyed after isc_log_registermodules().

• Because each element of the modules array is used by isc_log_modulebyname, it should not be altered or destroyed after registration.

• The value of the id integer in each structure is overwritten by this function, and so id need not be initialized to any particular value prior to the function call.

• A subsequent call to isc_log_registermodules with the same logging context (but new modules) will cause the last element of the modules array from the prior call to have its "name" member changed from NULL to point to the new modules array, and its "id" member set to UINT_MAX.

Requires:

• lctx is a valid logging context.
• modules != NULL.
• modules[0].name != NULL;

Ensures:

• Each module has a reference in the logging context, so they can be used with isc_log_usechannel() and isc_log_write().

Definition at line 637 of file log.c.

References DE_CONST, isc_logmodule::id, isc_log::module_count, isc_log::modules, isc_logmodule::name, isc_logchannel::name, REQUIRE, and VALID_CONTEXT.

Referenced by cfg_log_init(), dns_log_init(), isc_log_create(), and ns_log_init().

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.

Definition at line 681 of file log.c.

References DE_CONST, isc_logmodule::id, isc_log::modules, isc_logmodule::name, REQUIRE, and VALID_CONTEXT.

isc_result_t isc_log_createchannel	(	isc_logconfig_t *	lcfg,
		const char *	name,
		unsigned int	type,
		int	level,
		const isc_logdestination_t *	destination,
		unsigned int	flags
	)

Specify the parameters of a logging channel.

Notes:

• The name argument is copied to memory in the logging context, so it can be altered or destroyed after isc_log_createchannel().

• Defining a very large number of channels will have a performance impact on isc_log_usechannel(), since the names are searched linearly until a match is made. This same issue does not affect isc_log_write, however.

• Channel names can be redefined; this is primarily useful for programs that want their own definition of default_syslog, default_debug and default_stderr.

• Any channel that is redefined will not affect logging that was already directed to its original definition, _except_ for the default_stderr channel. This case is handled specially so that the default logging category can be changed by redefining default_stderr. (XXXDCL Though now that I think of it, the default logging category can be changed with only one additional function call by defining a new channel and then calling isc_log_usechannel() for ISC_LOGCATEGORY_DEFAULT.)

• Specifying ISC_LOG_PRINTTIME or ISC_LOG_PRINTTAG for syslog is allowed, but probably not what you wanted to do.

ISC_LOG_DEBUGONLY will mark the channel as usable only when the debug level of the logging context (see isc_log_setdebuglevel) is non-zero.

Requires:

• lcfg is a valid logging configuration.

• name is not NULL.

• type is ISC_LOG_TOSYSLOG, ISC_LOG_TOFILE, ISC_LOG_TOFILEDESC or ISC_LOG_TONULL.

• destination is not NULL unless type is ISC_LOG_TONULL.

• level is >= ISC_LOG_CRITICAL (the most negative logging level).

• flags does not include any bits aside from the ISC_LOG_PRINT* bits, ISC_LOG_DEBUGONLY or ISC_LOG_BUFFERED.

Ensures:

• ISC_R_SUCCESS A channel with the given name is usable with isc_log_usechannel().

• ISC_R_NOMEMORY or ISC_R_UNEXPECTED No additional memory is being used by the logging context. Any channel that previously existed with the given name is not redefined.

Returns:

• ISC_R_SUCCESS Success
• ISC_R_NOMEMORY Resource limit: Out of memory
• ISC_R_UNEXPECTED type was out of range and REQUIRE() was disabled.

Definition at line 704 of file log.c.

References isc_logchannellist::channel, isc_logdestination::facility, FACILITY, isc_logdestination::file, FILE_MAXREACHED, FILE_MAXSIZE, FILE_NAME, FILE_STREAM, FILE_VERSIONS, isc_logchannel::flags, ISC_FALSE, ISC_LINK_INIT, ISC_LIST_PREPEND, ISC_LOG_BUFFERED, ISC_LOG_CRITICAL, ISC_LOG_DEBUGONLY, ISC_LOG_PRINTALL, ISC_LOG_ROLLNEVER, ISC_LOG_TOFILE, ISC_LOG_TOFILEDESC, ISC_LOG_TONULL, ISC_LOG_TOSYSLOG, isc_mem_free, isc_mem_get, isc_mem_put, isc_mem_strdup, ISC_R_NOMEMORY, ISC_R_SUCCESS, ISC_R_UNEXPECTED, isc_logconfig::lctx, isc_logchannel::level, isc_logfile::maximum_size, isc_log::mctx, isc_logfile::name, isc_logchannel::name, REQUIRE, isc_logfile::stream, isc_logchannel::type, VALID_CONFIG, and isc_logfile::versions.

Referenced by channel_fromconf(), dns_test_begin(), isc_logconfig_create(), isc_test_begin(), main(), ns_log_setdefaultchannels(), ns_log_setsafechannels(), and setup_logging().

isc_result_t 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.

• Specifying 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

Definition at line 790 of file log.c.

References assignchannel(), isc_log::category_count, isc_logmodule::id, isc_logcategory::id, ISC_LIST_HEAD, ISC_LIST_NEXT, ISC_R_NOTFOUND, ISC_R_SUCCESS, isc_logconfig::lctx, isc_log::module_count, isc_logchannel::name, REQUIRE, and VALID_CONFIG.

Referenced by category_fromconf(), dns_client_create(), dns_test_begin(), isc_test_begin(), main(), ns_log_setdefaultcategory(), ns_log_setunmatchedcategory(), setup_libs(), setup_logging(), and setup_system().

void isc_log_write	(	isc_log_t *	lctx,
		isc_logcategory_t *	category,
		isc_logmodule_t *	module,
		int	level,
		const char *	format,
			...
	)

Definition at line 833 of file log.c.

References ISC_FALSE, and isc_log_doit().

void isc_log_vwrite	(	isc_log_t *	lctx,
		isc_logcategory_t *	category,
		isc_logmodule_t *	module,
		int	level,
		const char *	format,
		va_list	args
	)

Definition at line 849 of file log.c.

References ISC_FALSE, and isc_log_doit().

void isc_log_write1	(	isc_log_t *	lctx,
		isc_logcategory_t *	category,
		isc_logmodule_t *	module,
		int	level,
		const char *	format,
			...
	)

Definition at line 861 of file log.c.

References isc_log_doit(), and ISC_TRUE.

void isc_log_vwrite1	(	isc_log_t *	lctx,
		isc_logcategory_t *	category,
		isc_logmodule_t *	module,
		int	level,
		const char *	format,
		va_list	args
	)

Definition at line 877 of file log.c.

References isc_log_doit(), and ISC_TRUE.

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	msg,
		const char *	format,
			...
	)

Definition at line 889 of file log.c.

References ISC_FALSE, and isc_log_doit().

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	msg,
		const char *	format,
		va_list	args
	)

Definition at line 907 of file log.c.

References ISC_FALSE, and isc_log_doit().

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	msg,
		const char *	format,
			...
	)

Definition at line 920 of file log.c.

References isc_log_doit(), and ISC_TRUE.

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	msg,
		const char *	format,
		va_list	args
	)

Definition at line 938 of file log.c.

References isc_log_doit(), and ISC_TRUE.

void isc_log_setcontext

(

isc_log_t *

lctx

)

Sets the context used by the libisc for logging.

Requires:

• lctx be a valid context.

Definition at line 951 of file log.c.

Referenced by cleanup_logging(), dns_client_create(), dns_test_begin(), isc_test_begin(), main(), ns_log_init(), ns_log_shutdown(), setup_libs(), setup_logging(), and setup_system().

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.

Definition at line 956 of file log.c.

References isc_log::debug_level, FILE_STREAM, isc_logchannel::flags, ISC_LIST_HEAD, ISC_LIST_NEXT, ISC_LOG_DEBUGONLY, ISC_LOG_TOFILE, isc_log::lock, LOCK, isc_log::logconfig, REQUIRE, isc_logchannel::type, UNLOCK, and VALID_CONTEXT.

Referenced by dns_client_create(), ns_control_docommand(), ns_log_setdefaultchannels(), ns_log_setsafechannels(), ns_server_setdebuglevel(), setup_libs(), and setup_system().

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.

Definition at line 981 of file log.c.

References isc_log::debug_level, REQUIRE, and VALID_CONTEXT.

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.

Definition at line 988 of file log.c.

References REQUIRE, and VALID_CONFIG.

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.

Definition at line 995 of file log.c.

References REQUIRE, and VALID_CONTEXT.

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.

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.

Definition at line 1002 of file log.c.

References isc_mem_free, isc_mem_strdup, ISC_R_NOMEMORY, ISC_R_SUCCESS, isc_logconfig::lctx, isc_log::mctx, REQUIRE, and VALID_CONFIG.

Referenced by main(), and setup_logging().

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.

Definition at line 1022 of file log.c.

References REQUIRE, and VALID_CONFIG.

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 accommodate 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.

Definition at line 1030 of file log.c.

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.

Definition at line 1035 of file log.c.

References FILE_STREAM, ISC_LIST_HEAD, ISC_LIST_NEXT, ISC_LOG_TOFILE, isc_log::lock, LOCK, isc_log::logconfig, REQUIRE, isc_logchannel::type, UNLOCK, and VALID_CONTEXT.

static isc_result_t isc_log_open

(

isc_logchannel_t *

channel

)

[static]

Definition at line 1321 of file log.c.

References FILE_MAXSIZE, FILE_NAME, FILE_STREAM, FILE_VERSIONS, isc_logchannel::flags, ISC_FALSE, ISC_LOG_OPENERR, ISC_LOG_ROLLNEVER, ISC_LOG_TOFILE, ISC_R_INVALIDFILE, ISC_R_MAXSIZE, ISC_R_SUCCESS, isc_result_totext(), isc_stdio_open(), ISC_TRUE, POST, REQUIRE, roll_log(), and isc_logchannel::type.

Referenced by isc_log_doit().

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.

Definition at line 1380 of file log.c.

References ISC_FALSE, ISC_TF, and isc_log::logconfig.

Referenced by badname(), cfg_obj_log(), debit_rrl_entry(), decrement_reference(), dispatch_createudp(), dispatch_log(), dns_adb_createfind2(), dns_rrl(), dns_zone_log(), dns_zone_logc(), doio_recv(), dump_symboltable(), expand_entries(), expand_rrl_hash(), expirenode(), hash_divisor(), isc_log_doit(), log_fetch(), log_query(), log_queryerror(), logfmtpacket(), mgr_log(), notify_log(), ns_client_dumpmessage(), ns_client_error(), ns_client_log(), possibly_mark(), query_find(), query_getcachedb(), query_resume(), query_validatezonedb(), request_log(), rpz_getdb(), rpz_log_fail(), rpz_log_rewrite(), sendstream(), socket_log(), tsig_log(), udp_recv(), update_action(), update_log(), validator_log(), view_find(), xfrin_log(), xfrin_log1(), and zone_debuglog().

---

Variable Documentation

const char* log_level_strings[] [static]

Initial value:

 {
        "debug",
        "info",
        "notice",
        "warning",
        "error",
        "critical"
}

Used when ISC_LOG_PRINTLEVEL is enabled for a channel.

Definition at line 163 of file log.c.

Referenced by isc_log_doit().

const int syslog_map[] [static]

Initial value:

 {
        LOG_DEBUG,
        LOG_INFO,
        LOG_NOTICE,
        LOG_WARNING,
        LOG_ERR,
        LOG_CRIT
}

Used to convert ISC_LOG_* priorities into syslog priorities. XXXDCL This will need modification for NT.

Definition at line 176 of file log.c.

LIBISC_EXTERNAL_DATA isc_logcategory_t isc_categories[]

Initial value:

 {
        { "default", 0 },       
        { "general", 0 },
        { NULL, 0 }
}

The built-in categories of libisc.

When adding new categories, a corresponding ISC_LOGCATEGORY_foo definition needs to be added to <isc/log.h>.

The default category is provided so that the internal default can be overridden. Since the default is always looked up as the first channellist in the log context, it must come first in isc_categories[].

Definition at line 193 of file log.c.

LIBISC_EXTERNAL_DATA isc_logmodule_t isc_modules[]

Initial value:

 {
        { "socket", 0 },
        { "time", 0 },
        { "interface", 0 },
        { "timer", 0 },
        { "file", 0 },
        { "other", 0 },
        { NULL, 0 }
}

See above comment for categories on LIBISC_EXTERNAL_DATA, and apply it to modules.

Definition at line 202 of file log.c.

isc_logchannellist_t default_channel [static]

This essentially constant structure must be filled in at run time, because its channel member is pointed to a channel that is created dynamically with isc_log_createchannel.

Definition at line 217 of file log.c.

LIBISC_EXTERNAL_DATA isc_log_t* isc_lctx = NULL

libisc logs to this context.

Definition at line 222 of file log.c.

Referenced by doio_recv(), internal_accept(), internal_current4(), isc_file_openuniquemode(), schedule(), socket_log(), try_dscp_v4(), try_proto(), and wakeup_socket().

---