log.h revision 1d761cb453c76353deb8423c78e98d00c5f86ffa
2N/A * Copyright (C) 2004-2007, 2009 Internet Systems Consortium, Inc. ("ISC") 2N/A * Copyright (C) 1999-2002 Internet Software Consortium. 2N/A * Permission to use, copy, modify, and/or distribute this software for any 2N/A * purpose with or without fee is hereby granted, provided that the above 2N/A * copyright notice and this permission notice appear in all copies. 2N/A * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 2N/A * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 2N/A * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 2N/A * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 2N/A * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 2N/A * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 2N/A * PERFORMANCE OF THIS SOFTWARE. 2N/A/* $Id: log.h,v 1.59 2009/02/16 02:01:16 marka Exp $ */ 2N/A * \brief Severity levels, patterned after Unix's syslog levels. 2N/A * #ISC_LOG_DYNAMIC can only be used for defining channels with 2N/A * isc_log_createchannel(), not to specify a level in isc_log_write(). 2N/A * \brief Destinations. 2N/A * \brief Other options. 2N/A * XXXDCL INFINITE doesn't yet work. Arguably it isn't needed, but 2N/A * since I am intend to make large number of versions work efficiently, 2N/A * INFINITE is going to be trivial to add to that. 2N/A * \brief Used to name the categories used by a library. 2N/A * An array of isc_logcategory 2N/A * structures names each category, and the id value is initialized by calling 2N/A * isc_log_registercategories. 2N/A * Similar to isc_logcategory, but for all the modules a library defines. 2N/A * The isc_logfile structure is initialized as part of an isc_logdestination 2N/A * before calling isc_log_createchannel(). 2N/A * When defining an #ISC_LOG_TOFILE 2N/A * channel the name, versions and maximum_size should be set before calling 2N/A * isc_log_createchannel(). To define an #ISC_LOG_TOFILEDESC channel set only 2N/A * the stream before the call. 2N/A * Setting maximum_size to zero implies no maximum. 2N/A const char *
name;
/*%< NULL for #ISC_LOG_TOFILEDESC. */ 2N/A int versions;
/* >= 0, #ISC_LOG_ROLLNEVER, #ISC_LOG_ROLLINFINITE. */ 2N/A * stdio's ftell is standardized to return a long, which may well not 2N/A * be big enough for the largest file supportable by the operating 2N/A * system (though it is _probably_ big enough for the largest log 2N/A * anyone would want). st_size returned by fstat should be typedef'd 2N/A * to a size large enough for the largest possible file on a system. 2N/A * Passed to isc_log_createchannel to define the attributes of either 2N/A * a stdio or a syslog log. 2N/A * The built-in categories of libisc. 2N/A * Each library registering categories should provide library_LOGCATEGORY_name 2N/A * definitions with indexes into its isc_logcategory structure corresponding to 2N/A * the order of the names. 2N/A * Do not log directly to DEFAULT. Use another category. When in doubt, 2N/A * Establish a new logging context, with default channels. 2N/A *\li isc_log_create() calls isc_logconfig_create(), so see its comment 2N/A * below for more information. 2N/A *\li mctx is a valid memory context. 2N/A *\li lctxp is not null and *lctxp is null. 2N/A *\li lcfgp is null or lcfgp is not null and *lcfgp is null. 2N/A *\li *lctxp will point to a valid logging context if all of the necessary 2N/A * memory was allocated, or NULL otherwise. 2N/A *\li *lcfgp will point to a valid logging configuration if all of the 2N/A * necessary memory was allocated, or NULL otherwise. 2N/A *\li On failure, no additional memory is allocated. 2N/A *\li #ISC_R_SUCCESS Success 2N/A *\li #ISC_R_NOMEMORY Resource limit: Out of memory 2N/A * Create the data structure that holds all of the configurable information 2N/A * about where messages are actually supposed to be sent -- the information 2N/A * that could changed based on some configuration file, as opposed to the 2N/A * into a program, or the debug_level which is dynamic state information. 2N/A *\li It is necessary to specify the logging context the configuration 2N/A * will be used with because the number of categories and modules 2N/A * needs to be known in order to set the configuration. However, 2N/A * the configuration is not used by the logging context until the 2N/A * isc_logconfig_use function is called. 2N/A *\li The memory context used for operations that allocate memory for 2N/A * the configuration is that of the logging context, as specified 2N/A * in the isc_log_create call. 2N/A *\li Four default channels are established: 2N/A * - log to syslog's daemon facility #ISC_LOG_INFO or higher 2N/A * - log to stderr #ISC_LOG_INFO or higher 2N/A * - log to stderr #ISC_LOG_DEBUG dynamically 2N/A *\li lctx is a valid logging context. 2N/A *\li lcftp is not null and *lcfgp is null. 2N/A *\li *lcfgp will point to a valid logging context if all of the necessary 2N/A * memory was allocated, or NULL otherwise. 2N/A *\li On failure, no additional memory is allocated. 2N/A *\li #ISC_R_SUCCESS Success 2N/A *\li #ISC_R_NOMEMORY Resource limit: Out of memory 2N/A * Returns a pointer to the configuration currently in use by the log context. 2N/A *\li lctx is a valid context. 2N/A *\li The configuration pointer is non-null. 2N/A *\li The configuration pointer. 2N/A * Associate a new configuration with a logging context. 2N/A *\li This is thread safe. The logging context will lock a mutex 2N/A * before attempting to swap in the new configuration, and isc_log_doit 2N/A * (the internal function used by all of isc_log_[v]write[1]) locks 2N/A * the same lock for the duration of its use of the configuration. 2N/A *\li lctx is a valid logging context. 2N/A *\li lcfg is a valid logging configuration. 2N/A *\li lctx is the same configuration given to isc_logconfig_create 2N/A * when the configuration was created. 2N/A *\li Future calls to isc_log_write will use the new configuration. 2N/A *\li #ISC_R_SUCCESS Success 2N/A *\li #ISC_R_NOMEMORY Resource limit: Out of memory * Deallocate the memory associated with a logging context. *\li *lctx is a valid logging context. *\li All of the memory associated with the logging context is returned * to the free memory pool. *\li Any open files are closed. *\li The logging context is marked as invalid. * Destroy a logging configuration. *\li This function cannot be used directly with the return value of * isc_logconfig_get, because a logging context must always have * a valid configuration associated with it. *\li lcfgp is not null and *lcfgp is a valid logging configuration. *\li The logging configuration is not in use by an existing logging context. *\li All memory allocated for the configuration is freed. *\li The configuration is marked as invalid. * Identify logging categories a library will use. *\li A category should only be registered once, but no mechanism enforces *\li The end of the categories array is identified by a NULL name. *\li Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not * be altered or destroyed after isc_log_registercategories(). *\li Because each element of the categories array is used by * isc_log_categorybyname, it should not be altered or destroyed *\li The value of the id integer in each structure is overwritten * by this function, and so id need not be initialized to any particular * value prior to the function call. *\li A subsequent call to isc_log_registercategories with the same * logging context (but new categories) will cause the last * element of the categories array from the prior call to have * its "name" member changed from NULL to point to the new * categories array, and its "id" member set to UINT_MAX. *\li lctx is a valid logging context. *\li categories[0].name != NULL. * \li There are references to each category in the logging context, * so they can be used with isc_log_usechannel() and isc_log_write(). * Identify logging categories a library will use. *\li A module should only be registered once, but no mechanism enforces *\li The end of the modules array is identified by a NULL name. *\li Because the name is used by #ISC_LOG_PRINTMODULE, it should not * be altered or destroyed after isc_log_registermodules(). *\li Because each element of the modules array is used by * isc_log_modulebyname, it should not be altered or destroyed *\li The value of the id integer in each structure is overwritten * by this function, and so id need not be initialized to any particular * value prior to the function call. *\li A subsequent call to isc_log_registermodules with the same * logging context (but new modules) will cause the last * element of the modules array from the prior call to have * its "name" member changed from NULL to point to the new * modules array, and its "id" member set to UINT_MAX. *\li lctx is a valid logging context. *\li modules[0].name != NULL; *\li Each module has a reference in the logging context, so they can be * used with isc_log_usechannel() and isc_log_write(). * Specify the parameters of a logging channel. *\li The name argument is copied to memory in the logging context, so * it can be altered or destroyed after isc_log_createchannel(). *\li Defining a very large number of channels will have a performance * impact on isc_log_usechannel(), since the names are searched * linearly until a match is made. This same issue does not affect * isc_log_write, however. *\li Channel names can be redefined; this is primarily useful for programs * that want their own definition of default_syslog, default_debug *\li Any channel that is redefined will not affect logging that was * already directed to its original definition, _except_ for the * default_stderr channel. This case is handled specially so that * the default logging category can be changed by redefining * default_stderr. (XXXDCL Though now that I think of it, the default * logging category can be changed with only one additional function * call by defining a new channel and then calling isc_log_usechannel() * for #ISC_LOGCATEGORY_DEFAULT.) *\li Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is allowed, * but probably not what you wanted to do. * #ISC_LOG_DEBUGONLY will mark the channel as usable only when the * debug level of the logging context (see isc_log_setdebuglevel) *\li lcfg is a valid logging configuration. *\li type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or *\li destination is not NULL unless type is #ISC_LOG_TONULL. *\li level is >= #ISC_LOG_CRITICAL (the most negative logging level). *\li flags does not include any bits aside from the ISC_LOG_PRINT* bits * A channel with the given name is usable with *\li #ISC_R_NOMEMORY or #ISC_R_UNEXPECTED * No additional memory is being used by the logging context. * Any channel that previously existed with the given name *\li #ISC_R_SUCCESS Success *\li #ISC_R_NOMEMORY Resource limit: Out of memory *\li #ISC_R_UNEXPECTED type was out of range and REQUIRE() * Associate a named logging channel with a category and module that *\li The name is searched for linearly in the set of known channel names * until a match is found. (Note the performance impact of a very large * number of named channels.) When multiple channels of the same * name are defined, the most recent definition is found. *\li Specifying a very large number of channels for a category will have * a moderate impact on performance in isc_log_write(), as each * call looks up the category for the start of a linked list, which * it follows all the way to the end to find matching modules. The * test for matching modules is integral, though. *\li If category is NULL, then the channel is associated with the indicated * module for all known categories (including the "default" category). *\li If module is NULL, then the channel is associated with every module * that uses that category. *\li Passing both category and module as NULL would make every log message * use the indicated channel. * \li Specifying a channel that is #ISC_LOG_TONULL for a category/module pair * has no effect on any other channels associated with that pair, * regardless of ordering. Thus you cannot use it to "mask out" one * category/module pair when you have specified some other channel that *\li lcfg is a valid logging configuration. *\li category is NULL or has an id that is in the range of known ids. * module is NULL or has an id that is in the range of known ids. * If assignment for a specific category has been requested, * the channel has not been associated with the indicated * used by the logging context. * If assignment for all categories has been requested * then _some_ may have succeeded (starting with category * "default" and progressing through the order of categories * passed to isc_log_registercategories()) and additional memory * is being used by whatever assignments succeeded. *\li #ISC_R_SUCCESS Success *\li #ISC_R_NOMEMORY Resource limit: Out of memory /* Attention: next four comments PRECEED code */ * Write a message to the log channels. *\li Log messages containing natural language text should be logged with * isc_log_iwrite() to allow for localization. *\li lctx can be NULL; this is allowed so that programs which use * libraries that use the ISC logging system are not required to *\li The format argument is a printf(3) string, with additional arguments *\li lctx is a valid logging context. *\li The category and module arguments must have ids that are in the * range of known ids, as established by isc_log_registercategories() * and isc_log_registermodules(). *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define * channels, and explicit debugging level must be identified for * isc_log_write() via ISC_LOG_DEBUG(level). *\li The log message is written to every channel associated with the *\li Nothing. Failure to log a message is not construed as a * Write a message to the log channels. *\li lctx can be NULL; this is allowed so that programs which use * libraries that use the ISC logging system are not required to *\li The format argument is a printf(3) string, with additional arguments *\li lctx is a valid logging context. *\li The category and module arguments must have ids that are in the * range of known ids, as established by isc_log_registercategories() * and isc_log_registermodules(). *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define * channels, and explicit debugging level must be identified for * isc_log_write() via ISC_LOG_DEBUG(level). *\li The log message is written to every channel associated with the *\li Nothing. Failure to log a message is not construed as a * Write a message to the log channels, pruning duplicates that occur within * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval). * This function is otherwise identical to isc_log_write(). * Write a message to the log channels, pruning duplicates that occur within * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval). * This function is otherwise identical to isc_log_vwrite(). * These are four internationalized versions of the isc_log_[v]write[1] * The only difference is that they take arguments for a message * catalog, message set, and message number, all immediately preceding the * format argument. The format argument becomes the default text, a la * isc_msgcat_get. If the message catalog is NULL, no lookup is attempted * for a message -- which makes the message set and message number irrelevant, * and the non-internationalized call should have probably been used instead. * Yes, that means there are now *eight* interfaces to logging a message. * Sheesh. Make the madness stop! * Set the debugging level used for logging. *\li Setting the debugging level to 0 disables debugging log messages. *\li lctx is a valid logging context. *\li The debugging level is set to the requested value. * Get the current debugging level. *\li This is provided so that a program can have a notion of * "increment debugging level" or "decrement debugging level" * without needing to keep track of what the current level is. *\li A return value of 0 indicates that debugging messages are disabled. *\li lctx is a valid logging context. *\li The current logging debugging level is returned. * Determine whether logging something to 'lctx' at 'level' would * actually cause something to be logged somewhere. * If #ISC_FALSE is returned, it is guaranteed that nothing would * be logged, allowing the caller to omit unnecessary * isc_log_write() calls and possible message preformatting. * Set the interval over which duplicate log messages will be ignored * by isc_log_[v]write1(), in seconds. *\li Increasing the duplicate interval from X to Y will not necessarily * filter out duplicates of messages logged in Y - X seconds since the * increase. (Example: Message1 is logged at midnight. Message2 * is logged at 00:01:00, when the interval is only 30 seconds, causing * Message1 to be expired from the log message history. Then the interval * is increased to 3000 (five minutes) and at 00:04:00 Message1 is logged * again. It will appear the second time even though less than five * passed since the first occurrence. *\li lctx is a valid logging context. * Get the current duplicate filtering interval. *\li lctx is a valid logging context. *\li The current duplicate filtering interval. * Set the program name or other identifier for #ISC_LOG_PRINTTAG. *\li lcfg is a valid logging configuration. *\li If this function has not set the tag to a non-NULL, non-empty value, * then the #ISC_LOG_PRINTTAG channel flag will not print anything. * Unlike some implementations of syslog on Unix systems, you *must* set * the tag in order to get it logged. It is not implicitly derived from * the program name (which is pretty impossible to infer portably). *\li Setting the tag to NULL or the empty string will also cause the * #ISC_LOG_PRINTTAG channel flag to not print anything. If tag equals the * empty string, calls to isc_log_gettag will return NULL. *\li #ISC_R_SUCCESS Success *\li #ISC_R_NOMEMORY Resource Limit: Out of memory * XXXDCL when creating a new isc_logconfig_t, it might be nice if the tag * of the currently active isc_logconfig_t was inherited. this does not * Get the current identifier printed with #ISC_LOG_PRINTTAG. *\li lcfg is a valid logging configuration. *\li Since isc_log_settag() will not associate a zero-length string * with the logging configuration, attempts to do so will cause * this function to return NULL. However, a determined programmer * will observe that (currently) a tag of length greater than zero * could be set, and then modified to be zero length. *\li A pointer to the current identifier, or NULL if none has been set. * Initialize syslog logging. * This is currently equivalent to openlog(), but is not going to remain * that way. In the meantime, the arguments are all identical to * those used by openlog(3), as follows: * tag: The string to use in the position of the program * name in syslog messages. Most (all?) syslogs * will use basename(argv[0]) if tag is NULL. * options: LOG_CONS, LOG_PID, LOG_NDELAY ... whatever your * facility: The default syslog facility. This is irrelevant * since isc_log_write will ALWAYS use the channel's *\li Zero effort has been made (yet) to accommodate systems with openlog() * that only takes two arguments, or to identify valid syslog * facilities or options for any given architecture. *\li It is necessary to call isc_log_opensyslog() to initialize * syslogging on machines which do not support network connections to * syslogd because they require a Unix domain socket to be used. Since * this is a chore to determine at run-time, it is suggested that it * always be called by programs using the ISC logging system. *\li openlog() is called to initialize the syslog system. * Close all open files used by #ISC_LOG_TOFILE channels. *\li This function is provided for programs that want to use their own * log rolling mechanism rather than the one provided internally. * For example, a program that wanted to keep daily logs would define * a channel which used #ISC_LOG_ROLLNEVER, then once a day would * rename the log file and call isc_log_closefilelogs(). *\li #ISC_LOG_TOFILEDESC channels are unaffected. *\li lctx is a valid context. *\li The open files are closed and will be reopened when they are * Find a category by its name. *\li The string name of a category is not required to be unique. *\li lctx is a valid context. *\li A pointer to the _first_ isc_logcategory_t structure used by "name". *\li NULL if no category exists by that name. * Find a module by its name. *\li The string name of a module is not required to be unique. *\li lctx is a valid context. *\li A pointer to the _first_ isc_logmodule_t structure used by "name". *\li NULL if no module exists by that name. * Sets the context used by the libisc for logging. *\li lctx be a valid context.