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