log.h 26.9 KB
Newer Older
1
/*
2
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3
 *
4
5
6
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7
8
9
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
10
11
12
13
14
15
 */


#ifndef ISC_LOG_H
#define ISC_LOG_H 1

16
/*! \file isc/log.h */
17

18
#include <stdbool.h>
19
#include <stdio.h>
20
#include <stdarg.h>
21
#include <syslog.h> /* XXXDCL NT */
22

Michael Graff's avatar
Michael Graff committed
23
#include <isc/formatcheck.h>
24
#include <isc/lang.h>
25
#include <isc/platform.h>
26
#include <isc/types.h>
27

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

46
47
48
/*@{*/
/*!
 * \brief Destinations.
49
50
51
52
53
 */
#define ISC_LOG_TONULL		1
#define ISC_LOG_TOSYSLOG	2
#define ISC_LOG_TOFILE		3
#define ISC_LOG_TOFILEDESC	4
54
/*@}*/
55

56
57
/*@{*/
/*%
58
59
 * Channel flags.
 */
60
61
62
63
64
65
66
67
68
69
70
71
#define ISC_LOG_PRINTTIME	0x00001
#define ISC_LOG_PRINTLEVEL	0x00002
#define ISC_LOG_PRINTCATEGORY	0x00004
#define ISC_LOG_PRINTMODULE	0x00008
#define ISC_LOG_PRINTTAG	0x00010		/* tag and ":" */
#define ISC_LOG_PRINTPREFIX	0x00020		/* tag only, no colon */
#define ISC_LOG_PRINTALL	0x0003F
#define ISC_LOG_BUFFERED	0x00040
#define ISC_LOG_DEBUGONLY	0x01000
#define ISC_LOG_OPENERR		0x08000		/* internal */
#define ISC_LOG_ISO8601		0x10000		/* if PRINTTIME, use ISO8601 */
#define ISC_LOG_UTC		0x20000		/* if PRINTTIME, use UTC */
72
/*@}*/
73

74
75
76
77
/*@{*/
/*!
 * \brief Other options.
 *
78
79
80
81
82
83
 * 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)
84
85
86
87
88
89
90
91
92
93
94
#define ISC_LOG_MAX_VERSIONS	256
/*@}*/

/*@{*/
/*!
 * \brief Type of suffix used on rolled log files.
 */
typedef enum {
	isc_log_rollsuffix_increment,
	isc_log_rollsuffix_timestamp
} isc_log_rollsuffix_t;
95
/*@}*/
96

97
/*!
Automatic Updater's avatar
Automatic Updater committed
98
 * \brief Used to name the categories used by a library.
99
100
 *
 * An array of isc_logcategory
101
 * structures names each category, and the id value is initialized by calling
102
 * isc_log_registercategories.
103
 */
104
struct isc_logcategory {
105
106
	const char *name;
	unsigned int id;
107
};
108

109
110
/*%
 * Similar to isc_logcategory, but for all the modules a library defines.
111
 */
112
struct isc_logmodule {
113
114
	const char *name;
	unsigned int id;
115
};
116

117
/*%
118
 * The isc_logfile structure is initialized as part of an isc_logdestination
Automatic Updater's avatar
Automatic Updater committed
119
 * before calling isc_log_createchannel().
120
121
 *
 * When defining an #ISC_LOG_TOFILE
122
 * channel the name, versions and maximum_size should be set before calling
123
 * isc_log_createchannel().  To define an #ISC_LOG_TOFILEDESC channel set only
124
 * the stream before the call.
Automatic Updater's avatar
Automatic Updater committed
125
 *
126
 * Setting maximum_size to zero implies no maximum.
127
128
 */
typedef struct isc_logfile {
129
130
131
	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. */
132
	isc_log_rollsuffix_t suffix;
133
	/*%
134
135
136
137
138
139
	 * 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.
	 */
140
	isc_offset_t maximum_size;
141
	bool maximum_reached; /*%< Private. */
142
143
} isc_logfile_t;

144
/*%
145
146
147
148
149
150
151
152
 * 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;

153
154
/*@{*/
/*%
155
 * The built-in categories of libisc.
156
157
158
 *
 * Each library registering categories should provide library_LOGCATEGORY_name
 * definitions with indexes into its isc_logcategory structure corresponding to
159
 * the order of the names.
160
 */
161
162
163
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[];
164
/*@}*/
165

166
167
/*@{*/
/*%
168
169
170
 * Do not log directly to DEFAULT.  Use another category.  When in doubt,
 * use GENERAL.
 */
171
#define ISC_LOGCATEGORY_DEFAULT	(&isc_categories[0])
172
#define ISC_LOGCATEGORY_GENERAL	(&isc_categories[1])
173
/*@}*/
174

