log.h 28.2 KB
Newer Older
1
/*
Automatic Updater's avatar
Automatic Updater committed
2
 * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 1999-2002  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
6 7
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * 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.
16 17
 */

Automatic Updater's avatar
Automatic Updater committed
18
/* $Id: log.h,v 1.57 2009/01/06 23:47:57 tbox Exp $ */
19 20 21 22

#ifndef ISC_LOG_H
#define ISC_LOG_H 1

23
/*! \file isc/log.h */
24

25
#include <stdio.h>
26
#include <stdarg.h>
27
#include <syslog.h> /* XXXDCL NT */
28

Michael Graff's avatar
Michael Graff committed
29
#include <isc/formatcheck.h>
30
#include <isc/lang.h>
31
#include <isc/platform.h>
32
#include <isc/types.h>
33

34 35 36
/*@{*/
/*!
 * \brief Severity levels, patterned after Unix's syslog levels.
37 38 39
 *
 */
#define ISC_LOG_DEBUG(level)	(level)
40 41 42 43
/*!
 * #ISC_LOG_DYNAMIC can only be used for defining channels with
 * isc_log_createchannel(), not to specify a level in isc_log_write().
 */
44 45 46 47 48 49
#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)
50
/*@}*/
51

52 53 54
/*@{*/
/*!
 * \brief Destinations.
55 56 57 58 59
 */
#define ISC_LOG_TONULL		1
#define ISC_LOG_TOSYSLOG	2
#define ISC_LOG_TOFILE		3
#define ISC_LOG_TOFILEDESC	4
60
/*@}*/
61

62 63
/*@{*/
/*%
64 65 66 67 68 69
 * Channel flags.
 */
#define ISC_LOG_PRINTTIME	0x0001
#define ISC_LOG_PRINTLEVEL	0x0002
#define ISC_LOG_PRINTCATEGORY	0x0004
#define ISC_LOG_PRINTMODULE	0x0008
70 71 72
#define ISC_LOG_PRINTTAG	0x0010
#define ISC_LOG_PRINTALL	0x001F
#define ISC_LOG_DEBUGONLY	0x1000
73
#define ISC_LOG_OPENERR		0x8000		/* internal */
74
/*@}*/
75

76 77 78 79
/*@{*/
/*!
 * \brief Other options.
 *
80 81 82 83 84 85
 * 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)
86
/*@}*/
87

88
/*!
Automatic Updater's avatar
Automatic Updater committed
89
 * \brief Used to name the categories used by a library.
90 91
 *
 * An array of isc_logcategory
92
 * structures names each category, and the id value is initialized by calling
93
 * isc_log_registercategories.
94
 */
95
struct isc_logcategory {
96 97
	const char *name;
	unsigned int id;
98
};
99

100 101
/*%
 * Similar to isc_logcategory, but for all the modules a library defines.
102
 */
103
struct isc_logmodule {
104 105
	const char *name;
	unsigned int id;
106
};
107

108
/*%
109
 * The isc_logfile structure is initialized as part of an isc_logdestination
Automatic Updater's avatar
Automatic Updater committed
110
 * before calling isc_log_createchannel().
111 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.
Automatic Updater's avatar
Automatic Updater committed
116
 *
117
 * Setting maximum_size to zero implies no maximum.
118 119
 */
typedef struct isc_logfile {
120 121 122 123
	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. */
	/*%
124 125 126 127 128 129
	 * 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.
	 */
130
	isc_offset_t maximum_size;
131
	isc_boolean_t maximum_reached; /*%< Private. */
132 133
} isc_logfile_t;

134
/*%
135 136 137 138 139 140 141 142
 * 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;

143 144
/*@{*/
/*%
145
 * The built-in categories of libisc.
146 147 148
 *
 * Each library registering categories should provide library_LOGCATEGORY_name
 * definitions with indexes into its isc_logcategory structure corresponding to
149
 * the order of the names.
150
 */
151 152 153
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[];
154
/*@}*/
155

156 157
/*@{*/
/*%
158 159 160
 * Do not log directly to DEFAULT.  Use another category.  When in doubt,
 * use GENERAL.
 */
161
#define ISC_LOGCATEGORY_DEFAULT	(&isc_categories[0])
162
#define ISC_LOGCATEGORY_GENERAL	(&isc_categories[1])
163
/*@}*/
164

