1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * Permission to use, copy, modify, and/or distribute this software for any 5 * purpose with or without fee is hereby granted, provided that the above 6 * copyright notice and this permission notice appear in all copies. 7 * 8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 14 * PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /* $Id: log.h,v 1.9 2024/05/17 23:56:19 jsg Exp $ */ 18 19 #ifndef ISC_LOG_H 20 #define ISC_LOG_H 1 21 22 /*! \file isc/log.h */ 23 24 #include <stdio.h> 25 #include <stdarg.h> 26 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_TOFILEDESC 3 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_DEBUGONLY 0x1000 68 #define ISC_LOG_OPENERR 0x8000 /* internal */ 69 /*@}*/ 70 71 /*@{*/ 72 /*! 73 * \brief Other options. 74 * 75 * XXXDCL INFINITE doesn't yet work. Arguably it isn't needed, but 76 * since I am intend to make large number of versions work efficiently, 77 * INFINITE is going to be trivial to add to that. 78 */ 79 #define ISC_LOG_ROLLINFINITE (-1) 80 #define ISC_LOG_ROLLNEVER (-2) 81 /*@}*/ 82 83 /*! 84 * \brief Used to name the categories used by a library. 85 * 86 * An array of isc_logcategory 87 * structures names each category, and the id value is initialized by calling 88 * isc_log_registercategories. 89 */ 90 struct isc_logcategory { 91 const char *name; 92 unsigned int id; 93 }; 94 95 /*% 96 * Similar to isc_logcategory, but for all the modules a library defines. 97 */ 98 struct isc_logmodule { 99 const char *name; 100 unsigned int id; 101 }; 102 103 /*% 104 * The isc_logfile structure is initialized as part of an isc_logdestination 105 * before calling isc_log_createchannel(). 106 * 107 * When defining an #ISC_LOG_TOFILE 108 * channel the name, versions and maximum_size should be set before calling 109 * isc_log_createchannel(). To define an #ISC_LOG_TOFILEDESC channel set only 110 * the stream before the call. 111 * 112 * Setting maximum_size to zero implies no maximum. 113 */ 114 typedef struct isc_logfile { 115 FILE *stream; /*%< Initialized to NULL for #ISC_LOG_TOFILE. */ 116 const char *name; /*%< NULL for #ISC_LOG_TOFILEDESC. */ 117 int versions; /* >= 0, #ISC_LOG_ROLLNEVER, #ISC_LOG_ROLLINFINITE. */ 118 /*% 119 * stdio's ftell is standardized to return a long, which may well not 120 * be big enough for the largest file supportable by the operating 121 * system (though it is _probably_ big enough for the largest log 122 * anyone would want). st_size returned by fstat should be typedef'd 123 * to a size large enough for the largest possible file on a system. 124 */ 125 off_t maximum_size; 126 int maximum_reached; /*%< Private. */ 127 } isc_logfile_t; 128 129 /*% 130 * Passed to isc_log_createchannel to define the attributes of either 131 * a stdio or a syslog log. 132 */ 133 typedef union isc_logdestination { 134 isc_logfile_t file; 135 int facility; /* XXXDCL NT */ 136 } isc_logdestination_t; 137 138 /*@{*/ 139 /*% 140 * The built-in categories of libisc. 141 * 142 * Each library registering categories should provide library_LOGCATEGORY_name 143 * definitions with indexes into its isc_logcategory structure corresponding to 144 * the order of the names. 145 */ 146 extern isc_logcategory_t isc_categories[]; 147 extern isc_log_t *isc_lctx; 148 extern isc_logmodule_t isc_modules[]; 149 /*@}*/ 150 151 /*@{*/ 152 /*% 153 * Do not log directly to DEFAULT. Use another category. When in doubt, 154 * use GENERAL. 155 */ 156 #define ISC_LOGCATEGORY_DEFAULT (&isc_categories[0]) 157 #define ISC_LOGCATEGORY_GENERAL (&isc_categories[1]) 158 /*@}*/ 159 160 #define ISC_LOGMODULE_SOCKET (&isc_modules[0]) 161 #define ISC_LOGMODULE_TIME (&isc_modules[1]) 162 #define ISC_LOGMODULE_INTERFACE (&isc_modules[2]) 163 #define ISC_LOGMODULE_TIMER (&isc_modules[3]) 164 #define ISC_LOGMODULE_FILE (&isc_modules[4]) 165 #define ISC_LOGMODULE_OTHER (&isc_modules[5]) 166 167 isc_result_t 168 isc_log_create(isc_log_t **lctxp, isc_logconfig_t **lcfgp); 169 /*%< 170 * Establish a new logging context, with default channels. 171 * 172 * Notes: 173 *\li isc_log_create() calls isc_logconfig_create(), so see its comment 174 * below for more information. 175 * 176 * Requires: 177 *\li mctx is a valid memory context. 178 *\li lctxp is not null and *lctxp is null. 179 *\li lcfgp is null or lcfgp is not null and *lcfgp is null. 180 * 181 * Ensures: 182 *\li *lctxp will point to a valid logging context if all of the necessary 183 * memory was allocated, or NULL otherwise. 184 *\li *lcfgp will point to a valid logging configuration if all of the 185 * necessary memory was allocated, or NULL otherwise. 186 *\li On failure, no additional memory is allocated. 187 * 188 * Returns: 189 *\li #ISC_R_SUCCESS Success 190 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 191 */ 192 193 isc_result_t 194 isc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp); 195 /*%< 196 * Create the data structure that holds all of the configurable information 197 * about where messages are actually supposed to be sent -- the information 198 * that could changed based on some configuration file, as opposed to the 199 * the category/module specification of isc_log_[v]write[1] that is compiled 200 * into a program, or the debug_level which is dynamic state information. 201 * 202 * Notes: 203 *\li It is necessary to specify the logging context the configuration 204 * will be used with because the number of categories and modules 205 * needs to be known in order to set the configuration. However, 206 * the configuration is not used by the logging context until the 207 * isc_logconfig_use function is called. 208 * 209 *\li The memory context used for operations that allocate memory for 210 * the configuration is that of the logging context, as specified 211 * in the isc_log_create call. 212 * 213 *\li Four default channels are established: 214 *\verbatim 215 * default_syslog 216 * - log to syslog's daemon facility #ISC_LOG_INFO or higher 217 * default_stderr 218 * - log to stderr #ISC_LOG_INFO or higher 219 * default_debug 220 * - log to stderr #ISC_LOG_DEBUG dynamically 221 * null 222 * - log nothing 223 *\endverbatim 224 * 225 * Requires: 226 *\li lctx is a valid logging context. 227 *\li lcftp is not null and *lcfgp is null. 228 * 229 * Ensures: 230 *\li *lcfgp will point to a valid logging context if all of the necessary 231 * memory was allocated, or NULL otherwise. 232 *\li On failure, no additional memory is allocated. 233 * 234 * Returns: 235 *\li #ISC_R_SUCCESS Success 236 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 237 */ 238 239 void 240 isc_log_destroy(isc_log_t **lctxp); 241 /*%< 242 * Deallocate the memory associated with a logging context. 243 * 244 * Requires: 245 *\li *lctx is a valid logging context. 246 * 247 * Ensures: 248 *\li All of the memory associated with the logging context is returned 249 * to the free memory pool. 250 * 251 *\li Any open files are closed. 252 * 253 *\li The logging context is marked as invalid. 254 */ 255 256 void 257 isc_logconfig_destroy(isc_logconfig_t **lcfgp); 258 /*%< 259 * Destroy a logging configuration. 260 * 261 * Notes: 262 *\li This function cannot be used directly with the return value of 263 * isc_logconfig_get, because a logging context must always have 264 * a valid configuration associated with it. 265 * 266 * Requires: 267 *\li lcfgp is not null and *lcfgp is a valid logging configuration. 268 *\li The logging configuration is not in use by an existing logging context. 269 * 270 * Ensures: 271 *\li All memory allocated for the configuration is freed. 272 * 273 *\li The configuration is marked as invalid. 274 */ 275 276 void 277 isc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]); 278 /*%< 279 * Identify logging categories a library will use. 280 * 281 * Notes: 282 *\li A category should only be registered once, but no mechanism enforces 283 * this rule. 284 * 285 *\li The end of the categories array is identified by a NULL name. 286 * 287 *\li Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not 288 * be altered or destroyed after isc_log_registercategories(). 289 * 290 *\li Because each element of the categories array is used by 291 * isc_log_categorybyname, it should not be altered or destroyed 292 * after registration. 293 * 294 *\li The value of the id integer in each structure is overwritten 295 * by this function, and so id need not be initialized to any particular 296 * value prior to the function call. 297 * 298 *\li A subsequent call to isc_log_registercategories with the same 299 * logging context (but new categories) will cause the last 300 * element of the categories array from the prior call to have 301 * its "name" member changed from NULL to point to the new 302 * categories array, and its "id" member set to UINT_MAX. 303 * 304 * Requires: 305 *\li lctx is a valid logging context. 306 *\li categories != NULL. 307 *\li categories[0].name != NULL. 308 * 309 * Ensures: 310 * \li There are references to each category in the logging context, 311 * so they can be used with isc_log_usechannel() and isc_log_write(). 312 */ 313 314 void 315 isc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]); 316 /*%< 317 * Identify logging categories a library will use. 318 * 319 * Notes: 320 *\li A module should only be registered once, but no mechanism enforces 321 * this rule. 322 * 323 *\li The end of the modules array is identified by a NULL name. 324 * 325 *\li Because the name is used by #ISC_LOG_PRINTMODULE, it should not 326 * be altered or destroyed after isc_log_registermodules(). 327 * 328 *\li Because each element of the modules array is used by 329 * isc_log_modulebyname, it should not be altered or destroyed 330 * after registration. 331 * 332 *\li The value of the id integer in each structure is overwritten 333 * by this function, and so id need not be initialized to any particular 334 * value prior to the function call. 335 * 336 *\li A subsequent call to isc_log_registermodules with the same 337 * logging context (but new modules) will cause the last 338 * element of the modules array from the prior call to have 339 * its "name" member changed from NULL to point to the new 340 * modules array, and its "id" member set to UINT_MAX. 341 * 342 * Requires: 343 *\li lctx is a valid logging context. 344 *\li modules != NULL. 345 *\li modules[0].name != NULL; 346 * 347 * Ensures: 348 *\li Each module has a reference in the logging context, so they can be 349 * used with isc_log_usechannel() and isc_log_write(). 350 */ 351 352 isc_result_t 353 isc_log_createchannel(isc_logconfig_t *lcfg, const char *name, 354 unsigned int type, int level, 355 const isc_logdestination_t *destination, 356 unsigned int flags); 357 /*%< 358 * Specify the parameters of a logging channel. 359 * 360 * Notes: 361 *\li The name argument is copied to memory in the logging context, so 362 * it can be altered or destroyed after isc_log_createchannel(). 363 * 364 *\li Defining a very large number of channels will have a performance 365 * impact on isc_log_usechannel(), since the names are searched 366 * linearly until a match is made. This same issue does not affect 367 * isc_log_write, however. 368 * 369 *\li Channel names can be redefined; this is primarily useful for programs 370 * that want their own definition of default_syslog, default_debug 371 * and default_stderr. 372 * 373 *\li Any channel that is redefined will not affect logging that was 374 * already directed to its original definition, _except_ for the 375 * default_stderr channel. This case is handled specially so that 376 * the default logging category can be changed by redefining 377 * default_stderr. (XXXDCL Though now that I think of it, the default 378 * logging category can be changed with only one additional function 379 * call by defining a new channel and then calling isc_log_usechannel() 380 * for #ISC_LOGCATEGORY_DEFAULT.) 381 * 382 *\li Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is allowed, 383 * but probably not what you wanted to do. 384 * 385 * #ISC_LOG_DEBUGONLY will mark the channel as usable only when the 386 * debug level of the logging context (see isc_log_setdebuglevel) 387 * is non-zero. 388 * 389 * Requires: 390 *\li lcfg is a valid logging configuration. 391 * 392 *\li name is not NULL. 393 * 394 *\li type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or 395 * #ISC_LOG_TONULL. 396 * 397 *\li destination is not NULL unless type is #ISC_LOG_TONULL. 398 * 399 *\li level is >= #ISC_LOG_CRITICAL (the most negative logging level). 400 * 401 *\li flags does not include any bits aside from the ISC_LOG_PRINT* bits 402 * or #ISC_LOG_DEBUGONLY. 403 * 404 * Ensures: 405 *\li #ISC_R_SUCCESS 406 * A channel with the given name is usable with 407 * isc_log_usechannel(). 408 * 409 *\li #ISC_R_NOMEMORY or #ISC_R_UNEXPECTED 410 * No additional memory is being used by the logging context. 411 * Any channel that previously existed with the given name 412 * is not redefined. 413 * 414 * Returns: 415 *\li #ISC_R_SUCCESS Success 416 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 417 *\li #ISC_R_UNEXPECTED type was out of range and REQUIRE() 418 * was disabled. 419 */ 420 421 isc_result_t 422 isc_log_usechannel(isc_logconfig_t *lcfg, const char *name, 423 const isc_logcategory_t *category, 424 const isc_logmodule_t *module); 425 /*%< 426 * Associate a named logging channel with a category and module that 427 * will use it. 428 * 429 * Notes: 430 *\li The name is searched for linearly in the set of known channel names 431 * until a match is found. (Note the performance impact of a very large 432 * number of named channels.) When multiple channels of the same 433 * name are defined, the most recent definition is found. 434 * 435 *\li Specifying a very large number of channels for a category will have 436 * a moderate impact on performance in isc_log_write(), as each 437 * call looks up the category for the start of a linked list, which 438 * it follows all the way to the end to find matching modules. The 439 * test for matching modules is integral, though. 440 * 441 *\li If category is NULL, then the channel is associated with the indicated 442 * module for all known categories (including the "default" category). 443 * 444 *\li If module is NULL, then the channel is associated with every module 445 * that uses that category. 446 * 447 *\li Passing both category and module as NULL would make every log message 448 * use the indicated channel. 449 * 450 * \li Specifying a channel that is #ISC_LOG_TONULL for a category/module pair 451 * has no effect on any other channels associated with that pair, 452 * regardless of ordering. Thus you cannot use it to "mask out" one 453 * category/module pair when you have specified some other channel that 454 * is also used by that category/module pair. 455 * 456 * Requires: 457 *\li lcfg is a valid logging configuration. 458 * 459 *\li category is NULL or has an id that is in the range of known ids. 460 * 461 * module is NULL or has an id that is in the range of known ids. 462 * 463 * Ensures: 464 *\li #ISC_R_SUCCESS 465 * The channel will be used by the indicated category/module 466 * arguments. 467 * 468 *\li #ISC_R_NOMEMORY 469 * If assignment for a specific category has been requested, 470 * the channel has not been associated with the indicated 471 * category/module arguments and no additional memory is 472 * used by the logging context. 473 * If assignment for all categories has been requested 474 * then _some_ may have succeeded (starting with category 475 * "default" and progressing through the order of categories 476 * passed to isc_log_registercategories()) and additional memory 477 * is being used by whatever assignments succeeded. 478 * 479 * Returns: 480 *\li #ISC_R_SUCCESS Success 481 *\li #ISC_R_NOMEMORY Resource limit: Out of memory 482 */ 483 484 /* Attention: next four comments PRECEED code */ 485 /*! 486 * \brief 487 * Write a message to the log channels. 488 * 489 * Notes: 490 *\li Log messages containing natural language text should be logged with 491 * isc_log_iwrite() to allow for localization. 492 * 493 *\li lctx can be NULL; this is allowed so that programs which use 494 * libraries that use the ISC logging system are not required to 495 * also use it. 496 * 497 *\li The format argument is a printf(3) string, with additional arguments 498 * as necessary. 499 * 500 * Requires: 501 *\li lctx is a valid logging context. 502 * 503 *\li The category and module arguments must have ids that are in the 504 * range of known ids, as established by isc_log_registercategories() 505 * and isc_log_registermodules(). 506 * 507 *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define 508 * channels, and explicit debugging level must be identified for 509 * isc_log_write() via ISC_LOG_DEBUG(level). 510 * 511 *\li format != NULL. 512 * 513 * Ensures: 514 *\li The log message is written to every channel associated with the 515 * indicated category/module pair. 516 * 517 * Returns: 518 *\li Nothing. Failure to log a message is not construed as a 519 * meaningful error. 520 */ 521 void 522 isc_log_write(isc_log_t *lctx, isc_logcategory_t *category, 523 isc_logmodule_t *module, int level, 524 const char *format, ...) 525 526 __attribute__((__format__(__printf__, 5, 6))); 527 528 void 529 isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level); 530 /*%< 531 * Set the debugging level used for logging. 532 * 533 * Notes: 534 *\li Setting the debugging level to 0 disables debugging log messages. 535 * 536 * Requires: 537 *\li lctx is a valid logging context. 538 * 539 * Ensures: 540 *\li The debugging level is set to the requested value. 541 */ 542 543 int 544 isc_log_wouldlog(isc_log_t *lctx, int level); 545 /*%< 546 * Determine whether logging something to 'lctx' at 'level' would 547 * actually cause something to be logged somewhere. 548 * 549 * If #0 is returned, it is guaranteed that nothing would 550 * be logged, allowing the caller to omit unnecessary 551 * isc_log_write() calls and possible message preformatting. 552 */ 553 554 void 555 isc_log_setcontext(isc_log_t *lctx); 556 /*%< 557 * Sets the context used by the libisc for logging. 558 * 559 * Requires: 560 *\li lctx be a valid context. 561 */ 562 563 #endif /* ISC_LOG_H */ 564