175
#define ISC_LOGMODULE_SOCKET (&isc_modules[0])
176
#define ISC_LOGMODULE_TIME (&isc_modules[1])
177
#define ISC_LOGMODULE_INTERFACE (&isc_modules[2])
Michael Graff's avatar
Michael Graff committed
178
#define ISC_LOGMODULE_TIMER (&isc_modules[3])
Mark Andrews's avatar
Mark Andrews committed
179
#define ISC_LOGMODULE_FILE (&isc_modules[4])
Evan Hunt's avatar
Evan Hunt committed
180
181
#define ISC_LOGMODULE_NETMGR (&isc_modules[5])
#define ISC_LOGMODULE_OTHER (&isc_modules[6])
182

183
184
ISC_LANG_BEGINDECLS

185
isc_result_t
186
isc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp);
187
/*%<
188
189
190
 * Establish a new logging context, with default channels.
 *
 * Notes:
191
 *\li	isc_log_create() calls isc_logconfig_create(), so see its comment
David Lawrence's avatar
David Lawrence committed
192
193
194
 *	below for more information.
 *
 * Requires:
195
196
197
 *\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
198
199
 *
 * Ensures:
200
 *\li	*lctxp will point to a valid logging context if all of the necessary
David Lawrence's avatar
David Lawrence committed
201
 *	memory was allocated, or NULL otherwise.
202
 *\li	*lcfgp will point to a valid logging configuration if all of the
203
 *	necessary memory was allocated, or NULL otherwise.
204
 *\li	On failure, no additional memory is allocated.
David Lawrence's avatar
David Lawrence committed
205
206
 *
 * Returns:
207
208
 *\li	#ISC_R_SUCCESS		Success
 *\li	#ISC_R_NOMEMORY		Resource limit: Out of memory
David Lawrence's avatar
David Lawrence committed
209
210
211
212
 */

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

257
258
isc_logconfig_t *
isc_logconfig_get(isc_log_t *lctx);
259
/*%<
David Lawrence's avatar
David Lawrence committed
260
261
262
 * Returns a pointer to the configuration currently in use by the log context.
 *
 * Requires:
263
 *\li	lctx is a valid context.
David Lawrence's avatar
David Lawrence committed
264
265
 *
 * Ensures:
266
 *\li	The configuration pointer is non-null.
David Lawrence's avatar
David Lawrence committed
267
268
 *
 * Returns:
269
 *\li	The configuration pointer.
David Lawrence's avatar
David Lawrence committed
270
 */
271
272
273

isc_result_t
isc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg);
274
/*%<
David Lawrence's avatar
David Lawrence committed
275
276
277
 * Associate a new configuration with a logging context.
 *
 * Notes:
278
 *\li	This is thread safe.  The logging context will lock a mutex
David Lawrence's avatar
David Lawrence committed
279
280
281
282
283
 *	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:
284
285
286
 *\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
287
288
289
 *		when the configuration was created.
 *
 * Ensures:
290
 *\li	Future calls to isc_log_write will use the new configuration.
David Lawrence's avatar
David Lawrence committed
291
292
 *
 * Returns:
293
294
 *\li	#ISC_R_SUCCESS		Success
 *\li	#ISC_R_NOMEMORY		Resource limit: Out of memory
David Lawrence's avatar
David Lawrence committed
295
 */
296

297
298
void
isc_log_destroy(isc_log_t **lctxp);
299
/*%<
300
301
302
 * Deallocate the memory associated with a logging context.
 *
 * Requires:
303
 *\li	*lctx is a valid logging context.
304
305
 *
 * Ensures:
306
 *\li	All of the memory associated with the logging context is returned
307
308
 *	to the free memory pool.
 *
309
 *\li	Any open files are closed.
310
 *
311
 *\li	The logging context is marked as invalid.
312
313
 */

314
315
void
isc_logconfig_destroy(isc_logconfig_t **lcfgp);
316
/*%<
David Lawrence's avatar
David Lawrence committed
317
318
319
 * Destroy a logging configuration.
 *
 * Notes:
320
 *\li	This function cannot be used directly with the return value of
David Lawrence's avatar
David Lawrence committed
321
322
323
324
 *	isc_logconfig_get, because a logging context must always have
 *	a valid configuration associated with it.
 *
 * Requires:
325
326
 *\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
327
328
 *
 * Ensures:
329
 *\li	All memory allocated for the configuration is freed.
David Lawrence's avatar
David Lawrence committed
330
 *
331
 *\li	The configuration is marked as invalid.
David Lawrence's avatar
David Lawrence committed
332
 */