165
#define ISC_LOGMODULE_SOCKET (&isc_modules[0])
166
#define ISC_LOGMODULE_TIME (&isc_modules[1])
167
#define ISC_LOGMODULE_INTERFACE (&isc_modules[2])
Michael Graff's avatar
Michael Graff committed
168
#define ISC_LOGMODULE_TIMER (&isc_modules[3])
169

170 171
ISC_LANG_BEGINDECLS

172
isc_result_t
173
isc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp);
174
/*%<
175 176 177
 * Establish a new logging context, with default channels.
 *
 * Notes:
178
 *\li	isc_log_create() calls isc_logconfig_create(), so see its comment
David Lawrence's avatar
David Lawrence committed
179 180 181
 *	below for more information.
 *
 * Requires:
182 183 184
 *\li	mctx is a valid memory context.
 *\li	lctxp is not null and *lctxp is null.
 *\li	lcfgp is null or lcfgp is not null and *lcfgp is null.
David Lawrence's avatar
David Lawrence committed
185 186
 *
 * Ensures:
187
 *\li	*lctxp will point to a valid logging context if all of the necessary
David Lawrence's avatar
David Lawrence committed
188
 *	memory was allocated, or NULL otherwise.
189
 *\li	*lcfgp will point to a valid logging configuration if all of the
190
 *	necessary memory was allocated, or NULL otherwise.
191
 *\li	On failure, no additional memory is allocated.
David Lawrence's avatar
David Lawrence committed
192 193
 *
 * Returns:
194 195
 *\li	#ISC_R_SUCCESS		Success
 *\li	#ISC_R_NOMEMORY		Resource limit: Out of memory
David Lawrence's avatar
David Lawrence committed
196 197 198 199
 */

isc_result_t
isc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp);
200
/*%<
David Lawrence's avatar
David Lawrence committed
201 202 203 204 205 206 207
 * 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:
208
 *\li	It is necessary to specify the logging context the configuration
David Lawrence's avatar
David Lawrence committed
209 210 211 212 213
 * 	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.
 *
214
 *\li	The memory context used for operations that allocate memory for
David Lawrence's avatar
David Lawrence committed
215 216 217
 *	the configuration is that of the logging context, as specified
 *	in the isc_log_create call.
 *
218 219
 *\li	Four default channels are established:
 *\verbatim
220
 *	    	default_syslog
221
 *		 - log to syslog's daemon facility #ISC_LOG_INFO or higher
222
 *		default_stderr
223
 *		 - log to stderr #ISC_LOG_INFO or higher
224
 *		default_debug
225
 *		 - log to stderr #ISC_LOG_DEBUG dynamically
226 227
 *		null
 *		 - log nothing
228
 *\endverbatim
229 230
 *
 * Requires:
231 232
 *\li 	lctx is a valid logging context.
 *\li	lcftp is not null and *lcfgp is null.
233 234
 *
 * Ensures:
235
 *\li	*lcfgp will point to a valid logging context if all of the necessary
236
 *	memory was allocated, or NULL otherwise.
237
 *\li	On failure, no additional memory is allocated.
238 239
 *
 * Returns:
240 241
 *\li	#ISC_R_SUCCESS		Success
 *\li	#ISC_R_NOMEMORY		Resource limit: Out of memory
242 243
 */

244 245
isc_logconfig_t *
isc_logconfig_get(isc_log_t *lctx);
246
/*%<
David Lawrence's avatar
David Lawrence committed
247 248 249
 * Returns a pointer to the configuration currently in use by the log context.
 *
 * Requires:
250
 *\li	lctx is a valid context.
David Lawrence's avatar
David Lawrence committed
251 252
 *
 * Ensures:
253
 *\li	The configuration pointer is non-null.
David Lawrence's avatar
David Lawrence committed
254 255
 *
 * Returns:
256
 *\li	The configuration pointer.
David Lawrence's avatar
David Lawrence committed
257
 */
258 259 260

