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