1258945Sroberto/* 2258945Sroberto * Copyright (C) 2004-2007, 2009 Internet Systems Consortium, Inc. ("ISC") 3258945Sroberto * Copyright (C) 1999-2002 Internet Software Consortium. 4258945Sroberto * 5258945Sroberto * Permission to use, copy, modify, and/or distribute this software for any 6258945Sroberto * purpose with or without fee is hereby granted, provided that the above 7258945Sroberto * copyright notice and this permission notice appear in all copies. 8258945Sroberto * 9258945Sroberto * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10258945Sroberto * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11258945Sroberto * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12258945Sroberto * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13258945Sroberto * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14258945Sroberto * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15258945Sroberto * PERFORMANCE OF THIS SOFTWARE. 16258945Sroberto */ 17258945Sroberto 18280849Scy/* $Id: log.h,v 1.59 2009/02/16 02:01:16 marka Exp $ */ 19258945Sroberto 20258945Sroberto#ifndef ISC_LOG_H 21258945Sroberto#define ISC_LOG_H 1 22258945Sroberto 23258945Sroberto/*! \file isc/log.h */ 24258945Sroberto 25258945Sroberto#include <stdio.h> 26258945Sroberto#include <stdarg.h> 27258945Sroberto#include <syslog.h> /* XXXDCL NT */ 28258945Sroberto 29258945Sroberto#include <isc/formatcheck.h> 30258945Sroberto#include <isc/lang.h> 31258945Sroberto#include <isc/platform.h> 32258945Sroberto#include <isc/types.h> 33258945Sroberto 34258945Sroberto/*@{*/ 35258945Sroberto/*! 36258945Sroberto * \brief Severity levels, patterned after Unix's syslog levels. 37258945Sroberto * 38258945Sroberto */ 39258945Sroberto#define ISC_LOG_DEBUG(level) (level) 40258945Sroberto/*! 41258945Sroberto * #ISC_LOG_DYNAMIC can only be used for defining channels with 42258945Sroberto * isc_log_createchannel(), not to specify a level in isc_log_write(). 43258945Sroberto */ 44258945Sroberto#define ISC_LOG_DYNAMIC 0 45258945Sroberto#define ISC_LOG_INFO (-1) 46258945Sroberto#define ISC_LOG_NOTICE (-2) 47258945Sroberto#define ISC_LOG_WARNING (-3) 48258945Sroberto#define ISC_LOG_ERROR (-4) 49258945Sroberto#define ISC_LOG_CRITICAL (-5) 50258945Sroberto/*@}*/ 51258945Sroberto 52258945Sroberto/*@{*/ 53258945Sroberto/*! 54258945Sroberto * \brief Destinations. 55258945Sroberto */ 56258945Sroberto#define ISC_LOG_TONULL 1 57258945Sroberto#define ISC_LOG_TOSYSLOG 2 58258945Sroberto#define ISC_LOG_TOFILE 3 59258945Sroberto#define ISC_LOG_TOFILEDESC 4 60258945Sroberto/*@}*/ 61258945Sroberto 62258945Sroberto/*@{*/ 63258945Sroberto/*% 64258945Sroberto * Channel flags. 65258945Sroberto */ 66258945Sroberto#define ISC_LOG_PRINTTIME 0x0001 67258945Sroberto#define ISC_LOG_PRINTLEVEL 0x0002 68258945Sroberto#define ISC_LOG_PRINTCATEGORY 0x0004 69258945Sroberto#define ISC_LOG_PRINTMODULE 0x0008 70258945Sroberto#define ISC_LOG_PRINTTAG 0x0010 71258945Sroberto#define ISC_LOG_PRINTALL 0x001F 72258945Sroberto#define ISC_LOG_DEBUGONLY 0x1000 73258945Sroberto#define ISC_LOG_OPENERR 0x8000 /* internal */ 74258945Sroberto/*@}*/ 75258945Sroberto 76258945Sroberto/*@{*/ 77258945Sroberto/*! 78258945Sroberto * \brief Other options. 79258945Sroberto * 80258945Sroberto * XXXDCL INFINITE doesn't yet work. Arguably it isn't needed, but 81258945Sroberto * since I am intend to make large number of versions work efficiently, 82258945Sroberto * INFINITE is going to be trivial to add to that. 83258945Sroberto */ 84258945Sroberto#define ISC_LOG_ROLLINFINITE (-1) 85258945Sroberto#define ISC_LOG_ROLLNEVER (-2) 86258945Sroberto/*@}*/ 87258945Sroberto 88258945Sroberto/*! 89258945Sroberto * \brief Used to name the categories used by a library. 90258945Sroberto * 91258945Sroberto * An array of isc_logcategory 92258945Sroberto * structures names each category, and the id value is initialized by calling 93258945Sroberto * isc_log_registercategories. 94258945Sroberto */ 95258945Srobertostruct isc_logcategory { 96258945Sroberto const char *name; 97258945Sroberto unsigned int id; 98258945Sroberto}; 99258945Sroberto 100258945Sroberto/*% 101258945Sroberto * Similar to isc_logcategory, but for all the modules a library defines. 102258945Sroberto */ 103258945Srobertostruct isc_logmodule { 104258945Sroberto const char *name; 105258945Sroberto unsigned int id; 106258945Sroberto}; 107258945Sroberto 108258945Sroberto/*% 109258945Sroberto * The isc_logfile structure is initialized as part of an isc_logdestination 110258945Sroberto * before calling isc_log_createchannel(). 111258945Sroberto * 112258945Sroberto * When defining an #ISC_LOG_TOFILE 113258945Sroberto * channel the name, versions and maximum_size should be set before calling 114258945Sroberto * isc_log_createchannel(). To define an #ISC_LOG_TOFILEDESC channel set only 115258945Sroberto * the stream before the call. 116258945Sroberto * 117258945Sroberto * Setting maximum_size to zero implies no maximum. 118258945Sroberto */ 119258945Srobertotypedef struct isc_logfile { 120258945Sroberto FILE *stream; /*%< Initialized to NULL for #ISC_LOG_TOFILE. */ 121258945Sroberto const char *name; /*%< NULL for #ISC_LOG_TOFILEDESC. */ 122258945Sroberto int versions; /* >= 0, #ISC_LOG_ROLLNEVER, #ISC_LOG_ROLLINFINITE. */ 123258945Sroberto /*% 124258945Sroberto * stdio's ftell is standardized to return a long, which may well not 125258945Sroberto * be big enough for the largest file supportable by the operating 126258945Sroberto * system (though it is _probably_ big enough for the largest log 127258945Sroberto * anyone would want). st_size returned by fstat should be typedef'd 128258945Sroberto * to a size large enough for the largest possible file on a system. 129258945Sroberto */ 130258945Sroberto isc_offset_t maximum_size; 131258945Sroberto isc_boolean_t maximum_reached; /*%< Private. */ 132258945Sroberto} isc_logfile_t; 133258945Sroberto 134258945Sroberto/*% 135258945Sroberto * Passed to isc_log_createchannel to define the attributes of either 136258945Sroberto * a stdio or a syslog log. 137258945Sroberto */ 138258945Srobertotypedef union isc_logdestination { 139258945Sroberto isc_logfile_t file; 140258945Sroberto int facility; /* XXXDCL NT */ 141258945Sroberto} isc_logdestination_t; 142258945Sroberto 143258945Sroberto/*@{*/ 144258945Sroberto/*% 145258945Sroberto * The built-in categories of libisc. 146258945Sroberto * 147258945Sroberto * Each library registering categories should provide library_LOGCATEGORY_name 148258945Sroberto * definitions with indexes into its isc_logcategory structure corresponding to 149258945Sroberto * the order of the names. 150258945Sroberto */ 151258945SrobertoLIBISC_EXTERNAL_DATA extern isc_logcategory_t isc_categories[]; 152258945SrobertoLIBISC_EXTERNAL_DATA extern isc_log_t *isc_lctx; 153258945SrobertoLIBISC_EXTERNAL_DATA extern isc_logmodule_t isc_modules[]; 154258945Sroberto/*@}*/ 155258945Sroberto 156258945Sroberto/*@{*/ 157258945Sroberto/*% 158258945Sroberto * Do not log directly to DEFAULT. Use another category. When in doubt, 159258945Sroberto * use GENERAL. 160258945Sroberto */ 161258945Sroberto#define ISC_LOGCATEGORY_DEFAULT (&isc_categories[0]) 162258945Sroberto#define ISC_LOGCATEGORY_GENERAL (&isc_categories[1]) 163258945Sroberto/*@}*/ 164258945Sroberto 165258945Sroberto#define ISC_LOGMODULE_SOCKET (&isc_modules[0]) 166258945Sroberto#define ISC_LOGMODULE_TIME (&isc_modules[1]) 167258945Sroberto#define ISC_LOGMODULE_INTERFACE (&isc_modules[2]) 168258945Sroberto#define ISC_LOGMODULE_TIMER (&isc_modules[3]) 169258945Sroberto#define ISC_LOGMODULE_FILE (&isc_modules[4]) 170258945Sroberto 171258945SrobertoISC_LANG_BEGINDECLS 172258945Sroberto 173258945Srobertoisc_result_t 174258945Srobertoisc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp); 175258945Sroberto/*%< 176258945Sroberto * Establish a new logging context, with default channels. 177258945Sroberto * 178258945Sroberto * Notes: 179258945Sroberto *\li isc_log_create() calls isc_logconfig_create(), so see its comment 180258945Sroberto * below for more information. 181258945Sroberto * 182258945Sroberto * Requires: 183258945Sroberto *\li mctx is a valid memory context. 184258945Sroberto *\li lctxp is not null and *lctxp is null. 185258945Sroberto *\li lcfgp is null or lcfgp is not null and *lcfgp is null. 186258945Sroberto * 187258945Sroberto * Ensures: 188258945Sroberto *\li *lctxp will point to a valid logging context if all of the necessary 189258945Sroberto * memory was allocated, or NULL otherwise. 190258945Sroberto *\li *lcfgp will point to a valid logging configuration if all of the 191258945Sroberto * necessary memory was allocated, or NULL otherwise. 192258945Sroberto *\li On failure, no additional memory is allocated. 193258945Sroberto * 194258945Sroberto * Returns: 195258945Sroberto *\li #ISC_R_SUCCESS Success 196258945Sroberto *\li #ISC_R_NOMEMORY Resource limit: Out of memory 197258945Sroberto */ 198258945Sroberto 199258945Srobertoisc_result_t 200258945Srobertoisc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp); 201258945Sroberto/*%< 202258945Sroberto * Create the data structure that holds all of the configurable information 203258945Sroberto * about where messages are actually supposed to be sent -- the information 204258945Sroberto * that could changed based on some configuration file, as opposed to the 205258945Sroberto * the category/module specification of isc_log_[v]write[1] that is compiled 206258945Sroberto * into a program, or the debug_level which is dynamic state information. 207258945Sroberto * 208258945Sroberto * Notes: 209258945Sroberto *\li It is necessary to specify the logging context the configuration 210258945Sroberto * will be used with because the number of categories and modules 211258945Sroberto * needs to be known in order to set the configuration. However, 212258945Sroberto * the configuration is not used by the logging context until the 213258945Sroberto * isc_logconfig_use function is called. 214258945Sroberto * 215258945Sroberto *\li The memory context used for operations that allocate memory for 216258945Sroberto * the configuration is that of the logging context, as specified 217258945Sroberto * in the isc_log_create call. 218258945Sroberto * 219258945Sroberto *\li Four default channels are established: 220258945Sroberto *\verbatim 221258945Sroberto * default_syslog 222258945Sroberto * - log to syslog's daemon facility #ISC_LOG_INFO or higher 223258945Sroberto * default_stderr 224258945Sroberto * - log to stderr #ISC_LOG_INFO or higher 225258945Sroberto * default_debug 226258945Sroberto * - log to stderr #ISC_LOG_DEBUG dynamically 227258945Sroberto * null 228258945Sroberto * - log nothing 229258945Sroberto *\endverbatim 230258945Sroberto * 231258945Sroberto * Requires: 232258945Sroberto *\li lctx is a valid logging context. 233258945Sroberto *\li lcftp is not null and *lcfgp is null. 234258945Sroberto * 235258945Sroberto * Ensures: 236258945Sroberto *\li *lcfgp will point to a valid logging context if all of the necessary 237258945Sroberto * memory was allocated, or NULL otherwise. 238258945Sroberto *\li On failure, no additional memory is allocated. 239258945Sroberto * 240258945Sroberto * Returns: 241258945Sroberto *\li #ISC_R_SUCCESS Success 242258945Sroberto *\li #ISC_R_NOMEMORY Resource limit: Out of memory 243258945Sroberto */ 244258945Sroberto 245258945Srobertoisc_logconfig_t * 246258945Srobertoisc_logconfig_get(isc_log_t *lctx); 247258945Sroberto/*%< 248258945Sroberto * Returns a pointer to the configuration currently in use by the log context. 249258945Sroberto * 250258945Sroberto * Requires: 251258945Sroberto *\li lctx is a valid context. 252258945Sroberto * 253258945Sroberto * Ensures: 254258945Sroberto *\li The configuration pointer is non-null. 255258945Sroberto * 256258945Sroberto * Returns: 257258945Sroberto *\li The configuration pointer. 258258945Sroberto */ 259258945Sroberto 260258945Srobertoisc_result_t 261258945Srobertoisc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg); 262258945Sroberto/*%< 263258945Sroberto * Associate a new configuration with a logging context. 264258945Sroberto * 265258945Sroberto * Notes: 266258945Sroberto *\li This is thread safe. The logging context will lock a mutex 267258945Sroberto * before attempting to swap in the new configuration, and isc_log_doit 268258945Sroberto * (the internal function used by all of isc_log_[v]write[1]) locks 269258945Sroberto * the same lock for the duration of its use of the configuration. 270258945Sroberto * 271258945Sroberto * Requires: 272258945Sroberto *\li lctx is a valid logging context. 273258945Sroberto *\li lcfg is a valid logging configuration. 274258945Sroberto *\li lctx is the same configuration given to isc_logconfig_create 275258945Sroberto * when the configuration was created. 276258945Sroberto * 277258945Sroberto * Ensures: 278258945Sroberto *\li Future calls to isc_log_write will use the new configuration. 279258945Sroberto * 280258945Sroberto * Returns: 281258945Sroberto *\li #ISC_R_SUCCESS Success 282258945Sroberto *\li #ISC_R_NOMEMORY Resource limit: Out of memory 283258945Sroberto */ 284258945Sroberto 285258945Srobertovoid 286258945Srobertoisc_log_destroy(isc_log_t **lctxp); 287258945Sroberto/*%< 288258945Sroberto * Deallocate the memory associated with a logging context. 289258945Sroberto * 290258945Sroberto * Requires: 291258945Sroberto *\li *lctx is a valid logging context. 292258945Sroberto * 293258945Sroberto * Ensures: 294258945Sroberto *\li All of the memory associated with the logging context is returned 295258945Sroberto * to the free memory pool. 296258945Sroberto * 297258945Sroberto *\li Any open files are closed. 298258945Sroberto * 299258945Sroberto *\li The logging context is marked as invalid. 300258945Sroberto */ 301258945Sroberto 302258945Srobertovoid 303258945Srobertoisc_logconfig_destroy(isc_logconfig_t **lcfgp); 304258945Sroberto/*%< 305258945Sroberto * Destroy a logging configuration. 306258945Sroberto * 307258945Sroberto * Notes: 308258945Sroberto *\li This function cannot be used directly with the return value of 309258945Sroberto * isc_logconfig_get, because a logging context must always have 310258945Sroberto * a valid configuration associated with it. 311258945Sroberto * 312258945Sroberto * Requires: 313258945Sroberto *\li lcfgp is not null and *lcfgp is a valid logging configuration. 314258945Sroberto *\li The logging configuration is not in use by an existing logging context. 315258945Sroberto * 316258945Sroberto * Ensures: 317258945Sroberto *\li All memory allocated for the configuration is freed. 318258945Sroberto * 319258945Sroberto *\li The configuration is marked as invalid. 320258945Sroberto */ 321258945Sroberto 322258945Srobertovoid 323258945Srobertoisc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]); 324258945Sroberto/*%< 325258945Sroberto * Identify logging categories a library will use. 326258945Sroberto * 327258945Sroberto * Notes: 328258945Sroberto *\li A category should only be registered once, but no mechanism enforces 329258945Sroberto * this rule. 330258945Sroberto * 331258945Sroberto *\li The end of the categories array is identified by a NULL name. 332258945Sroberto * 333258945Sroberto *\li Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not 334258945Sroberto * be altered or destroyed after isc_log_registercategories(). 335258945Sroberto * 336258945Sroberto *\li Because each element of the categories array is used by 337258945Sroberto * isc_log_categorybyname, it should not be altered or destroyed 338258945Sroberto * after registration. 339258945Sroberto * 340258945Sroberto *\li The value of the id integer in each structure is overwritten 341258945Sroberto * by this function, and so id need not be initialized to any particular 342258945Sroberto * value prior to the function call. 343258945Sroberto * 344258945Sroberto *\li A subsequent call to isc_log_registercategories with the same 345258945Sroberto * logging context (but new categories) will cause the last 346258945Sroberto * element of the categories array from the prior call to have 347258945Sroberto * its "name" member changed from NULL to point to the new 348258945Sroberto * categories array, and its "id" member set to UINT_MAX. 349258945Sroberto * 350258945Sroberto * Requires: 351258945Sroberto *\li lctx is a valid logging context. 352258945Sroberto *\li categories != NULL. 353258945Sroberto *\li categories[0].name != NULL. 354258945Sroberto * 355258945Sroberto * Ensures: 356258945Sroberto * \li There are references to each category in the logging context, 357258945Sroberto * so they can be used with isc_log_usechannel() and isc_log_write(). 358258945Sroberto */ 359258945Sroberto 360258945Srobertovoid 361258945Srobertoisc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]); 362258945Sroberto/*%< 363258945Sroberto * Identify logging categories a library will use. 364258945Sroberto * 365258945Sroberto * Notes: 366258945Sroberto *\li A module should only be registered once, but no mechanism enforces 367258945Sroberto * this rule. 368258945Sroberto * 369258945Sroberto *\li The end of the modules array is identified by a NULL name. 370258945Sroberto * 371258945Sroberto *\li Because the name is used by #ISC_LOG_PRINTMODULE, it should not 372258945Sroberto * be altered or destroyed after isc_log_registermodules(). 373258945Sroberto * 374258945Sroberto *\li Because each element of the modules array is used by 375258945Sroberto * isc_log_modulebyname, it should not be altered or destroyed 376258945Sroberto * after registration. 377258945Sroberto * 378258945Sroberto *\li The value of the id integer in each structure is overwritten 379258945Sroberto * by this function, and so id need not be initialized to any particular 380258945Sroberto * value prior to the function call. 381258945Sroberto * 382258945Sroberto *\li A subsequent call to isc_log_registermodules with the same 383258945Sroberto * logging context (but new modules) will cause the last 384258945Sroberto * element of the modules array from the prior call to have 385258945Sroberto * its "name" member changed from NULL to point to the new 386258945Sroberto * modules array, and its "id" member set to UINT_MAX. 387258945Sroberto * 388258945Sroberto * Requires: 389258945Sroberto *\li lctx is a valid logging context. 390258945Sroberto *\li modules != NULL. 391258945Sroberto *\li modules[0].name != NULL; 392258945Sroberto * 393258945Sroberto * Ensures: 394258945Sroberto *\li Each module has a reference in the logging context, so they can be 395258945Sroberto * used with isc_log_usechannel() and isc_log_write(). 396258945Sroberto */ 397258945Sroberto 398258945Srobertoisc_result_t 399258945Srobertoisc_log_createchannel(isc_logconfig_t *lcfg, const char *name, 400258945Sroberto unsigned int type, int level, 401258945Sroberto const isc_logdestination_t *destination, 402258945Sroberto unsigned int flags); 403258945Sroberto/*%< 404258945Sroberto * Specify the parameters of a logging channel. 405258945Sroberto * 406258945Sroberto * Notes: 407258945Sroberto *\li The name argument is copied to memory in the logging context, so 408258945Sroberto * it can be altered or destroyed after isc_log_createchannel(). 409258945Sroberto * 410258945Sroberto *\li Defining a very large number of channels will have a performance 411258945Sroberto * impact on isc_log_usechannel(), since the names are searched 412258945Sroberto * linearly until a match is made. This same issue does not affect 413258945Sroberto * isc_log_write, however. 414258945Sroberto * 415258945Sroberto *\li Channel names can be redefined; this is primarily useful for programs 416258945Sroberto * that want their own definition of default_syslog, default_debug 417258945Sroberto * and default_stderr. 418258945Sroberto * 419258945Sroberto *\li Any channel that is redefined will not affect logging that was 420258945Sroberto * already directed to its original definition, _except_ for the 421258945Sroberto * default_stderr channel. This case is handled specially so that 422258945Sroberto * the default logging category can be changed by redefining 423258945Sroberto * default_stderr. (XXXDCL Though now that I think of it, the default 424258945Sroberto * logging category can be changed with only one additional function 425258945Sroberto * call by defining a new channel and then calling isc_log_usechannel() 426258945Sroberto * for #ISC_LOGCATEGORY_DEFAULT.) 427258945Sroberto * 428258945Sroberto *\li Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is allowed, 429258945Sroberto * but probably not what you wanted to do. 430258945Sroberto * 431258945Sroberto * #ISC_LOG_DEBUGONLY will mark the channel as usable only when the 432258945Sroberto * debug level of the logging context (see isc_log_setdebuglevel) 433258945Sroberto * is non-zero. 434258945Sroberto * 435258945Sroberto * Requires: 436258945Sroberto *\li lcfg is a valid logging configuration. 437258945Sroberto * 438258945Sroberto *\li name is not NULL. 439258945Sroberto * 440258945Sroberto *\li type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or 441258945Sroberto * #ISC_LOG_TONULL. 442258945Sroberto * 443258945Sroberto *\li destination is not NULL unless type is #ISC_LOG_TONULL. 444258945Sroberto * 445258945Sroberto *\li level is >= #ISC_LOG_CRITICAL (the most negative logging level). 446258945Sroberto * 447258945Sroberto *\li flags does not include any bits aside from the ISC_LOG_PRINT* bits 448258945Sroberto * or #ISC_LOG_DEBUGONLY. 449258945Sroberto * 450258945Sroberto * Ensures: 451258945Sroberto *\li #ISC_R_SUCCESS 452258945Sroberto * A channel with the given name is usable with 453258945Sroberto * isc_log_usechannel(). 454258945Sroberto * 455258945Sroberto *\li #ISC_R_NOMEMORY or #ISC_R_UNEXPECTED 456258945Sroberto * No additional memory is being used by the logging context. 457258945Sroberto * Any channel that previously existed with the given name 458258945Sroberto * is not redefined. 459258945Sroberto * 460258945Sroberto * Returns: 461258945Sroberto *\li #ISC_R_SUCCESS Success 462258945Sroberto *\li #ISC_R_NOMEMORY Resource limit: Out of memory 463258945Sroberto *\li #ISC_R_UNEXPECTED type was out of range and REQUIRE() 464258945Sroberto * was disabled. 465258945Sroberto */ 466258945Sroberto 467258945Srobertoisc_result_t 468258945Srobertoisc_log_usechannel(isc_logconfig_t *lcfg, const char *name, 469258945Sroberto const isc_logcategory_t *category, 470258945Sroberto const isc_logmodule_t *module); 471258945Sroberto/*%< 472258945Sroberto * Associate a named logging channel with a category and module that 473258945Sroberto * will use it. 474258945Sroberto * 475258945Sroberto * Notes: 476258945Sroberto *\li The name is searched for linearly in the set of known channel names 477258945Sroberto * until a match is found. (Note the performance impact of a very large 478258945Sroberto * number of named channels.) When multiple channels of the same 479258945Sroberto * name are defined, the most recent definition is found. 480258945Sroberto * 481258945Sroberto *\li Specifying a very large number of channels for a category will have 482258945Sroberto * a moderate impact on performance in isc_log_write(), as each 483258945Sroberto * call looks up the category for the start of a linked list, which 484258945Sroberto * it follows all the way to the end to find matching modules. The 485258945Sroberto * test for matching modules is integral, though. 486258945Sroberto * 487258945Sroberto *\li If category is NULL, then the channel is associated with the indicated 488258945Sroberto * module for all known categories (including the "default" category). 489258945Sroberto * 490258945Sroberto *\li If module is NULL, then the channel is associated with every module 491258945Sroberto * that uses that category. 492258945Sroberto * 493258945Sroberto *\li Passing both category and module as NULL would make every log message 494258945Sroberto * use the indicated channel. 495258945Sroberto * 496258945Sroberto * \li Specifying a channel that is #ISC_LOG_TONULL for a category/module pair 497258945Sroberto * has no effect on any other channels associated with that pair, 498258945Sroberto * regardless of ordering. Thus you cannot use it to "mask out" one 499258945Sroberto * category/module pair when you have specified some other channel that 500258945Sroberto * is also used by that category/module pair. 501258945Sroberto * 502258945Sroberto * Requires: 503258945Sroberto *\li lcfg is a valid logging configuration. 504258945Sroberto * 505258945Sroberto *\li category is NULL or has an id that is in the range of known ids. 506258945Sroberto * 507258945Sroberto * module is NULL or has an id that is in the range of known ids. 508258945Sroberto * 509258945Sroberto * Ensures: 510258945Sroberto *\li #ISC_R_SUCCESS 511258945Sroberto * The channel will be used by the indicated category/module 512258945Sroberto * arguments. 513258945Sroberto * 514258945Sroberto *\li #ISC_R_NOMEMORY 515258945Sroberto * If assignment for a specific category has been requested, 516258945Sroberto * the channel has not been associated with the indicated 517258945Sroberto * category/module arguments and no additional memory is 518258945Sroberto * used by the logging context. 519258945Sroberto * If assignment for all categories has been requested 520258945Sroberto * then _some_ may have succeeded (starting with category 521258945Sroberto * "default" and progressing through the order of categories 522258945Sroberto * passed to isc_log_registercategories()) and additional memory 523258945Sroberto * is being used by whatever assignments succeeded. 524258945Sroberto * 525258945Sroberto * Returns: 526258945Sroberto *\li #ISC_R_SUCCESS Success 527258945Sroberto *\li #ISC_R_NOMEMORY Resource limit: Out of memory 528258945Sroberto */ 529258945Sroberto 530258945Sroberto/* Attention: next four comments PRECEED code */ 531258945Sroberto/*! 532258945Sroberto * \brief 533258945Sroberto * Write a message to the log channels. 534258945Sroberto * 535258945Sroberto * Notes: 536258945Sroberto *\li Log messages containing natural language text should be logged with 537258945Sroberto * isc_log_iwrite() to allow for localization. 538258945Sroberto * 539258945Sroberto *\li lctx can be NULL; this is allowed so that programs which use 540258945Sroberto * libraries that use the ISC logging system are not required to 541258945Sroberto * also use it. 542258945Sroberto * 543258945Sroberto *\li The format argument is a printf(3) string, with additional arguments 544258945Sroberto * as necessary. 545258945Sroberto * 546258945Sroberto * Requires: 547258945Sroberto *\li lctx is a valid logging context. 548258945Sroberto * 549258945Sroberto *\li The category and module arguments must have ids that are in the 550258945Sroberto * range of known ids, as established by isc_log_registercategories() 551258945Sroberto * and isc_log_registermodules(). 552258945Sroberto * 553258945Sroberto *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define 554258945Sroberto * channels, and explicit debugging level must be identified for 555258945Sroberto * isc_log_write() via ISC_LOG_DEBUG(level). 556258945Sroberto * 557258945Sroberto *\li format != NULL. 558258945Sroberto * 559258945Sroberto * Ensures: 560258945Sroberto *\li The log message is written to every channel associated with the 561258945Sroberto * indicated category/module pair. 562258945Sroberto * 563258945Sroberto * Returns: 564258945Sroberto *\li Nothing. Failure to log a message is not construed as a 565258945Sroberto * meaningful error. 566258945Sroberto */ 567258945Srobertovoid 568258945Srobertoisc_log_write(isc_log_t *lctx, isc_logcategory_t *category, 569258945Sroberto isc_logmodule_t *module, int level, 570258945Sroberto const char *format, ...) 571258945Sroberto 572258945SrobertoISC_FORMAT_PRINTF(5, 6); 573258945Sroberto 574258945Sroberto/*% 575258945Sroberto * Write a message to the log channels. 576258945Sroberto * 577258945Sroberto * Notes: 578258945Sroberto *\li lctx can be NULL; this is allowed so that programs which use 579258945Sroberto * libraries that use the ISC logging system are not required to 580258945Sroberto * also use it. 581258945Sroberto * 582258945Sroberto *\li The format argument is a printf(3) string, with additional arguments 583258945Sroberto * as necessary. 584258945Sroberto * 585258945Sroberto * Requires: 586258945Sroberto *\li lctx is a valid logging context. 587258945Sroberto * 588258945Sroberto *\li The category and module arguments must have ids that are in the 589258945Sroberto * range of known ids, as established by isc_log_registercategories() 590258945Sroberto * and isc_log_registermodules(). 591258945Sroberto * 592258945Sroberto *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define 593258945Sroberto * channels, and explicit debugging level must be identified for 594258945Sroberto * isc_log_write() via ISC_LOG_DEBUG(level). 595258945Sroberto * 596258945Sroberto *\li format != NULL. 597258945Sroberto * 598258945Sroberto * Ensures: 599258945Sroberto *\li The log message is written to every channel associated with the 600258945Sroberto * indicated category/module pair. 601258945Sroberto * 602258945Sroberto * Returns: 603258945Sroberto *\li Nothing. Failure to log a message is not construed as a 604258945Sroberto * meaningful error. 605258945Sroberto */ 606258945Srobertovoid 607258945Srobertoisc_log_vwrite(isc_log_t *lctx, isc_logcategory_t *category, 608258945Sroberto isc_logmodule_t *module, int level, 609258945Sroberto const char *format, va_list args) 610258945Sroberto 611258945SrobertoISC_FORMAT_PRINTF(5, 0); 612258945Sroberto 613258945Sroberto/*% 614258945Sroberto * Write a message to the log channels, pruning duplicates that occur within 615258945Sroberto * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval). 616258945Sroberto * This function is otherwise identical to isc_log_write(). 617258945Sroberto */ 618258945Srobertovoid 619258945Srobertoisc_log_write1(isc_log_t *lctx, isc_logcategory_t *category, 620258945Sroberto isc_logmodule_t *module, int level, const char *format, ...) 621258945Sroberto 622258945SrobertoISC_FORMAT_PRINTF(5, 6); 623258945Sroberto 624258945Sroberto/*% 625258945Sroberto * Write a message to the log channels, pruning duplicates that occur within 626258945Sroberto * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval). 627258945Sroberto * This function is otherwise identical to isc_log_vwrite(). 628258945Sroberto */ 629258945Srobertovoid 630258945Srobertoisc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category, 631258945Sroberto isc_logmodule_t *module, int level, const char *format, 632258945Sroberto va_list args) 633258945Sroberto 634258945SrobertoISC_FORMAT_PRINTF(5, 0); 635258945Sroberto 636258945Sroberto/*% 637258945Sroberto * These are four internationalized versions of the isc_log_[v]write[1] 638258945Sroberto * functions. 639258945Sroberto * 640258945Sroberto * The only difference is that they take arguments for a message 641258945Sroberto * catalog, message set, and message number, all immediately preceding the 642258945Sroberto * format argument. The format argument becomes the default text, a la 643258945Sroberto * isc_msgcat_get. If the message catalog is NULL, no lookup is attempted 644258945Sroberto * for a message -- which makes the message set and message number irrelevant, 645258945Sroberto * and the non-internationalized call should have probably been used instead. 646258945Sroberto * 647258945Sroberto * Yes, that means there are now *eight* interfaces to logging a message. 648258945Sroberto * Sheesh. Make the madness stop! 649258945Sroberto */ 650258945Sroberto/*@{*/ 651258945Srobertovoid 652258945Srobertoisc_log_iwrite(isc_log_t *lctx, isc_logcategory_t *category, 653258945Sroberto isc_logmodule_t *module, int level, 654258945Sroberto isc_msgcat_t *msgcat, int msgset, int message, 655258945Sroberto const char *format, ...) 656258945SrobertoISC_FORMAT_PRINTF(8, 9); 657258945Sroberto 658258945Srobertovoid 659258945Srobertoisc_log_ivwrite(isc_log_t *lctx, isc_logcategory_t *category, 660258945Sroberto isc_logmodule_t *module, int level, 661258945Sroberto isc_msgcat_t *msgcat, int msgset, int message, 662258945Sroberto const char *format, va_list args) 663258945SrobertoISC_FORMAT_PRINTF(8, 0); 664258945Sroberto 665258945Srobertovoid 666258945Srobertoisc_log_iwrite1(isc_log_t *lctx, isc_logcategory_t *category, 667258945Sroberto isc_logmodule_t *module, int level, 668258945Sroberto isc_msgcat_t *msgcat, int msgset, int message, 669258945Sroberto const char *format, ...) 670258945SrobertoISC_FORMAT_PRINTF(8, 9); 671258945Sroberto 672258945Srobertovoid 673258945Srobertoisc_log_ivwrite1(isc_log_t *lctx, isc_logcategory_t *category, 674258945Sroberto isc_logmodule_t *module, int level, 675258945Sroberto isc_msgcat_t *msgcat, int msgset, int message, 676258945Sroberto const char *format, va_list args) 677258945SrobertoISC_FORMAT_PRINTF(8, 0); 678258945Sroberto/*@}*/ 679258945Sroberto 680258945Srobertovoid 681258945Srobertoisc_log_setdebuglevel(isc_log_t *lctx, unsigned int level); 682258945Sroberto/*%< 683258945Sroberto * Set the debugging level used for logging. 684258945Sroberto * 685258945Sroberto * Notes: 686258945Sroberto *\li Setting the debugging level to 0 disables debugging log messages. 687258945Sroberto * 688258945Sroberto * Requires: 689258945Sroberto *\li lctx is a valid logging context. 690258945Sroberto * 691258945Sroberto * Ensures: 692258945Sroberto *\li The debugging level is set to the requested value. 693258945Sroberto */ 694258945Sroberto 695258945Srobertounsigned int 696258945Srobertoisc_log_getdebuglevel(isc_log_t *lctx); 697258945Sroberto/*%< 698258945Sroberto * Get the current debugging level. 699258945Sroberto * 700258945Sroberto * Notes: 701258945Sroberto *\li This is provided so that a program can have a notion of 702258945Sroberto * "increment debugging level" or "decrement debugging level" 703258945Sroberto * without needing to keep track of what the current level is. 704258945Sroberto * 705258945Sroberto *\li A return value of 0 indicates that debugging messages are disabled. 706258945Sroberto * 707258945Sroberto * Requires: 708258945Sroberto *\li lctx is a valid logging context. 709258945Sroberto * 710258945Sroberto * Ensures: 711258945Sroberto *\li The current logging debugging level is returned. 712258945Sroberto */ 713258945Sroberto 714258945Srobertoisc_boolean_t 715258945Srobertoisc_log_wouldlog(isc_log_t *lctx, int level); 716258945Sroberto/*%< 717258945Sroberto * Determine whether logging something to 'lctx' at 'level' would 718258945Sroberto * actually cause something to be logged somewhere. 719258945Sroberto * 720258945Sroberto * If #ISC_FALSE is returned, it is guaranteed that nothing would 721258945Sroberto * be logged, allowing the caller to omit unnecessary 722258945Sroberto * isc_log_write() calls and possible message preformatting. 723258945Sroberto */ 724258945Sroberto 725258945Srobertovoid 726258945Srobertoisc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval); 727258945Sroberto/*%< 728258945Sroberto * Set the interval over which duplicate log messages will be ignored 729258945Sroberto * by isc_log_[v]write1(), in seconds. 730258945Sroberto * 731258945Sroberto * Notes: 732258945Sroberto *\li Increasing the duplicate interval from X to Y will not necessarily 733258945Sroberto * filter out duplicates of messages logged in Y - X seconds since the 734258945Sroberto * increase. (Example: Message1 is logged at midnight. Message2 735258945Sroberto * is logged at 00:01:00, when the interval is only 30 seconds, causing 736258945Sroberto * Message1 to be expired from the log message history. Then the interval 737258945Sroberto * is increased to 3000 (five minutes) and at 00:04:00 Message1 is logged 738258945Sroberto * again. It will appear the second time even though less than five 739258945Sroberto * passed since the first occurrence. 740258945Sroberto * 741258945Sroberto * Requires: 742258945Sroberto *\li lctx is a valid logging context. 743258945Sroberto */ 744258945Sroberto 745258945Srobertounsigned int 746258945Srobertoisc_log_getduplicateinterval(isc_logconfig_t *lcfg); 747258945Sroberto/*%< 748258945Sroberto * Get the current duplicate filtering interval. 749258945Sroberto * 750258945Sroberto * Requires: 751258945Sroberto *\li lctx is a valid logging context. 752258945Sroberto * 753258945Sroberto * Returns: 754258945Sroberto *\li The current duplicate filtering interval. 755258945Sroberto */ 756258945Sroberto 757258945Srobertoisc_result_t 758258945Srobertoisc_log_settag(isc_logconfig_t *lcfg, const char *tag); 759258945Sroberto/*%< 760258945Sroberto * Set the program name or other identifier for #ISC_LOG_PRINTTAG. 761258945Sroberto * 762258945Sroberto * Requires: 763258945Sroberto *\li lcfg is a valid logging configuration. 764258945Sroberto * 765258945Sroberto * Notes: 766258945Sroberto *\li If this function has not set the tag to a non-NULL, non-empty value, 767258945Sroberto * then the #ISC_LOG_PRINTTAG channel flag will not print anything. 768258945Sroberto * Unlike some implementations of syslog on Unix systems, you *must* set 769258945Sroberto * the tag in order to get it logged. It is not implicitly derived from 770258945Sroberto * the program name (which is pretty impossible to infer portably). 771258945Sroberto * 772258945Sroberto *\li Setting the tag to NULL or the empty string will also cause the 773258945Sroberto * #ISC_LOG_PRINTTAG channel flag to not print anything. If tag equals the 774258945Sroberto * empty string, calls to isc_log_gettag will return NULL. 775258945Sroberto * 776258945Sroberto * Returns: 777258945Sroberto *\li #ISC_R_SUCCESS Success 778258945Sroberto *\li #ISC_R_NOMEMORY Resource Limit: Out of memory 779258945Sroberto * 780258945Sroberto * XXXDCL when creating a new isc_logconfig_t, it might be nice if the tag 781258945Sroberto * of the currently active isc_logconfig_t was inherited. this does not 782258945Sroberto * currently happen. 783258945Sroberto */ 784258945Sroberto 785258945Srobertochar * 786258945Srobertoisc_log_gettag(isc_logconfig_t *lcfg); 787258945Sroberto/*%< 788258945Sroberto * Get the current identifier printed with #ISC_LOG_PRINTTAG. 789258945Sroberto * 790258945Sroberto * Requires: 791258945Sroberto *\li lcfg is a valid logging configuration. 792258945Sroberto * 793258945Sroberto * Notes: 794258945Sroberto *\li Since isc_log_settag() will not associate a zero-length string 795258945Sroberto * with the logging configuration, attempts to do so will cause 796258945Sroberto * this function to return NULL. However, a determined programmer 797258945Sroberto * will observe that (currently) a tag of length greater than zero 798258945Sroberto * could be set, and then modified to be zero length. 799258945Sroberto * 800258945Sroberto * Returns: 801258945Sroberto *\li A pointer to the current identifier, or NULL if none has been set. 802258945Sroberto */ 803258945Sroberto 804258945Srobertovoid 805258945Srobertoisc_log_opensyslog(const char *tag, int options, int facility); 806258945Sroberto/*%< 807258945Sroberto * Initialize syslog logging. 808258945Sroberto * 809258945Sroberto * Notes: 810258945Sroberto *\li XXXDCL NT 811258945Sroberto * This is currently equivalent to openlog(), but is not going to remain 812258945Sroberto * that way. In the meantime, the arguments are all identical to 813258945Sroberto * those used by openlog(3), as follows: 814258945Sroberto * 815258945Sroberto * \code 816258945Sroberto * tag: The string to use in the position of the program 817258945Sroberto * name in syslog messages. Most (all?) syslogs 818258945Sroberto * will use basename(argv[0]) if tag is NULL. 819258945Sroberto * 820258945Sroberto * options: LOG_CONS, LOG_PID, LOG_NDELAY ... whatever your 821258945Sroberto * syslog supports. 822258945Sroberto * 823258945Sroberto * facility: The default syslog facility. This is irrelevant 824258945Sroberto * since isc_log_write will ALWAYS use the channel's 825258945Sroberto * declared facility. 826258945Sroberto * \endcode 827258945Sroberto * 828258945Sroberto *\li Zero effort has been made (yet) to accommodate systems with openlog() 829258945Sroberto * that only takes two arguments, or to identify valid syslog 830258945Sroberto * facilities or options for any given architecture. 831258945Sroberto * 832258945Sroberto *\li It is necessary to call isc_log_opensyslog() to initialize 833258945Sroberto * syslogging on machines which do not support network connections to 834258945Sroberto * syslogd because they require a Unix domain socket to be used. Since 835258945Sroberto * this is a chore to determine at run-time, it is suggested that it 836258945Sroberto * always be called by programs using the ISC logging system. 837258945Sroberto * 838258945Sroberto * Requires: 839258945Sroberto *\li Nothing. 840258945Sroberto * 841258945Sroberto * Ensures: 842258945Sroberto *\li openlog() is called to initialize the syslog system. 843258945Sroberto */ 844258945Sroberto 845258945Srobertovoid 846258945Srobertoisc_log_closefilelogs(isc_log_t *lctx); 847258945Sroberto/*%< 848258945Sroberto * Close all open files used by #ISC_LOG_TOFILE channels. 849258945Sroberto * 850258945Sroberto * Notes: 851258945Sroberto *\li This function is provided for programs that want to use their own 852258945Sroberto * log rolling mechanism rather than the one provided internally. 853258945Sroberto * For example, a program that wanted to keep daily logs would define 854258945Sroberto * a channel which used #ISC_LOG_ROLLNEVER, then once a day would 855258945Sroberto * rename the log file and call isc_log_closefilelogs(). 856258945Sroberto * 857258945Sroberto *\li #ISC_LOG_TOFILEDESC channels are unaffected. 858258945Sroberto * 859258945Sroberto * Requires: 860258945Sroberto *\li lctx is a valid context. 861258945Sroberto * 862258945Sroberto * Ensures: 863258945Sroberto *\li The open files are closed and will be reopened when they are 864258945Sroberto * next needed. 865258945Sroberto */ 866258945Sroberto 867258945Srobertoisc_logcategory_t * 868258945Srobertoisc_log_categorybyname(isc_log_t *lctx, const char *name); 869258945Sroberto/*%< 870258945Sroberto * Find a category by its name. 871258945Sroberto * 872258945Sroberto * Notes: 873258945Sroberto *\li The string name of a category is not required to be unique. 874258945Sroberto * 875258945Sroberto * Requires: 876258945Sroberto *\li lctx is a valid context. 877258945Sroberto *\li name is not NULL. 878258945Sroberto * 879258945Sroberto * Returns: 880258945Sroberto *\li A pointer to the _first_ isc_logcategory_t structure used by "name". 881258945Sroberto * 882258945Sroberto *\li NULL if no category exists by that name. 883258945Sroberto */ 884258945Sroberto 885258945Srobertoisc_logmodule_t * 886258945Srobertoisc_log_modulebyname(isc_log_t *lctx, const char *name); 887258945Sroberto/*%< 888258945Sroberto * Find a module by its name. 889258945Sroberto * 890258945Sroberto * Notes: 891258945Sroberto *\li The string name of a module is not required to be unique. 892258945Sroberto * 893258945Sroberto * Requires: 894258945Sroberto *\li lctx is a valid context. 895258945Sroberto *\li name is not NULL. 896258945Sroberto * 897258945Sroberto * Returns: 898258945Sroberto *\li A pointer to the _first_ isc_logmodule_t structure used by "name". 899258945Sroberto * 900258945Sroberto *\li NULL if no module exists by that name. 901258945Sroberto */ 902258945Sroberto 903258945Srobertovoid 904258945Srobertoisc_log_setcontext(isc_log_t *lctx); 905258945Sroberto/*%< 906258945Sroberto * Sets the context used by the libisc for logging. 907258945Sroberto * 908258945Sroberto * Requires: 909258945Sroberto *\li lctx be a valid context. 910258945Sroberto */ 911258945Sroberto 912258945SrobertoISC_LANG_ENDDECLS 913258945Sroberto 914258945Sroberto#endif /* ISC_LOG_H */ 915