isc_result_t
isc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg);
261
/*%<
David Lawrence's avatar
David Lawrence committed
262 263 264
 * Associate a new configuration with a logging context.
 *
 * Notes:
265
 *\li	This is thread safe.  The logging context will lock a mutex
David Lawrence's avatar
David Lawrence committed
266 267 268 269 270
 *	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:
271 272 273
 *\li	lctx is a valid logging context.
 *\li	lcfg is a valid logging configuration.
 *\li	lctx is the same configuration given to isc_logconfig_create
David Lawrence's avatar
David Lawrence committed
274 275 276
 *		when the configuration was created.
 *
 * Ensures:
277
 *\li	Future calls to isc_log_write will use the new configuration.
David Lawrence's avatar
David Lawrence committed
278 279
 *
 * Returns:
280 281
 *\li	#ISC_R_SUCCESS		Success
 *\li	#ISC_R_NOMEMORY		Resource limit: Out of memory
David Lawrence's avatar
David Lawrence committed
282
 */
283

284 285
void
isc_log_destroy(isc_log_t **lctxp);
286
/*%<
287 288 289
 * Deallocate the memory associated with a logging context.
 *
 * Requires:
290
 *\li	*lctx is a valid logging context.
291 292
 *
 * Ensures:
293
 *\li	All of the memory associated with the logging context is returned
294 295
 *	to the free memory pool.
 *
296
 *\li	Any open files are closed.
297
 *
298
 *\li	The logging context is marked as invalid.
299 300
 */

301 302
void
isc_logconfig_destroy(isc_logconfig_t **lcfgp);
303
/*%<
David Lawrence's avatar
David Lawrence committed
304 305 306
 * Destroy a logging configuration.
 *
 * Notes:
307
 *\li	This function cannot be used directly with the return value of
David Lawrence's avatar
David Lawrence committed
308 309 310 311
 *	isc_logconfig_get, because a logging context must always have
 *	a valid configuration associated with it.
 *
 * Requires:
312 313
 *\li	lcfgp is not null and *lcfgp is a valid logging configuration.
 *\li	The logging configuration is not in use by an existing logging context.
David Lawrence's avatar
David Lawrence committed
314 315
 *
 * Ensures:
316
 *\li	All memory allocated for the configuration is freed.
David Lawrence's avatar
David Lawrence committed
317
 *
318
 *\li	The configuration is marked as invalid.
David Lawrence's avatar
David Lawrence committed
319
 */
David Lawrence's avatar
David Lawrence committed
320

321
void
322
isc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]);
323
/*%<
324 325 326
 * Identify logging categories a library will use.
 *
 * Notes:
327
 *\li	A category should only be registered once, but no mechanism enforces
328 329
 *	this rule.
 *
330
 *\li	The end of the categories array is identified by a NULL name.
331
 *
332
 *\li	Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not
333 334
 *	be altered or destroyed after isc_log_registercategories().
 *
335
 *\li	Because each element of the categories array is used by
336 337 338
 *	isc_log_categorybyname, it should not be altered or destroyed
 *	after registration.
 *
339
 *\li	The value of the id integer in each structure is overwritten
340
 *	by this function, and so id need not be initialized to any particular
341 342
 *	value prior to the function call.
 *
343
 *\li	A subsequent call to isc_log_registercategories with the same
344 345 346 347 348
 *	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.
 *
349
 * Requires:
350 351 352
 *\li	lctx is a valid logging context.
 *\li	categories != NULL.
 *\li	categories[0].name != NULL.
353 354
 *
 * Ensures:
355
 * \li	There are references to each category in the logging context,
David Lawrence's avatar
David Lawrence committed
356
 * 	so they can be used with isc_log_usechannel() and isc_log_write().
357 358 359 360
 */

void
isc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]);
361
/*%<
362 363 364
 * Identify logging categories a library will use.
 *
 * Notes:
365
 *\li	A module should only be registered once, but no mechanism enforces
366 367
 *	this rule.
 *
368
 *\li	The end of the modules array is identified by a NULL name.
369
 *
370
 *\li	Because the name is used by #ISC_LOG_PRINTMODULE, it should not
371 372
 *	be altered or destroyed after isc_log_registermodules().
 *
373
 *\li	Because each element of the modules array is used by
374 375 376
 *	isc_log_modulebyname, it should not be altered or destroyed
 *	after registration.
 *
377
 *\li	The value of the id integer in each structure is overwritten
378
 *	by this function, and so id need not be initialized to any particular
379 380
 *	value prior to the function call.
 *
381
 *\li	A subsequent call to isc_log_registermodules with the same
382 383 384 385 386
 *	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.
 *
387
 * Requires:
388 389 390
 *\li	lctx is a valid logging context.
 *\li	modules != NULL.
 *\li	modules[0].name != NULL;
391 392
 *
 * Ensures:
393
 *\li	Each module has a reference in the logging context, so they can be
394 395 396 397
 *	used with isc_log_usechannel() and isc_log_write().
 */

