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