David Lawrence's avatar
David Lawrence committed
333

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

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

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

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

542
/* Attention: next four comments PRECEED code */
Automatic Updater's avatar
Automatic Updater committed
543
/*!
544
 *   \brief
545
546
547
 * Write a message to the log channels.
 *
 * Notes:
548
 *\li	lctx can be NULL; this is allowed so that programs which use
549
550
551
 *	libraries that use the ISC logging system are not required to
 *	also use it.
 *
552
 *\li	The format argument is a printf(3) string, with additional arguments
553
554
555
 *	as necessary.
 *
 * Requires:
556
 *\li	lctx is a valid logging context.
557
 *
558
 *\li	The category and module arguments must have ids that are in the
Francis Dupont's avatar
Francis Dupont committed
559
 *	range of known ids, as established by isc_log_registercategories()
560
561
 *	and isc_log_registermodules().
 *
562
 *\li	level != #ISC_LOG_DYNAMIC.  ISC_LOG_DYNAMIC is used only to define
563
564
 *	channels, and explicit debugging level must be identified for
 *	isc_log_write() via ISC_LOG_DEBUG(level).
565
 *
566
 *\li	format != NULL.
567
568
 *
 * Ensures:
569
 *\li	The log message is written to every channel associated with the
570
571
572
 *	indicated category/module pair.
 *
 * Returns:
573
 *\li	Nothing.  Failure to log a message is not construed as a
574
575
 *	meaningful error.
 */
576
void
577
isc_log_write(isc_log_t *lctx, isc_logcategory_t *category,
578
	       isc_logmodule_t *module, int level,
579
580
581
582
583
	      const char *format, ...)

ISC_FORMAT_PRINTF(5, 6);

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

622
623
624
625
626
/*%
 * 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().
 */
627
void
628
isc_log_write1(isc_log_t *lctx, isc_logcategory_t *category,
629
	       isc_logmodule_t *module, int level, const char *format, ...)
630

631
ISC_FORMAT_PRINTF(5, 6);
632
633

/*%
634
635
 * Write a message to the log channels, pruning duplicates that occur within
 * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval).
636
 * This function is otherwise identical to isc_log_vwrite().
637
 */
638
void
639
isc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category,
640
641
		isc_logmodule_t *module, int level, const char *format,
		va_list args)
642

643
ISC_FORMAT_PRINTF(5, 0);
644

645
646
void
isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level);
647
/*%<
648
649
650
 * Set the debugging level used for logging.
 *
 * Notes:
651
 *\li	Setting the debugging level to 0 disables debugging log messages.
652
653
 *
 * Requires:
654
 *\li	lctx is a valid logging context.
655
656
 *
 * Ensures:
657
 *\li	The debugging level is set to the requested value.
658
659
660
661
 */

unsigned int
isc_log_getdebuglevel(isc_log_t *lctx);
662
/*%<
663
664
665
 * Get the current debugging level.
 *
 * Notes:
666
 *\li	This is provided so that a program can have a notion of
667
668
669
 *	"increment debugging level" or "decrement debugging level"
 *	without needing to keep track of what the current level is.
 *
670
 *\li	A return value of 0 indicates that debugging messages are disabled.
671
672
 *
 * Requires:
673
 *\li	lctx is a valid logging context.
674
 *
675
 * Ensures:
676
 *\li	The current logging debugging level is returned.
677
678
 */

679
bool
680
isc_log_wouldlog(isc_log_t *lctx, int level);
681
/*%<
682
683
684
 * Determine whether logging something to 'lctx' at 'level' would
 * actually cause something to be logged somewhere.
 *
685
 * If #false is returned, it is guaranteed that nothing would
686
687
688
689
 * be logged, allowing the caller to omit unnecessary
 * isc_log_write() calls and possible message preformatting.
 */

690
void
691
isc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval);
692
/*%<
693
694
695
696
 * Set the interval over which duplicate log messages will be ignored
 * by isc_log_[v]write1(), in seconds.
 *
 * Notes:
697
 *\li	Increasing the duplicate interval from X to Y will not necessarily
698
699
700
701
702
703
704
705
706
 *	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:
707
 *\li	lctx is a valid logging context.
708
709
710
 */

unsigned int
711
isc_log_getduplicateinterval(isc_logconfig_t *lcfg);
712
/*%<
713
714
715
 * Get the current duplicate filtering interval.
 *
 * Requires:
716
 *\li	lctx is a valid logging context.
717
 *
718
 * Returns:
719
 *\li	The current duplicate filtering interval.
720
721
 */