isc_result_t
398 399
isc_log_createchannel(isc_logconfig_t *lcfg, const char *name,
		      unsigned int type, int level,
David Lawrence's avatar
David Lawrence committed
400 401
		      const isc_logdestination_t *destination,
		      unsigned int flags);
402
/*%<
403 404 405
 * Specify the parameters of a logging channel.
 *
 * Notes:
406
 *\li	The name argument is copied to memory in the logging context, so
407 408
 *	it can be altered or destroyed after isc_log_createchannel().
 *
409
 *\li	Defining a very large number of channels will have a performance
410 411 412 413
 *	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.
 *
414
 *\li	Channel names can be redefined; this is primarily useful for programs
415 416 417
 *	that want their own definition of default_syslog, default_debug
 *	and default_stderr.
 *
418
 *\li	Any channel that is redefined will not affect logging that was
419 420 421 422 423 424
 *	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()
425
 *	for #ISC_LOGCATEGORY_DEFAULT.)
426
 *
427
 *\li	Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is allowed,
428
 *	but probably not what you wanted to do.
429
 *
430
 *	#ISC_LOG_DEBUGONLY will mark the channel as usable only when the
David Lawrence's avatar
David Lawrence committed
431 432 433
 *	debug level of the logging context (see isc_log_setdebuglevel)
 *	is non-zero.
 *
434
 * Requires:
435
 *\li	lcfg is a valid logging configuration.
436
 *
437
 *\li	name is not NULL.
438
 *
439 440
 *\li	type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or
 *		#ISC_LOG_TONULL.
441
 *
442
 *\li	destination is not NULL unless type is #ISC_LOG_TONULL.
443
 *
444
 *\li	level is >= #ISC_LOG_CRITICAL (the most negative logging level).
445
 *
446 447
 *\li	flags does not include any bits aside from the ISC_LOG_PRINT* bits
 *	or #ISC_LOG_DEBUGONLY.
448 449
 *
 * Ensures:
450
 *\li	#ISC_R_SUCCESS
451 452 453
 *		A channel with the given name is usable with
 *		isc_log_usechannel().
 *
454
 *\li	#ISC_R_NOMEMORY or #ISC_R_UNEXPECTED
455 456 457 458 459
 *		No additional memory is being used by the logging context.
 *		Any channel that previously existed with the given name
 *		is not redefined.
 *
 * Returns:
460 461 462
 *\li	#ISC_R_SUCCESS		Success
 *\li	#ISC_R_NOMEMORY		Resource limit: Out of memory
 *\li	#ISC_R_UNEXPECTED	type was out of range and REQUIRE()
463 464 465 466
 *					was disabled.
 */

isc_result_t
467
isc_log_usechannel(isc_logconfig_t *lcfg, const char *name,
David Lawrence's avatar
David Lawrence committed
468 469
		   const isc_logcategory_t *category,
		   const isc_logmodule_t *module);
470
/*%<
471 472 473 474
 * Associate a named logging channel with a category and module that
 * will use it.
 *
 * Notes:
475
 *\li	The name is searched for linearly in the set of known channel names
476 477 478 479
 *	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.
 *
480
 *\li	Specifing a very large number of channels for a category will have
481 482 483 484 485
 *	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.
 *
486
 *\li	If category is NULL, then the channel is associated with the indicated
487 488
 *	module for all known categories (including the "default" category).
 *
489
 *\li	If module is NULL, then the channel is associated with every module
490 491
 *	that uses that category.
 *
492
 *\li	Passing both category and module as NULL would make every log message
493 494
 *	use the indicated channel.
 *
495
 * \li	Specifying a channel that is #ISC_LOG_TONULL for a category/module pair
496 497 498 499 500 501
 *	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:
502
 *\li	lcfg is a valid logging configuration.
503
 *
504
 *\li	category is NULL or has an id that is in the range of known ids.
505 506 507 508
 *
 *	module is NULL or has an id that is in the range of known ids.
 *
 * Ensures:
509
 *\li	#ISC_R_SUCCESS
510 511 512
 *		The channel will be used by the indicated category/module
 *		arguments.
 *
513
 *\li	#ISC_R_NOMEMORY
514 515 516 517 518 519 520
 *		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
521
 *		passed to isc_log_registercategories()) and additional memory
522 523 524
 *		is being used by whatever assignments succeeded.
 *
 * Returns:
525 526
 *\li	#ISC_R_SUCCESS	Success
 *\li	#ISC_R_NOMEMORY	Resource limit: Out of memory
527 528
 */

