1 /* $NetBSD: log.h,v 1.1.1.1 2009/12/13 16:54:31 kardel Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2007, 2009 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 1999-2002 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id: log.h,v 1.54.332.5 2009/02/16 02:04:05 marka Exp */ 21 22 #ifndef ISC_LOG_H 23 #define ISC_LOG_H 1 24 25 /*! \file isc/log.h */ 26 27 #include <stdio.h> 28 #include <stdarg.h> 29 #include <syslog.h> /* XXXDCL NT */ 30 31 #include <isc/formatcheck.h> 32 #include <isc/lang.h> 33 #include <isc/platform.h> 34 #include <isc/types.h> 35 36 /*@{*/ 37 /*! 38 * \brief Severity levels, patterned after Unix's syslog levels. 39 * 40 */ 41 #define ISC_LOG_DEBUG(level) (level) 42 /*! 43 * #ISC_LOG_DYNAMIC can only be used for defining channels with 44 * isc_log_createchannel(), not to specify a level in isc_log_write(). 45 */ 46 #define ISC_LOG_DYNAMIC 0 47 #define ISC_LOG_INFO (-1) 48 #define ISC_LOG_NOTICE (-2) 49 #define ISC_LOG_WARNING (-3) 50 #define ISC_LOG_ERROR (-4) 51 #define ISC_LOG_CRITICAL (-5) 52 /*@}*/ 53 54 /*@{*/ 55 /*! 56 * \brief Destinations. 57 */ 58 #define ISC_LOG_TONULL 1 59 #define ISC_LOG_TOSYSLOG 2 60 #define ISC_LOG_TOFILE 3 61 #define ISC_LOG_TOFILEDESC 4 62 /*@}*/ 63 64 /*@{*/ 65 /*% 66 * Channel flags. 67 */ 68 #define ISC_LOG_PRINTTIME 0x0001 69 #define ISC_LOG_PRINTLEVEL 0x0002 70 #define ISC_LOG_PRINTCATEGORY 0x0004 71 #define ISC_LOG_PRINTMODULE 0x0008 72 #define ISC_LOG_PRINTTAG 0x0010 73 #define ISC_LOG_PRINTALL 0x001F 74 #define ISC_LOG_DEBUGONLY 0x1000 75 #define ISC_LOG_OPENERR 0x8000 /* internal */ 76 /*@}*/ 77 78 /*@{*/ 79 /*! 80 * \brief Other options. 81 * 82 * XXXDCL INFINITE doesn't yet work. Arguably it isn't needed, but 83 * since I am intend to make large number of versions work efficiently, 84 * INFINITE is going to be trivial to add to that. 85 */ 86 #define ISC_LOG_ROLLINFINITE (-1) 87 #define ISC_LOG_ROLLNEVER (-2) 88 /*@}*/ 89 90 /*! 91 * \brief Used to name the categories used by a library. 92 * 93 * An array of isc_logcategory 94 * structures names each category, and the id value is initialized by calling 95 * isc_log_registercategories. 96 */ 97 struct isc_logcategory { 98 const char *name; 99 unsigned int id; 100 }; 101 102 /*% 103 * Similar to isc_logcategory, but for all the modules a library defines. 104 */ 105 struct isc_logmodule { 106 const char *name; 107 unsigned int id; 108 }; 109 110 /*% 111 * The isc_logfile structure is initialized as part of an isc_logdestination 112 * before calling isc_log_createchannel(). 113 * 114 * When defining an #ISC_LOG_TOFILE 115 * channel the name, versions and maximum_size should be set before calling 116 * isc_log_createchannel(). To define an #ISC_LOG_TOFILEDESC channel set only 117 * the stream before the call. 118 * 119 * Setting maximum_size to zero implies no maximum. 120 */ 121 typedef struct isc_logfile { 122 FILE *stream; /*%< Initialized to NULL for #ISC_LOG_TOFILE. */ 123 const char *name; /*%< NULL for #ISC_LOG_TOFILEDESC. */ 124 int versions; /* >= 0, #ISC_LOG_ROLLNEVER, #ISC_LOG_ROLLINFINITE. */ 125 /*% 126 * stdio's ftell is standardized to return a long, which may well not 127 * be big enough for the largest file supportable by the operating 128 * system (though it is _probably_ big enough for the largest log 129 * anyone would want). st_size returned by fstat should be typedef'd 130 * to a size large enough for the largest possible file on a system. 131 */ 132 isc_offset_t maximum_size; 133 isc_boolean_t maximum_reached; /*%< Private. */ 134 } isc_logfile_t; 135 136 /*% 137 * Passed to isc_log_createchannel to define the attributes of either 138 * a stdio or a syslog log. 139 */ 140 typedef union isc_logdestination { 141 isc_logfile_t file; 142 int facility; /* XXXDCL NT */ 143 } isc_logdestination_t; 144 145 /*@{*/ 146 /*% 147 * The built-in categories of libisc. 148 * 149 * Each library registering categories should provide library_LOGCATEGORY_name 150 * definitions with indexes into its isc_logcategory structure corresponding to 151 * the order of the names. 152 */ 153 LIBISC_EXTERNAL_DATA extern isc_logcategory_t isc_categories[]; 154 LIBISC_EXTERNAL_DATA extern isc_log_t *isc_lctx; 155 LIBISC_EXTERNAL_DATA extern isc_logmodule_t isc_modules[]; 156 /*@}*/ 157 158 /*@{*/ 159 /*% 160 * Do not log directly to DEFAULT. Use another category. When in doubt, 161 * use GENERAL. 162 */ 163 #define ISC_LOGCATEGORY_DEFAULT (&isc_categories[0]) 164 #define ISC_LOGCATEGORY_GENERAL (&isc_categories[1]) 165 /*@}*/ 166 167 #define ISC_LOGMODULE_SOCKET (&isc_modules[0]) 168 #define ISC_LOGMODULE_TIME (&isc_modules[1]) 169 #define ISC_LOGMODULE_INTERFACE (&isc_modules[2]) 170 #define ISC_LOGMODULE_TIMER (&isc_modules[3]) 171 #define ISC_LOGMODULE_FILE (&isc_modules[4]) 172 173 ISC_LANG_BEGINDECLS 174 175 isc_result_t 176 isc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp); 177 /*%< 178 * Establish a new logging context, with default channels. 179 * 180 * Notes: 181 *\li isc_log_create() calls isc_logconfig_create(), so see its comment 182 * below for more information. 183 * 184 * Requires: 185 *\li mctx is a valid memory context. 186 *\li lctxp is not null and *lctxp is null. 187 *\li lcfgp is null or lcfgp is not null and *lcfgp is null. 188 * 189 * Ensures: 190 *\li *lctxp will point to a valid logging context if all of the necessary 191 * memory was allocated, or NULL otherwise. 192 *\li *lcfgp will point to a valid logging configuration if all of the 193 * necessary memory was allocated, or NULL otherwise. 194 *\li On failure, no additional memory is allocated. 195 * 196 * Returns: 197 *\li #ISC_R_SUCCESS Success 198 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 199 */ 200 201 isc_result_t 202 isc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp); 203 /*%< 204 * Create the data structure that holds all of the configurable information 205 * about where messages are actually supposed to be sent -- the information 206 * that could changed based on some configuration file, as opposed to the 207 * the category/module specification of isc_log_[v]write[1] that is compiled 208 * into a program, or the debug_level which is dynamic state information. 209 * 210 * Notes: 211 *\li It is necessary to specify the logging context the configuration 212 * will be used with because the number of categories and modules 213 * needs to be known in order to set the configuration. However, 214 * the configuration is not used by the logging context until the 215 * isc_logconfig_use function is called. 216 * 217 *\li The memory context used for operations that allocate memory for 218 * the configuration is that of the logging context, as specified 219 * in the isc_log_create call. 220 * 221 *\li Four default channels are established: 222 *\verbatim 223 * default_syslog 224 * - log to syslog's daemon facility #ISC_LOG_INFO or higher 225 * default_stderr 226 * - log to stderr #ISC_LOG_INFO or higher 227 * default_debug 228 * - log to stderr #ISC_LOG_DEBUG dynamically 229 * null 230 * - log nothing 231 *\endverbatim 232 * 233 * Requires: 234 *\li lctx is a valid logging context. 235 *\li lcftp is not null and *lcfgp is null. 236 * 237 * Ensures: 238 *\li *lcfgp will point to a valid logging context if all of the necessary 239 * memory was allocated, or NULL otherwise. 240 *\li On failure, no additional memory is allocated. 241 * 242 * Returns: 243 *\li #ISC_R_SUCCESS Success 244 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 245 */ 246 247 isc_logconfig_t * 248 isc_logconfig_get(isc_log_t *lctx); 249 /*%< 250 * Returns a pointer to the configuration currently in use by the log context. 251 * 252 * Requires: 253 *\li lctx is a valid context. 254 * 255 * Ensures: 256 *\li The configuration pointer is non-null. 257 * 258 * Returns: 259 *\li The configuration pointer. 260 */ 261 262 isc_result_t 263 isc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg); 264 /*%< 265 * Associate a new configuration with a logging context. 266 * 267 * Notes: 268 *\li This is thread safe. The logging context will lock a mutex 269 * before attempting to swap in the new configuration, and isc_log_doit 270 * (the internal function used by all of isc_log_[v]write[1]) locks 271 * the same lock for the duration of its use of the configuration. 272 * 273 * Requires: 274 *\li lctx is a valid logging context. 275 *\li lcfg is a valid logging configuration. 276 *\li lctx is the same configuration given to isc_logconfig_create 277 * when the configuration was created. 278 * 279 * Ensures: 280 *\li Future calls to isc_log_write will use the new configuration. 281 * 282 * Returns: 283 *\li #ISC_R_SUCCESS Success 284 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 285 */ 286 287 void 288 isc_log_destroy(isc_log_t **lctxp); 289 /*%< 290 * Deallocate the memory associated with a logging context. 291 * 292 * Requires: 293 *\li *lctx is a valid logging context. 294 * 295 * Ensures: 296 *\li All of the memory associated with the logging context is returned 297 * to the free memory pool. 298 * 299 *\li Any open files are closed. 300 * 301 *\li The logging context is marked as invalid. 302 */ 303 304 void 305 isc_logconfig_destroy(isc_logconfig_t **lcfgp); 306 /*%< 307 * Destroy a logging configuration. 308 * 309 * Notes: 310 *\li This function cannot be used directly with the return value of 311 * isc_logconfig_get, because a logging context must always have 312 * a valid configuration associated with it. 313 * 314 * Requires: 315 *\li lcfgp is not null and *lcfgp is a valid logging configuration. 316 *\li The logging configuration is not in use by an existing logging context. 317 * 318 * Ensures: 319 *\li All memory allocated for the configuration is freed. 320 * 321 *\li The configuration is marked as invalid. 322 */ 323 324 void 325 isc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]); 326 /*%< 327 * Identify logging categories a library will use. 328 * 329 * Notes: 330 *\li A category should only be registered once, but no mechanism enforces 331 * this rule. 332 * 333 *\li The end of the categories array is identified by a NULL name. 334 * 335 *\li Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not 336 * be altered or destroyed after isc_log_registercategories(). 337 * 338 *\li Because each element of the categories array is used by 339 * isc_log_categorybyname, it should not be altered or destroyed 340 * after registration. 341 * 342 *\li The value of the id integer in each structure is overwritten 343 * by this function, and so id need not be initialized to any particular 344 * value prior to the function call. 345 * 346 *\li A subsequent call to isc_log_registercategories with the same 347 * logging context (but new categories) will cause the last 348 * element of the categories array from the prior call to have 349 * its "name" member changed from NULL to point to the new 350 * categories array, and its "id" member set to UINT_MAX. 351 * 352 * Requires: 353 *\li lctx is a valid logging context. 354 *\li categories != NULL. 355 *\li categories[0].name != NULL. 356 * 357 * Ensures: 358 * \li There are references to each category in the logging context, 359 * so they can be used with isc_log_usechannel() and isc_log_write(). 360 */ 361 362 void 363 isc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]); 364 /*%< 365 * Identify logging categories a library will use. 366 * 367 * Notes: 368 *\li A module should only be registered once, but no mechanism enforces 369 * this rule. 370 * 371 *\li The end of the modules array is identified by a NULL name. 372 * 373 *\li Because the name is used by #ISC_LOG_PRINTMODULE, it should not 374 * be altered or destroyed after isc_log_registermodules(). 375 * 376 *\li Because each element of the modules array is used by 377 * isc_log_modulebyname, it should not be altered or destroyed 378 * after registration. 379 * 380 *\li The value of the id integer in each structure is overwritten 381 * by this function, and so id need not be initialized to any particular 382 * value prior to the function call. 383 * 384 *\li A subsequent call to isc_log_registermodules with the same 385 * logging context (but new modules) will cause the last 386 * element of the modules array from the prior call to have 387 * its "name" member changed from NULL to point to the new 388 * modules array, and its "id" member set to UINT_MAX. 389 * 390 * Requires: 391 *\li lctx is a valid logging context. 392 *\li modules != NULL. 393 *\li modules[0].name != NULL; 394 * 395 * Ensures: 396 *\li Each module has a reference in the logging context, so they can be 397 * used with isc_log_usechannel() and isc_log_write(). 398 */ 399 400 isc_result_t 401 isc_log_createchannel(isc_logconfig_t *lcfg, const char *name, 402 unsigned int type, int level, 403 const isc_logdestination_t *destination, 404 unsigned int flags); 405 /*%< 406 * Specify the parameters of a logging channel. 407 * 408 * Notes: 409 *\li The name argument is copied to memory in the logging context, so 410 * it can be altered or destroyed after isc_log_createchannel(). 411 * 412 *\li Defining a very large number of channels will have a performance 413 * impact on isc_log_usechannel(), since the names are searched 414 * linearly until a match is made. This same issue does not affect 415 * isc_log_write, however. 416 * 417 *\li Channel names can be redefined; this is primarily useful for programs 418 * that want their own definition of default_syslog, default_debug 419 * and default_stderr. 420 * 421 *\li Any channel that is redefined will not affect logging that was 422 * already directed to its original definition, _except_ for the 423 * default_stderr channel. This case is handled specially so that 424 * the default logging category can be changed by redefining 425 * default_stderr. (XXXDCL Though now that I think of it, the default 426 * logging category can be changed with only one additional function 427 * call by defining a new channel and then calling isc_log_usechannel() 428 * for #ISC_LOGCATEGORY_DEFAULT.) 429 * 430 *\li Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is allowed, 431 * but probably not what you wanted to do. 432 * 433 * #ISC_LOG_DEBUGONLY will mark the channel as usable only when the 434 * debug level of the logging context (see isc_log_setdebuglevel) 435 * is non-zero. 436 * 437 * Requires: 438 *\li lcfg is a valid logging configuration. 439 * 440 *\li name is not NULL. 441 * 442 *\li type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or 443 * #ISC_LOG_TONULL. 444 * 445 *\li destination is not NULL unless type is #ISC_LOG_TONULL. 446 * 447 *\li level is >= #ISC_LOG_CRITICAL (the most negative logging level). 448 * 449 *\li flags does not include any bits aside from the ISC_LOG_PRINT* bits 450 * or #ISC_LOG_DEBUGONLY. 451 * 452 * Ensures: 453 *\li #ISC_R_SUCCESS 454 * A channel with the given name is usable with 455 * isc_log_usechannel(). 456 * 457 *\li #ISC_R_NOMEMORY or #ISC_R_UNEXPECTED 458 * No additional memory is being used by the logging context. 459 * Any channel that previously existed with the given name 460 * is not redefined. 461 * 462 * Returns: 463 *\li #ISC_R_SUCCESS Success 464 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 465 *\li #ISC_R_UNEXPECTED type was out of range and REQUIRE() 466 * was disabled. 467 */ 468 469 isc_result_t 470 isc_log_usechannel(isc_logconfig_t *lcfg, const char *name, 471 const isc_logcategory_t *category, 472 const isc_logmodule_t *module); 473 /*%< 474 * Associate a named logging channel with a category and module that 475 * will use it. 476 * 477 * Notes: 478 *\li The name is searched for linearly in the set of known channel names 479 * until a match is found. (Note the performance impact of a very large 480 * number of named channels.) When multiple channels of the same 481 * name are defined, the most recent definition is found. 482 * 483 *\li Specifying a very large number of channels for a category will have 484 * a moderate impact on performance in isc_log_write(), as each 485 * call looks up the category for the start of a linked list, which 486 * it follows all the way to the end to find matching modules. The 487 * test for matching modules is integral, though. 488 * 489 *\li If category is NULL, then the channel is associated with the indicated 490 * module for all known categories (including the "default" category). 491 * 492 *\li If module is NULL, then the channel is associated with every module 493 * that uses that category. 494 * 495 *\li Passing both category and module as NULL would make every log message 496 * use the indicated channel. 497 * 498 * \li Specifying a channel that is #ISC_LOG_TONULL for a category/module pair 499 * has no effect on any other channels associated with that pair, 500 * regardless of ordering. Thus you cannot use it to "mask out" one 501 * category/module pair when you have specified some other channel that 502 * is also used by that category/module pair. 503 * 504 * Requires: 505 *\li lcfg is a valid logging configuration. 506 * 507 *\li category is NULL or has an id that is in the range of known ids. 508 * 509 * module is NULL or has an id that is in the range of known ids. 510 * 511 * Ensures: 512 *\li #ISC_R_SUCCESS 513 * The channel will be used by the indicated category/module 514 * arguments. 515 * 516 *\li #ISC_R_NOMEMORY 517 * If assignment for a specific category has been requested, 518 * the channel has not been associated with the indicated 519 * category/module arguments and no additional memory is 520 * used by the logging context. 521 * If assignment for all categories has been requested 522 * then _some_ may have succeeded (starting with category 523 * "default" and progressing through the order of categories 524 * passed to isc_log_registercategories()) and additional memory 525 * is being used by whatever assignments succeeded. 526 * 527 * Returns: 528 *\li #ISC_R_SUCCESS Success 529 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 530 */ 531 532 /* Attention: next four comments PRECEED code */ 533 /*! 534 * \brief 535 * Write a message to the log channels. 536 * 537 * Notes: 538 *\li Log messages containing natural language text should be logged with 539 * isc_log_iwrite() to allow for localization. 540 * 541 *\li lctx can be NULL; this is allowed so that programs which use 542 * libraries that use the ISC logging system are not required to 543 * also use it. 544 * 545 *\li The format argument is a printf(3) string, with additional arguments 546 * as necessary. 547 * 548 * Requires: 549 *\li lctx is a valid logging context. 550 * 551 *\li The category and module arguments must have ids that are in the 552 * range of known ids, as established by isc_log_registercategories() 553 * and isc_log_registermodules(). 554 * 555 *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define 556 * channels, and explicit debugging level must be identified for 557 * isc_log_write() via ISC_LOG_DEBUG(level). 558 * 559 *\li format != NULL. 560 * 561 * Ensures: 562 *\li The log message is written to every channel associated with the 563 * indicated category/module pair. 564 * 565 * Returns: 566 *\li Nothing. Failure to log a message is not construed as a 567 * meaningful error. 568 */ 569 void 570 isc_log_write(isc_log_t *lctx, isc_logcategory_t *category, 571 isc_logmodule_t *module, int level, 572 const char *format, ...) 573 574 ISC_FORMAT_PRINTF(5, 6); 575 576 /*% 577 * Write a message to the log channels. 578 * 579 * Notes: 580 *\li lctx can be NULL; this is allowed so that programs which use 581 * libraries that use the ISC logging system are not required to 582 * also use it. 583 * 584 *\li The format argument is a printf(3) string, with additional arguments 585 * as necessary. 586 * 587 * Requires: 588 *\li lctx is a valid logging context. 589 * 590 *\li The category and module arguments must have ids that are in the 591 * range of known ids, as established by isc_log_registercategories() 592 * and isc_log_registermodules(). 593 * 594 *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define 595 * channels, and explicit debugging level must be identified for 596 * isc_log_write() via ISC_LOG_DEBUG(level). 597 * 598 *\li format != NULL. 599 * 600 * Ensures: 601 *\li The log message is written to every channel associated with the 602 * indicated category/module pair. 603 * 604 * Returns: 605 *\li Nothing. Failure to log a message is not construed as a 606 * meaningful error. 607 */ 608 void 609 isc_log_vwrite(isc_log_t *lctx, isc_logcategory_t *category, 610 isc_logmodule_t *module, int level, 611 const char *format, va_list args) 612 613 ISC_FORMAT_PRINTF(5, 0); 614 615 /*% 616 * Write a message to the log channels, pruning duplicates that occur within 617 * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval). 618 * This function is otherwise identical to isc_log_write(). 619 */ 620 void 621 isc_log_write1(isc_log_t *lctx, isc_logcategory_t *category, 622 isc_logmodule_t *module, int level, const char *format, ...) 623 624 ISC_FORMAT_PRINTF(5, 6); 625 626 /*% 627 * Write a message to the log channels, pruning duplicates that occur within 628 * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval). 629 * This function is otherwise identical to isc_log_vwrite(). 630 */ 631 void 632 isc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category, 633 isc_logmodule_t *module, int level, const char *format, 634 va_list args) 635 636 ISC_FORMAT_PRINTF(5, 0); 637 638 /*% 639 * These are four internationalized versions of the isc_log_[v]write[1] 640 * functions. 641 * 642 * The only difference is that they take arguments for a message 643 * catalog, message set, and message number, all immediately preceding the 644 * format argument. The format argument becomes the default text, a la 645 * isc_msgcat_get. If the message catalog is NULL, no lookup is attempted 646 * for a message -- which makes the message set and message number irrelevant, 647 * and the non-internationalized call should have probably been used instead. 648 * 649 * Yes, that means there are now *eight* interfaces to logging a message. 650 * Sheesh. Make the madness stop! 651 */ 652 /*@{*/ 653 void 654 isc_log_iwrite(isc_log_t *lctx, isc_logcategory_t *category, 655 isc_logmodule_t *module, int level, 656 isc_msgcat_t *msgcat, int msgset, int message, 657 const char *format, ...) 658 ISC_FORMAT_PRINTF(8, 9); 659 660 void 661 isc_log_ivwrite(isc_log_t *lctx, isc_logcategory_t *category, 662 isc_logmodule_t *module, int level, 663 isc_msgcat_t *msgcat, int msgset, int message, 664 const char *format, va_list args) 665 ISC_FORMAT_PRINTF(8, 0); 666 667 void 668 isc_log_iwrite1(isc_log_t *lctx, isc_logcategory_t *category, 669 isc_logmodule_t *module, int level, 670 isc_msgcat_t *msgcat, int msgset, int message, 671 const char *format, ...) 672 ISC_FORMAT_PRINTF(8, 9); 673 674 void 675 isc_log_ivwrite1(isc_log_t *lctx, isc_logcategory_t *category, 676 isc_logmodule_t *module, int level, 677 isc_msgcat_t *msgcat, int msgset, int message, 678 const char *format, va_list args) 679 ISC_FORMAT_PRINTF(8, 0); 680 /*@}*/ 681 682 void 683 isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level); 684 /*%< 685 * Set the debugging level used for logging. 686 * 687 * Notes: 688 *\li Setting the debugging level to 0 disables debugging log messages. 689 * 690 * Requires: 691 *\li lctx is a valid logging context. 692 * 693 * Ensures: 694 *\li The debugging level is set to the requested value. 695 */ 696 697 unsigned int 698 isc_log_getdebuglevel(isc_log_t *lctx); 699 /*%< 700 * Get the current debugging level. 701 * 702 * Notes: 703 *\li This is provided so that a program can have a notion of 704 * "increment debugging level" or "decrement debugging level" 705 * without needing to keep track of what the current level is. 706 * 707 *\li A return value of 0 indicates that debugging messages are disabled. 708 * 709 * Requires: 710 *\li lctx is a valid logging context. 711 * 712 * Ensures: 713 *\li The current logging debugging level is returned. 714 */ 715 716 isc_boolean_t 717 isc_log_wouldlog(isc_log_t *lctx, int level); 718 /*%< 719 * Determine whether logging something to 'lctx' at 'level' would 720 * actually cause something to be logged somewhere. 721 * 722 * If #ISC_FALSE is returned, it is guaranteed that nothing would 723 * be logged, allowing the caller to omit unnecessary 724 * isc_log_write() calls and possible message preformatting. 725 */ 726 727 void 728 isc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval); 729 /*%< 730 * Set the interval over which duplicate log messages will be ignored 731 * by isc_log_[v]write1(), in seconds. 732 * 733 * Notes: 734 *\li Increasing the duplicate interval from X to Y will not necessarily 735 * filter out duplicates of messages logged in Y - X seconds since the 736 * increase. (Example: Message1 is logged at midnight. Message2 737 * is logged at 00:01:00, when the interval is only 30 seconds, causing 738 * Message1 to be expired from the log message history. Then the interval 739 * is increased to 3000 (five minutes) and at 00:04:00 Message1 is logged 740 * again. It will appear the second time even though less than five 741 * passed since the first occurrence. 742 * 743 * Requires: 744 *\li lctx is a valid logging context. 745 */ 746 747 unsigned int 748 isc_log_getduplicateinterval(isc_logconfig_t *lcfg); 749 /*%< 750 * Get the current duplicate filtering interval. 751 * 752 * Requires: 753 *\li lctx is a valid logging context. 754 * 755 * Returns: 756 *\li The current duplicate filtering interval. 757 */ 758 759 isc_result_t 760 isc_log_settag(isc_logconfig_t *lcfg, const char *tag); 761 /*%< 762 * Set the program name or other identifier for #ISC_LOG_PRINTTAG. 763 * 764 * Requires: 765 *\li lcfg is a valid logging configuration. 766 * 767 * Notes: 768 *\li If this function has not set the tag to a non-NULL, non-empty value, 769 * then the #ISC_LOG_PRINTTAG channel flag will not print anything. 770 * Unlike some implementations of syslog on Unix systems, you *must* set 771 * the tag in order to get it logged. It is not implicitly derived from 772 * the program name (which is pretty impossible to infer portably). 773 * 774 *\li Setting the tag to NULL or the empty string will also cause the 775 * #ISC_LOG_PRINTTAG channel flag to not print anything. If tag equals the 776 * empty string, calls to isc_log_gettag will return NULL. 777 * 778 * Returns: 779 *\li #ISC_R_SUCCESS Success 780 *\li #ISC_R_NOMEMORY Resource Limit: Out of memory 781 * 782 * XXXDCL when creating a new isc_logconfig_t, it might be nice if the tag 783 * of the currently active isc_logconfig_t was inherited. this does not 784 * currently happen. 785 */ 786 787 char * 788 isc_log_gettag(isc_logconfig_t *lcfg); 789 /*%< 790 * Get the current identifier printed with #ISC_LOG_PRINTTAG. 791 * 792 * Requires: 793 *\li lcfg is a valid logging configuration. 794 * 795 * Notes: 796 *\li Since isc_log_settag() will not associate a zero-length string 797 * with the logging configuration, attempts to do so will cause 798 * this function to return NULL. However, a determined programmer 799 * will observe that (currently) a tag of length greater than zero 800 * could be set, and then modified to be zero length. 801 * 802 * Returns: 803 *\li A pointer to the current identifier, or NULL if none has been set. 804 */ 805 806 void 807 isc_log_opensyslog(const char *tag, int options, int facility); 808 /*%< 809 * Initialize syslog logging. 810 * 811 * Notes: 812 *\li XXXDCL NT 813 * This is currently equivalent to openlog(), but is not going to remain 814 * that way. In the meantime, the arguments are all identical to 815 * those used by openlog(3), as follows: 816 * 817 * \code 818 * tag: The string to use in the position of the program 819 * name in syslog messages. Most (all?) syslogs 820 * will use basename(argv[0]) if tag is NULL. 821 * 822 * options: LOG_CONS, LOG_PID, LOG_NDELAY ... whatever your 823 * syslog supports. 824 * 825 * facility: The default syslog facility. This is irrelevant 826 * since isc_log_write will ALWAYS use the channel's 827 * declared facility. 828 * \endcode 829 * 830 *\li Zero effort has been made (yet) to accommodate systems with openlog() 831 * that only takes two arguments, or to identify valid syslog 832 * facilities or options for any given architecture. 833 * 834 *\li It is necessary to call isc_log_opensyslog() to initialize 835 * syslogging on machines which do not support network connections to 836 * syslogd because they require a Unix domain socket to be used. Since 837 * this is a chore to determine at run-time, it is suggested that it 838 * always be called by programs using the ISC logging system. 839 * 840 * Requires: 841 *\li Nothing. 842 * 843 * Ensures: 844 *\li openlog() is called to initialize the syslog system. 845 */ 846 847 void 848 isc_log_closefilelogs(isc_log_t *lctx); 849 /*%< 850 * Close all open files used by #ISC_LOG_TOFILE channels. 851 * 852 * Notes: 853 *\li This function is provided for programs that want to use their own 854 * log rolling mechanism rather than the one provided internally. 855 * For example, a program that wanted to keep daily logs would define 856 * a channel which used #ISC_LOG_ROLLNEVER, then once a day would 857 * rename the log file and call isc_log_closefilelogs(). 858 * 859 *\li #ISC_LOG_TOFILEDESC channels are unaffected. 860 * 861 * Requires: 862 *\li lctx is a valid context. 863 * 864 * Ensures: 865 *\li The open files are closed and will be reopened when they are 866 * next needed. 867 */ 868 869 isc_logcategory_t * 870 isc_log_categorybyname(isc_log_t *lctx, const char *name); 871 /*%< 872 * Find a category by its name. 873 * 874 * Notes: 875 *\li The string name of a category is not required to be unique. 876 * 877 * Requires: 878 *\li lctx is a valid context. 879 *\li name is not NULL. 880 * 881 * Returns: 882 *\li A pointer to the _first_ isc_logcategory_t structure used by "name". 883 * 884 *\li NULL if no category exists by that name. 885 */ 886 887 isc_logmodule_t * 888 isc_log_modulebyname(isc_log_t *lctx, const char *name); 889 /*%< 890 * Find a module by its name. 891 * 892 * Notes: 893 *\li The string name of a module is not required to be unique. 894 * 895 * Requires: 896 *\li lctx is a valid context. 897 *\li name is not NULL. 898 * 899 * Returns: 900 *\li A pointer to the _first_ isc_logmodule_t structure used by "name". 901 * 902 *\li NULL if no module exists by that name. 903 */ 904 905 void 906 isc_log_setcontext(isc_log_t *lctx); 907 /*%< 908 * Sets the context used by the libisc for logging. 909 * 910 * Requires: 911 *\li lctx be a valid context. 912 */ 913 914 ISC_LANG_ENDDECLS 915 916 #endif /* ISC_LOG_H */ 917