David Lawrence's avatar
David Lawrence committed
722
723
isc_result_t
isc_log_settag(isc_logconfig_t *lcfg, const char *tag);
724
725
/*%<
 * Set the program name or other identifier for #ISC_LOG_PRINTTAG.
726
727
 *
 * Requires:
728
 *\li	lcfg is a valid logging configuration.
729
730
 *
 * Notes:
731
732
 *\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.
733
734
735
736
 *	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).
 *
737
738
 *\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
739
740
 *	empty string, calls to isc_log_gettag will return NULL.
 *
David Lawrence's avatar
David Lawrence committed
741
 * Returns:
742
743
 *\li	#ISC_R_SUCCESS	Success
 *\li	#ISC_R_NOMEMORY  Resource Limit: Out of memory
David Lawrence's avatar
David Lawrence committed
744
 *
745
746
747
748
749
750
751
 * 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);
752
753
/*%<
 * Get the current identifier printed with #ISC_LOG_PRINTTAG.
754
755
 *
 * Requires:
756
 *\li	lcfg is a valid logging configuration.
757
758
 *
 * Notes:
759
 *\li	Since isc_log_settag() will not associate a zero-length string
760
761
762
763
764
765
 *	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:
766
 *\li	A pointer to the current identifier, or NULL if none has been set.
767
768
 */

769
770
void
isc_log_opensyslog(const char *tag, int options, int facility);
771
/*%<
772
773
774
 * Initialize syslog logging.
 *
 * Notes:
775
 *\li	XXXDCL NT
776
777
778
 *	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:
779
780
 *
 * \code
781
782
783
784
785
786
787
788
789
790
 *		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.
791
 * \endcode
792
 *
Francis Dupont's avatar
Francis Dupont committed
793
 *\li	Zero effort has been made (yet) to accommodate systems with openlog()
794
795
796
 *	that only takes two arguments, or to identify valid syslog
 *	facilities or options for any given architecture.
 *
797
 *\li	It is necessary to call isc_log_opensyslog() to initialize
798
799
800
801
802
803
 *	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:
804
 *\li	Nothing.
805
806
 *
 * Ensures:
807
 *\li	openlog() is called to initialize the syslog system.
808
809
810
811
 */

void
isc_log_closefilelogs(isc_log_t *lctx);
812
813
/*%<
 * Close all open files used by #ISC_LOG_TOFILE channels.
814
815
 *
 * Notes:
816
 *\li	This function is provided for programs that want to use their own
817
818
 *	log rolling mechanism rather than the one provided internally.
 *	For example, a program that wanted to keep daily logs would define
819
 *	a channel which used #ISC_LOG_ROLLNEVER, then once a day would
820
821
 *	rename the log file and call isc_log_closefilelogs().
 *
822
 *\li	#ISC_LOG_TOFILEDESC channels are unaffected.
823
824
 *
 * Requires:
825
 *\li	lctx is a valid context.
826
827
 *
 * Ensures:
828
 *\li	The open files are closed and will be reopened when they are
829
830
831
 *	next needed.
 */

832
833
isc_logcategory_t *
isc_log_categorybyname(isc_log_t *lctx, const char *name);
834
/*%<
835
 * Find a category by its name.
836
 *
837
 * Notes:
838
 *\li	The string name of a category is not required to be unique.
839
 *
840
 * Requires:
841
842
 *\li	lctx is a valid context.
 *\li	name is not NULL.
843
 *
844
 * Returns:
845
 *\li	A pointer to the _first_ isc_logcategory_t structure used by "name".
846
 *
847
 *\li	NULL if no category exists by that name.
848
849
850
851
 */

isc_logmodule_t *
isc_log_modulebyname(isc_log_t *lctx, const char *name);
852
/*%<
853
 * Find a module by its name.
854
 *
855
 * Notes:
856
 *\li	The string name of a module is not required to be unique.
857
 *
858
 * Requires:
859
860
 *\li	lctx is a valid context.
 *\li	name is not NULL.
861
 *
862
 * Returns:
863
 *\li	A pointer to the _first_ isc_logmodule_t structure used by "name".
864
 *
865
 *\li	NULL if no module exists by that name.
866
867
 */

868
869
void
isc_log_setcontext(isc_log_t *lctx);
870
/*%<
871
872
873
 * Sets the context used by the libisc for logging.
 *
 * Requires:
874
 *\li	lctx be a valid context.
875
876
 */

Evan Hunt's avatar
Evan Hunt committed
877
878
879
880
881
882
883
884
885
isc_result_t
isc_logfile_roll(isc_logfile_t *file);
/*%<
 * Roll a logfile.
 *
 * Requires:
 *\li	file is not NULL.
 */

886
887
888
ISC_LANG_ENDDECLS

#endif /* ISC_LOG_H */