529
/* Attention: next four comments PRECEED code */
Automatic Updater's avatar
Automatic Updater committed
530
/*!
531
 *   \brief
532 533 534
 * Write a message to the log channels.
 *
 * Notes:
535
 *\li	Log messages containing natural language text should be logged with
536 537
 *	isc_log_iwrite() to allow for localization.
 *
538
 *\li	lctx can be NULL; this is allowed so that programs which use
539 540 541
 *	libraries that use the ISC logging system are not required to
 *	also use it.
 *
542
 *\li	The format argument is a printf(3) string, with additional arguments
543 544 545
 *	as necessary.
 *
 * Requires:
546
 *\li	lctx is a valid logging context.
547
 *
548
 *\li	The category and module arguments must have ids that are in the
549 550 551
 *	range of known ids, as estabished by isc_log_registercategories()
 *	and isc_log_registermodules().
 *
552
 *\li	level != #ISC_LOG_DYNAMIC.  ISC_LOG_DYNAMIC is used only to define
553 554
 *	channels, and explicit debugging level must be identified for
 *	isc_log_write() via ISC_LOG_DEBUG(level).
555
 *
556
 *\li	format != NULL.
557 558
 *
 * Ensures:
559
 *\li	The log message is written to every channel associated with the
560 561 562
 *	indicated category/module pair.
 *
 * Returns:
563
 *\li	Nothing.  Failure to log a message is not construed as a
564 565
 *	meaningful error.
 */
566
void
567
isc_log_write(isc_log_t *lctx, isc_logcategory_t *category,
568
	       isc_logmodule_t *module, int level,
569 570 571 572 573
	      const char *format, ...)

ISC_FORMAT_PRINTF(5, 6);

/*%
574 575 576
 * Write a message to the log channels.
 *
 * Notes:
577
 *\li	lctx can be NULL; this is allowed so that programs which use
578 579 580
 *	libraries that use the ISC logging system are not required to
 *	also use it.
 *
581
 *\li	The format argument is a printf(3) string, with additional arguments
582 583 584
 *	as necessary.
 *
 * Requires:
585
 *\li	lctx is a valid logging context.
586
 *
587
 *\li	The category and module arguments must have ids that are in the
588 589 590
 *	range of known ids, as estabished by isc_log_registercategories()
 *	and isc_log_registermodules().
 *
591
 *\li	level != #ISC_LOG_DYNAMIC.  ISC_LOG_DYNAMIC is used only to define
592 593
 *	channels, and explicit debugging level must be identified for
 *	isc_log_write() via ISC_LOG_DEBUG(level).
594
 *
595
 *\li	format != NULL.
596 597
 *
 * Ensures:
598
 *\li	The log message is written to every channel associated with the
599 600 601
 *	indicated category/module pair.
 *
 * Returns:
602
 *\li	Nothing.  Failure to log a message is not construed as a
603 604
 *	meaningful error.
 */
605 606 607 608 609 610
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);
611

612 613 614 615 616
/*%
 * 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().
 */
617
void
618
isc_log_write1(isc_log_t *lctx, isc_logcategory_t *category,
619
	       isc_logmodule_t *module, int level, const char *format, ...)
620

621
ISC_FORMAT_PRINTF(5, 6);
622 623

/*%
624 625
 * Write a message to the log channels, pruning duplicates that occur within
 * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval).
626
 * This function is otherwise identical to isc_log_vwrite().
627
 */
628
void
629
isc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category,
630 631
		isc_logmodule_t *module, int level, const char *format,
		va_list args)
