log.h

bind 9.3结合mysql数据库

/*
 * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
 * Copyright (C) 1999-2002  Internet Software Consortium.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */

/* $Id: log.h,v 1.39.2.4.2.7 2004/04/10 04:31:40 marka Exp $ */

#ifndef ISC_LOG_H
#define ISC_LOG_H 1

#include <stdio.h>
#include <stdarg.h>
#include <syslog.h> /* XXXDCL NT */

#include <isc/formatcheck.h>
#include <isc/lang.h>
#include <isc/platform.h>
#include <isc/types.h>

/*
 * Severity levels, patterned after Unix's syslog levels.
 *
 * ISC_LOG_DYNAMIC can only be used for defining channels with
 * isc_log_createchannel(), not to specify a level in isc_log_write().
 */
#define ISC_LOG_DEBUG(level)	(level)
#define ISC_LOG_DYNAMIC	  	  0
#define ISC_LOG_INFO		(-1)
#define ISC_LOG_NOTICE		(-2)
#define ISC_LOG_WARNING 	(-3)
#define ISC_LOG_ERROR		(-4)
#define ISC_LOG_CRITICAL	(-5)

/*
 * Destinations.
 */
#define ISC_LOG_TONULL		1
#define ISC_LOG_TOSYSLOG	2
#define ISC_LOG_TOFILE		3
#define ISC_LOG_TOFILEDESC	4

/*
 * Channel flags.
 */
#define ISC_LOG_PRINTTIME	0x0001
#define ISC_LOG_PRINTLEVEL	0x0002
#define ISC_LOG_PRINTCATEGORY	0x0004
#define ISC_LOG_PRINTMODULE	0x0008
#define ISC_LOG_PRINTTAG	0x0010
#define ISC_LOG_PRINTALL	0x001F
#define ISC_LOG_DEBUGONLY	0x1000
#define ISC_LOG_OPENERR		0x8000		/* internal */

/*
 * Other options.
 * XXXDCL INFINITE doesn't yet work.  Arguably it isn't needed, but
 *   since I am intend to make large number of versions work efficiently,
 *   INFINITE is going to be trivial to add to that.
 */
#define ISC_LOG_ROLLINFINITE	(-1)
#define ISC_LOG_ROLLNEVER	(-2)

/*
 * Used to name the categories used by a library.  An array of isc_logcategory
 * structures names each category, and the id value is initialized by calling
 * isc_log_registercategories.
 */
struct isc_logcategory {
	const char *name;
	unsigned int id;
};

/*
 * Similar to isc_logcategory above, but for all the modules a library defines.
 */
struct isc_logmodule {
	const char *name;
	unsigned int id;
};

/*
 * The isc_logfile structure is initialized as part of an isc_logdestination
 * before calling isc_log_createchannel().  When defining an ISC_LOG_TOFILE
 * channel the name, versions and maximum_size should be set before calling
 * isc_log_createchannel().  To define an ISC_LOG_TOFILEDESC channel set only
 * the stream before the call.
 * 
 * Setting maximum_size to zero implies no maximum.
 */
typedef struct isc_logfile {
	FILE *stream;		/* Initialized to NULL for ISC_LOG_TOFILE. */
	const char *name;	/* NULL for ISC_LOG_TOFILEDESC. */
	int versions;	/* >= 0, ISC_LOG_ROLLNEVER, ISC_LOG_ROLLINFINITE. */
	/*
	 * stdio's ftell is standardized to return a long, which may well not
	 * be big enough for the largest file supportable by the operating
	 * system (though it is _probably_ big enough for the largest log
	 * anyone would want).  st_size returned by fstat should be typedef'd
	 * to a size large enough for the largest possible file on a system.
	 */
	isc_offset_t maximum_size;
	isc_boolean_t maximum_reached; /* Private. */
} isc_logfile_t;

/*
 * Passed to isc_log_createchannel to define the attributes of either
 * a stdio or a syslog log.
 */
typedef union isc_logdestination {
	isc_logfile_t file;
	int facility;		/* XXXDCL NT */
} isc_logdestination_t;

/*
 * The built-in categories of libisc.
 *
 * Each library registering categories should provide library_LOGCATEGORY_name
 * definitions with indexes into its isc_logcategory structure corresponding to
 * the order of the names.
 */
LIBISC_EXTERNAL_DATA extern isc_logcategory_t isc_categories[];
LIBISC_EXTERNAL_DATA extern isc_log_t *isc_lctx;
LIBISC_EXTERNAL_DATA extern isc_logmodule_t isc_modules[];

/*
 * Do not log directly to DEFAULT.  Use another category.  When in doubt,
 * use GENERAL.
 */
#define ISC_LOGCATEGORY_DEFAULT	(&isc_categories[0])
#define ISC_LOGCATEGORY_GENERAL	(&isc_categories[1])

#define ISC_LOGMODULE_SOCKET (&isc_modules[0])
#define ISC_LOGMODULE_TIME (&isc_modules[1])
#define ISC_LOGMODULE_INTERFACE (&isc_modules[2])
#define ISC_LOGMODULE_TIMER (&isc_modules[3])

ISC_LANG_BEGINDECLS

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
 */

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
 */

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.
 */

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
 */

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.
 */

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.
 */

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().
 */

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().
 */

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
 *	or ISC_LOG_DEBUGONLY.
 *
 * 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()