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