* Copyright (C) Internet Systems Consortium, Inc. ("ISC")
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, you can obtain one at https://mozilla.org/MPL/2.0/.
* See the COPYRIGHT file distributed with this work for additional
* information regarding copyright ownership.
#include <syslog.h> /* XXXDCL NT */
#include <isc/formatcheck.h>
#include <isc/platform.h>
* \brief Severity levels, patterned after Unix's syslog levels.
#define ISC_LOG_DEBUG(level) (level)
* #ISC_LOG_DYNAMIC can only be used for defining channels with
* isc_log_createchannel(), not to specify a level in isc_log_write().
#define ISC_LOG_DYNAMIC 0
#define ISC_LOG_INFO (-1)
#define ISC_LOG_NOTICE (-2)
#define ISC_LOG_WARNING (-3)
#define ISC_LOG_ERROR (-4)
#define ISC_LOG_CRITICAL (-5)
#define ISC_LOG_TOSYSLOG 2
#define ISC_LOG_TOFILEDESC 4
#define ISC_LOG_PRINTTIME 0x0001
#define ISC_LOG_PRINTLEVEL 0x0002
#define ISC_LOG_PRINTCATEGORY 0x0004
#define ISC_LOG_PRINTMODULE 0x0008
#define ISC_LOG_PRINTTAG 0x0010 /* tag and ":" */
#define ISC_LOG_PRINTPREFIX 0x0020 /* tag only, no colon */
#define ISC_LOG_PRINTALL 0x003F
#define ISC_LOG_BUFFERED 0x0040
#define ISC_LOG_DEBUGONLY 0x1000
#define ISC_LOG_OPENERR 0x8000 /* internal */
* XXXDCL INFINITE doesn't yet work. Arguably it isn't needed, but
* since I am intend to make large number of versions work efficiently,
* INFINITE is going to be trivial to add to that.
#define ISC_LOG_ROLLINFINITE (-1)
#define ISC_LOG_ROLLNEVER (-2)
* \brief Used to name the categories used by a library.
* An array of isc_logcategory
* structures names each category, and the id value is initialized by calling
* isc_log_registercategories.
* Similar to isc_logcategory, but for all the modules a library defines.
* The isc_logfile structure is initialized as part of an isc_logdestination
* before calling isc_log_createchannel().
* When defining an #ISC_LOG_TOFILE
* channel the name, versions and maximum_size should be set before calling
* isc_log_createchannel(). To define an #ISC_LOG_TOFILEDESC channel set only
* the stream before the call.
* Setting maximum_size to zero implies no maximum.
typedef struct isc_logfile {
FILE *stream; /*%< Initialized to NULL for #ISC_LOG_TOFILE. */
const char *name; /*%< NULL for #ISC_LOG_TOFILEDESC. */
int versions; /* >= 0, #ISC_LOG_ROLLNEVER, #ISC_LOG_ROLLINFINITE. */
* stdio's ftell is standardized to return a long, which may well not
* be big enough for the largest file supportable by the operating
* system (though it is _probably_ big enough for the largest log
* anyone would want). st_size returned by fstat should be typedef'd
* to a size large enough for the largest possible file on a system.
isc_offset_t maximum_size;
bool maximum_reached; /*%< Private. */
* Passed to isc_log_createchannel to define the attributes of either
* a stdio or a syslog log.
typedef union isc_logdestination {
int facility; /* XXXDCL NT */
* The built-in categories of libisc.
* Each library registering categories should provide library_LOGCATEGORY_name
* definitions with indexes into its isc_logcategory structure corresponding to
* the order of the names.
LIBISC_EXTERNAL_DATA extern isc_logcategory_t isc_categories[];
LIBISC_EXTERNAL_DATA extern isc_log_t *isc_lctx;
LIBISC_EXTERNAL_DATA extern isc_logmodule_t isc_modules[];
* Do not log directly to DEFAULT. Use another category. When in doubt,
#define ISC_LOGCATEGORY_DEFAULT (&isc_categories[0])
#define ISC_LOGCATEGORY_GENERAL (&isc_categories[1])
#define ISC_LOGMODULE_SOCKET (&isc_modules[0])
#define ISC_LOGMODULE_TIME (&isc_modules[1])
#define ISC_LOGMODULE_INTERFACE (&isc_modules[2])
#define ISC_LOGMODULE_TIMER (&isc_modules[3])
#define ISC_LOGMODULE_FILE (&isc_modules[4])
#define ISC_LOGMODULE_OTHER (&isc_modules[5])
isc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp);
* Establish a new logging context, with default channels.
*\li isc_log_create() calls isc_logconfig_create(), so see its comment
* below for more information.
*\li mctx is a valid memory context.
*\li lctxp is not null and *lctxp is null.
*\li lcfgp is null or lcfgp is not null and *lcfgp is null.
*\li *lctxp will point to a valid logging context if all of the necessary
* memory was allocated, or NULL otherwise.
*\li *lcfgp will point to a valid logging configuration if all of the
* necessary memory was allocated, or NULL otherwise.
*\li On failure, no additional memory is allocated.
*\li #ISC_R_SUCCESS Success
*\li #ISC_R_NOMEMORY Resource limit: Out of memory
isc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp);
* Create the data structure that holds all of the configurable information
* about where messages are actually supposed to be sent -- the information
* that could changed based on some configuration file, as opposed to the
* the category/module specification of isc_log_[v]write[1] that is compiled
* into a program, or the debug_level which is dynamic state information.
*\li It is necessary to specify the logging context the configuration
* will be used with because the number of categories and modules
* needs to be known in order to set the configuration. However,
* the configuration is not used by the logging context until the
* isc_logconfig_use function is called.
*\li The memory context used for operations that allocate memory for
* the configuration is that of the logging context, as specified
* in the isc_log_create call.
*\li Four default channels are established:
* - log to syslog's daemon facility #ISC_LOG_INFO or higher
* - log to stderr #ISC_LOG_INFO or higher
* - log to stderr #ISC_LOG_DEBUG dynamically
*\li lctx is a valid logging context.
*\li lcftp is not null and *lcfgp is null.
*\li *lcfgp will point to a valid logging context if all of the necessary
* memory was allocated, or NULL otherwise.
*\li On failure, no additional memory is allocated.
*\li #ISC_R_SUCCESS Success
*\li #ISC_R_NOMEMORY Resource limit: Out of memory
isc_logconfig_get(isc_log_t *lctx);
* Returns a pointer to the configuration currently in use by the log context.
*\li lctx is a valid context.
*\li The configuration pointer is non-null.
*\li The configuration pointer.
isc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg);
* Associate a new configuration with a logging context.
*\li This is thread safe. The logging context will lock a mutex
* before attempting to swap in the new configuration, and isc_log_doit
* (the internal function used by all of isc_log_[v]write[1]) locks
* the same lock for the duration of its use of the configuration.
*\li lctx is a valid logging context.
*\li lcfg is a valid logging configuration.
*\li lctx is the same configuration given to isc_logconfig_create
* when the configuration was created.
*\li Future calls to isc_log_write will use the new configuration.
*\li #ISC_R_SUCCESS Success
*\li #ISC_R_NOMEMORY Resource limit: Out of memory
isc_log_destroy(isc_log_t **lctxp);
* 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.
isc_logconfig_destroy(isc_logconfig_t **lcfgp);
* 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.
isc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]);
* 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().
isc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]);
* 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().
isc_log_createchannel(isc_logconfig_t *lcfg, const char *name,
unsigned int type, int level,
const isc_logdestination_t *destination,
* 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,
* #ISC_LOG_DEBUGONLY or #ISC_LOG_BUFFERED.
* 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()
isc_log_usechannel(isc_logconfig_t *lcfg, const char *name,
const isc_logcategory_t *category,
const isc_logmodule_t *module);
* 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
* is also used by that category/module pair.
*\li lcfg is a valid logging configuration.
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