632

633
ISC_FORMAT_PRINTF(5, 0);
634

635
/*%
636
 * These are four internationalized versions of the isc_log_[v]write[1]
Automatic Updater's avatar
Automatic Updater committed
637
 * functions.
638 639 640 641 642 643 644 645 646 647 648 649
 *
 * 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!
 */
/*@{*/
650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676
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);
677
/*@}*/
678

679 680
void
isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level);
681
/*%<
682 683 684
 * Set the debugging level used for logging.
 *
 * Notes:
685
 *\li	Setting the debugging level to 0 disables debugging log messages.
686 687
 *
 * Requires:
688
 *\li	lctx is a valid logging context.
689 690
 *
 * Ensures:
691
 *\li	The debugging level is set to the requested value.
692 693 694 695
 */

unsigned int
isc_log_getdebuglevel(isc_log_t *lctx);
696
/*%<
697 698 699
 * Get the current debugging level.
 *
 * Notes:
700
 *\li	This is provided so that a program can have a notion of
701 702 703
 *	"increment debugging level" or "decrement debugging level"
 *	without needing to keep track of what the current level is.
 *
704
 *\li	A return value of 0 indicates that debugging messages are disabled.
705 706
 *
 * Requires:
707
 *\li	lctx is a valid logging context.
708
 *
709
 * Ensures:
710
 *\li	The current logging debugging level is returned.
711 712
 */

713 714
isc_boolean_t
isc_log_wouldlog(isc_log_t *lctx, int level);
715
/*%<
716 717 718
 * Determine whether logging something to 'lctx' at 'level' would
 * actually cause something to be logged somewhere.
 *
719
 * If #ISC_FALSE is returned, it is guaranteed that nothing would
720 721 722 723
 * be logged, allowing the caller to omit unnecessary
 * isc_log_write() calls and possible message preformatting.
 */

724
void
725
isc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval);
726
/*%<
727 728 729 730
 * Set the interval over which duplicate log messages will be ignored
 * by isc_log_[v]write1(), in seconds.
 *
 * Notes:
731
 *\li	Increasing the duplicate interval from X to Y will not necessarily
732 733 734 735 736 737 738 739 740
 *	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:
741
 *\li	lctx is a valid logging context.
742 743 744
 */

unsigned int
745
isc_log_getduplicateinterval(isc_logconfig_t *lcfg);
746
/*%<
747 748 749
 * Get the current duplicate filtering interval.
 *
 * Requires:
750
 *\li	lctx is a valid logging context.
751
 *
752
 * Returns:
753
 *\li	The current duplicate filtering interval.
754 755
 */

David Lawrence's avatar
David Lawrence committed
756 757
isc_result_t
isc_log_settag(isc_logconfig_t *lcfg, const char *tag);
758 759
/*%<
 * Set the program name or other identifier for #ISC_LOG_PRINTTAG.
760 761
 *
 * Requires:
762
 *\li	lcfg is a valid logging configuration.
763 764
 *
 * Notes:
765 766
 *\li	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.
767 768 769 770
 *	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).
 *
771 772
 *\li	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
773 774
 *	empty string, calls to isc_log_gettag will return NULL.
 *
David Lawrence's avatar
David Lawrence committed
775
 * Returns:
776 777
 *\li	#ISC_R_SUCCESS	Success
 *\li	#ISC_R_NOMEMORY  Resource Limit: Out of memory
David Lawrence's avatar
David Lawrence committed
778
 *
779 780 781 782 783 784 785
 * 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);
786 787
/*%<
 * Get the current identifier printed with #ISC_LOG_PRINTTAG.
788 789
 *
 * Requires:
790
 *\li	lcfg is a valid logging configuration.
791 792
 *
 * Notes:
793
 *\li	Since isc_log_settag() will not associate a zero-length string
794 795 796 797 798 799
 *	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:
800
 *\li	A pointer to the current identifier, or NULL if none has been set.
801 802
 */

803 804
void
isc_log_opensyslog(const char *tag, int options, int facility);
805
/*%<
806 807 808
 * Initialize syslog logging.
 *
 * Notes:
809
 *\li	XXXDCL NT
810 811 812
 *	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:
813 814
 *
 * \code
815 816 817 818 819 820 821