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