fc80027fb54b501cdd88461bf879d078259e0226David Lawrence/*
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews * Copyright (C) 1999-2002, 2004-2007, 2009, 2014, 2016 Internet Systems Consortium, Inc. ("ISC")
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence *
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews * This Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews * License, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews * file, You can obtain one at http://mozilla.org/MPL/2.0/.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
e502b133d630bda0ee64c1e2ce6729d96750d8abMark Andrews/* $Id: log.h,v 1.59 2009/02/16 02:01:16 marka Exp $ */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#ifndef ISC_LOG_H
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_H 1
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
29747dfe5e073a299b3681e01f5c55540f8bfed7Mark Andrews/*! \file isc/log.h */
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#include <stdio.h>
899f7f9af527d3dfe8345dcc8210d7c23fc950afDavid Lawrence#include <stdarg.h>
c4717613e45323ed23dc6e9162cba89f1f83830cDavid Lawrence#include <syslog.h> /* XXXDCL NT */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
9550eb2dab1d03e03e6c060f92e655d47ac1fc1bMichael Graff#include <isc/formatcheck.h>
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#include <isc/lang.h>
c4958494a98a59ce25e9fecad76a9ab0e36cc59fDanny Mayer#include <isc/platform.h>
8f804834e2b537da5c8bc81f986143a46147b490Andreas Gustafsson#include <isc/types.h>
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@{*/
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*!
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * \brief Severity levels, patterned after Unix's syslog levels.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_DEBUG(level) (level)
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*!
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * #ISC_LOG_DYNAMIC can only be used for defining channels with
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * isc_log_createchannel(), not to specify a level in isc_log_write().
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_DYNAMIC 0
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_INFO (-1)
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_NOTICE (-2)
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_WARNING (-3)
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_ERROR (-4)
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_CRITICAL (-5)
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@}*/
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@{*/
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*!
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * \brief Destinations.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_TONULL 1
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_TOSYSLOG 2
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_TOFILE 3
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_TOFILEDESC 4
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@}*/
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@{*/
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Channel flags.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_PRINTTIME 0x0001
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_PRINTLEVEL 0x0002
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_PRINTCATEGORY 0x0004
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_PRINTMODULE 0x0008
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt#define ISC_LOG_PRINTTAG 0x0010 /* tag and ":" */
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt#define ISC_LOG_PRINTPREFIX 0x0020 /* tag only, no colon */
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt#define ISC_LOG_PRINTALL 0x003F
00fb0253c9df8a4686115745ae91d501f62c7451Mark Andrews#define ISC_LOG_BUFFERED 0x0040
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence#define ISC_LOG_DEBUGONLY 0x1000
959cf5e112c41ba8da2a202f51bc0c7a3cf47f68Tatuya JINMEI 神明達哉#define ISC_LOG_OPENERR 0x8000 /* internal */
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@}*/
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@{*/
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*!
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * \brief Other options.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * XXXDCL INFINITE doesn't yet work. Arguably it isn't needed, but
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * since I am intend to make large number of versions work efficiently,
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * INFINITE is going to be trivial to add to that.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_ROLLINFINITE (-1)
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOG_ROLLNEVER (-2)
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@}*/
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*!
0cfbb9285a96f1355e5a3bd458624eaed2f16846Automatic Updater * \brief Used to name the categories used by a library.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * An array of isc_logcategory
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * structures names each category, and the id value is initialized by calling
d409ceeda41a256e8114423674d844d5f5035ee8Bob Halley * isc_log_registercategories.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
8f804834e2b537da5c8bc81f986143a46147b490Andreas Gustafssonstruct isc_logcategory {
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence const char *name;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence unsigned int id;
8f804834e2b537da5c8bc81f986143a46147b490Andreas Gustafsson};
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * Similar to isc_logcategory, but for all the modules a library defines.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
8f804834e2b537da5c8bc81f986143a46147b490Andreas Gustafssonstruct isc_logmodule {
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence const char *name;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence unsigned int id;
8f804834e2b537da5c8bc81f986143a46147b490Andreas Gustafsson};
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * The isc_logfile structure is initialized as part of an isc_logdestination
0cfbb9285a96f1355e5a3bd458624eaed2f16846Automatic Updater * before calling isc_log_createchannel().
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * When defining an #ISC_LOG_TOFILE
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * channel the name, versions and maximum_size should be set before calling
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * isc_log_createchannel(). To define an #ISC_LOG_TOFILEDESC channel set only
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * the stream before the call.
0cfbb9285a96f1355e5a3bd458624eaed2f16846Automatic Updater *
8862388bcb44f634cbfc3e69f11ff4cb76590a4bMark Andrews * Setting maximum_size to zero implies no maximum.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrencetypedef struct isc_logfile {
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein FILE *stream; /*%< Initialized to NULL for #ISC_LOG_TOFILE. */
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein const char *name; /*%< NULL for #ISC_LOG_TOFILEDESC. */
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein int versions; /* >= 0, #ISC_LOG_ROLLNEVER, #ISC_LOG_ROLLINFINITE. */
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein /*%
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * stdio's ftell is standardized to return a long, which may well not
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * be big enough for the largest file supportable by the operating
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * system (though it is _probably_ big enough for the largest log
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * anyone would want). st_size returned by fstat should be typedef'd
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * to a size large enough for the largest possible file on a system.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
61e9c1cdbe29683bb2db388e4fc6a6fd59315cefDavid Lawrence isc_offset_t maximum_size;
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein isc_boolean_t maximum_reached; /*%< Private. */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence} isc_logfile_t;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Passed to isc_log_createchannel to define the attributes of either
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * a stdio or a syslog log.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrencetypedef union isc_logdestination {
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence isc_logfile_t file;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence int facility; /* XXXDCL NT */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence} isc_logdestination_t;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@{*/
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff * The built-in categories of libisc.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Each library registering categories should provide library_LOGCATEGORY_name
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * definitions with indexes into its isc_logcategory structure corresponding to
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff * the order of the names.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
c4958494a98a59ce25e9fecad76a9ab0e36cc59fDanny MayerLIBISC_EXTERNAL_DATA extern isc_logcategory_t isc_categories[];
c4958494a98a59ce25e9fecad76a9ab0e36cc59fDanny MayerLIBISC_EXTERNAL_DATA extern isc_log_t *isc_lctx;
c4958494a98a59ce25e9fecad76a9ab0e36cc59fDanny MayerLIBISC_EXTERNAL_DATA extern isc_logmodule_t isc_modules[];
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@}*/
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@{*/
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff * Do not log directly to DEFAULT. Use another category. When in doubt,
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff * use GENERAL.
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#define ISC_LOGCATEGORY_DEFAULT (&isc_categories[0])
5fe5a0c02634eaadfcbc3528bf2c184557110a3bAndreas Gustafsson#define ISC_LOGCATEGORY_GENERAL (&isc_categories[1])
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@}*/
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff#define ISC_LOGMODULE_SOCKET (&isc_modules[0])
df0f58959ed82a2a43ca8d816ce9592541df9f2fMark Andrews#define ISC_LOGMODULE_TIME (&isc_modules[1])
ecf7a1812527d5557564b71363dabec491980246Mark Andrews#define ISC_LOGMODULE_INTERFACE (&isc_modules[2])
88f7da46901f5d1218e354768674e72e9190d05aMichael Graff#define ISC_LOGMODULE_TIMER (&isc_modules[3])
e502b133d630bda0ee64c1e2ce6729d96750d8abMark Andrews#define ISC_LOGMODULE_FILE (&isc_modules[4])
1d761cb453c76353deb8423c78e98d00c5f86ffaEvan Hunt#define ISC_LOGMODULE_OTHER (&isc_modules[5])
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff
b161f87be81548d1b6d0210a7e138a08fbb2d3e5David LawrenceISC_LANG_BEGINDECLS
b161f87be81548d1b6d0210a7e138a08fbb2d3e5David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_result_t
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Establish a new logging context, with default channels.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li isc_log_create() calls isc_logconfig_create(), so see its comment
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * below for more information.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li mctx is a valid memory context.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctxp is not null and *lctxp is null.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lcfgp is null or lcfgp is not null and *lcfgp is null.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li *lctxp will point to a valid logging context if all of the necessary
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * memory was allocated, or NULL otherwise.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li *lcfgp will point to a valid logging configuration if all of the
1b106e224d3931e85d68c091fe1ec7758d9f07cbAndreas Gustafsson * necessary memory was allocated, or NULL otherwise.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li On failure, no additional memory is allocated.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_SUCCESS Success
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_NOMEMORY Resource limit: Out of memory
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence */
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrenceisc_result_t
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrenceisc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Create the data structure that holds all of the configurable information
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * about where messages are actually supposed to be sent -- the information
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * that could changed based on some configuration file, as opposed to the
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * the category/module specification of isc_log_[v]write[1] that is compiled
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * into a program, or the debug_level which is dynamic state information.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li It is necessary to specify the logging context the configuration
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * will be used with because the number of categories and modules
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * needs to be known in order to set the configuration. However,
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * the configuration is not used by the logging context until the
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * isc_logconfig_use function is called.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The memory context used for operations that allocate memory for
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * the configuration is that of the logging context, as specified
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * in the isc_log_create call.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Four default channels are established:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\verbatim
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * default_syslog
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * - log to syslog's daemon facility #ISC_LOG_INFO or higher
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * default_stderr
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * - log to stderr #ISC_LOG_INFO or higher
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * default_debug
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * - log to stderr #ISC_LOG_DEBUG dynamically
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * null
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * - log nothing
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\endverbatim
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lcftp is not null and *lcfgp is null.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li *lcfgp will point to a valid logging context if all of the necessary
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * memory was allocated, or NULL otherwise.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li On failure, no additional memory is allocated.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_SUCCESS Success
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_NOMEMORY Resource limit: Out of memory
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_logconfig_t *
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_logconfig_get(isc_log_t *lctx);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Returns a pointer to the configuration currently in use by the log context.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid context.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The configuration pointer is non-null.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The configuration pointer.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence */
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrence
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_result_t
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Associate a new configuration with a logging context.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li This is thread safe. The logging context will lock a mutex
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * before attempting to swap in the new configuration, and isc_log_doit
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * (the internal function used by all of isc_log_[v]write[1]) locks
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * the same lock for the duration of its use of the configuration.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lcfg is a valid logging configuration.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is the same configuration given to isc_logconfig_create
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * when the configuration was created.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Future calls to isc_log_write will use the new configuration.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_SUCCESS Success
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_NOMEMORY Resource limit: Out of memory
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence */
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrencevoid
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_log_destroy(isc_log_t **lctxp);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Deallocate the memory associated with a logging context.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li *lctx is a valid logging context.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li All of the memory associated with the logging context is returned
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * to the free memory pool.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Any open files are closed.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The logging context is marked as invalid.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrencevoid
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_logconfig_destroy(isc_logconfig_t **lcfgp);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Destroy a logging configuration.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li This function cannot be used directly with the return value of
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * isc_logconfig_get, because a logging context must always have
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * a valid configuration associated with it.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lcfgp is not null and *lcfgp is a valid logging configuration.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The logging configuration is not in use by an existing logging context.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li All memory allocated for the configuration is freed.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The configuration is marked as invalid.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence */
0bd4e3591ac1a729c7ec8f811844119473350975David Lawrence
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrencevoid
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Identify logging categories a library will use.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li A category should only be registered once, but no mechanism enforces
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * this rule.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The end of the categories array is identified by a NULL name.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * be altered or destroyed after isc_log_registercategories().
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Because each element of the categories array is used by
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * isc_log_categorybyname, it should not be altered or destroyed
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * after registration.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The value of the id integer in each structure is overwritten
6a8832f784bd53aa6afbda22f6187cea6490e1e1Andreas Gustafsson * by this function, and so id need not be initialized to any particular
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * value prior to the function call.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li A subsequent call to isc_log_registercategories with the same
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * logging context (but new categories) will cause the last
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * element of the categories array from the prior call to have
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * its "name" member changed from NULL to point to the new
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * categories array, and its "id" member set to UINT_MAX.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li categories != NULL.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li categories[0].name != NULL.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * \li There are references to each category in the logging context,
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * so they can be used with isc_log_usechannel() and isc_log_write().
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrencevoid
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Identify logging categories a library will use.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li A module should only be registered once, but no mechanism enforces
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * this rule.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The end of the modules array is identified by a NULL name.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Because the name is used by #ISC_LOG_PRINTMODULE, it should not
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * be altered or destroyed after isc_log_registermodules().
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Because each element of the modules array is used by
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * isc_log_modulebyname, it should not be altered or destroyed
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * after registration.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The value of the id integer in each structure is overwritten
6a8832f784bd53aa6afbda22f6187cea6490e1e1Andreas Gustafsson * by this function, and so id need not be initialized to any particular
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * value prior to the function call.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li A subsequent call to isc_log_registermodules with the same
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * logging context (but new modules) will cause the last
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * element of the modules array from the prior call to have
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * its "name" member changed from NULL to point to the new
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * modules array, and its "id" member set to UINT_MAX.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li modules != NULL.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li modules[0].name != NULL;
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Each module has a reference in the logging context, so they can be
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * used with isc_log_usechannel() and isc_log_write().
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_result_t
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_log_createchannel(isc_logconfig_t *lcfg, const char *name,
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrence unsigned int type, int level,
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrence const isc_logdestination_t *destination,
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrence unsigned int flags);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Specify the parameters of a logging channel.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The name argument is copied to memory in the logging context, so
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * it can be altered or destroyed after isc_log_createchannel().
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Defining a very large number of channels will have a performance
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * impact on isc_log_usechannel(), since the names are searched
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * linearly until a match is made. This same issue does not affect
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * isc_log_write, however.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Channel names can be redefined; this is primarily useful for programs
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * that want their own definition of default_syslog, default_debug
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * and default_stderr.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Any channel that is redefined will not affect logging that was
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * already directed to its original definition, _except_ for the
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * default_stderr channel. This case is handled specially so that
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * the default logging category can be changed by redefining
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * default_stderr. (XXXDCL Though now that I think of it, the default
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * logging category can be changed with only one additional function
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * call by defining a new channel and then calling isc_log_usechannel()
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * for #ISC_LOGCATEGORY_DEFAULT.)
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
00fb0253c9df8a4686115745ae91d501f62c7451Mark Andrews *\li Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is
00fb0253c9df8a4686115745ae91d501f62c7451Mark Andrews * allowed, but probably not what you wanted to do.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * #ISC_LOG_DEBUGONLY will mark the channel as usable only when the
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * debug level of the logging context (see isc_log_setdebuglevel)
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence * is non-zero.
863ac191b448a13ae1a3a8ee3458344e11602737David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lcfg is a valid logging configuration.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li name is not NULL.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * #ISC_LOG_TONULL.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li destination is not NULL unless type is #ISC_LOG_TONULL.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li level is >= #ISC_LOG_CRITICAL (the most negative logging level).
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
00fb0253c9df8a4686115745ae91d501f62c7451Mark Andrews *\li flags does not include any bits aside from the ISC_LOG_PRINT* bits,
00fb0253c9df8a4686115745ae91d501f62c7451Mark Andrews * #ISC_LOG_DEBUGONLY or #ISC_LOG_BUFFERED.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_SUCCESS
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * A channel with the given name is usable with
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * isc_log_usechannel().
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_NOMEMORY or #ISC_R_UNEXPECTED
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * No additional memory is being used by the logging context.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Any channel that previously existed with the given name
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * is not redefined.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_SUCCESS Success
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_NOMEMORY Resource limit: Out of memory
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_UNEXPECTED type was out of range and REQUIRE()
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * was disabled.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_result_t
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_log_usechannel(isc_logconfig_t *lcfg, const char *name,
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrence const isc_logcategory_t *category,
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrence const isc_logmodule_t *module);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Associate a named logging channel with a category and module that
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * will use it.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The name is searched for linearly in the set of known channel names
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * until a match is found. (Note the performance impact of a very large
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * number of named channels.) When multiple channels of the same
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * name are defined, the most recent definition is found.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
0ef59d22882fc5d28f4683fdbe88aefd8eaad6f3Francis Dupont *\li Specifying a very large number of channels for a category will have
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * a moderate impact on performance in isc_log_write(), as each
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * call looks up the category for the start of a linked list, which
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * it follows all the way to the end to find matching modules. The
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * test for matching modules is integral, though.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li If category is NULL, then the channel is associated with the indicated
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * module for all known categories (including the "default" category).
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li If module is NULL, then the channel is associated with every module
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * that uses that category.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Passing both category and module as NULL would make every log message
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * use the indicated channel.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * \li Specifying a channel that is #ISC_LOG_TONULL for a category/module pair
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * has no effect on any other channels associated with that pair,
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * regardless of ordering. Thus you cannot use it to "mask out" one
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * category/module pair when you have specified some other channel that
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * is also used by that category/module pair.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lcfg is a valid logging configuration.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li category is NULL or has an id that is in the range of known ids.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * module is NULL or has an id that is in the range of known ids.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_SUCCESS
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * The channel will be used by the indicated category/module
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * arguments.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_NOMEMORY
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * If assignment for a specific category has been requested,
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * the channel has not been associated with the indicated
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * category/module arguments and no additional memory is
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * used by the logging context.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * If assignment for all categories has been requested
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * then _some_ may have succeeded (starting with category
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * "default" and progressing through the order of categories
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * passed to isc_log_registercategories()) and additional memory
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * is being used by whatever assignments succeeded.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_SUCCESS Success
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_NOMEMORY Resource limit: Out of memory
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/* Attention: next four comments PRECEED code */
0cfbb9285a96f1355e5a3bd458624eaed2f16846Automatic Updater/*!
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * \brief
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Write a message to the log channels.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Log messages containing natural language text should be logged with
fc6f5743aa860861fe39ca2680d9aa08e39d3039Andreas Gustafsson * isc_log_iwrite() to allow for localization.
fc6f5743aa860861fe39ca2680d9aa08e39d3039Andreas Gustafsson *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx can be NULL; this is allowed so that programs which use
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * libraries that use the ISC logging system are not required to
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * also use it.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The format argument is a printf(3) string, with additional arguments
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * as necessary.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The category and module arguments must have ids that are in the
0ef59d22882fc5d28f4683fdbe88aefd8eaad6f3Francis Dupont * range of known ids, as established by isc_log_registercategories()
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * and isc_log_registermodules().
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * channels, and explicit debugging level must be identified for
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * isc_log_write() via ISC_LOG_DEBUG(level).
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li format != NULL.
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence *
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The log message is written to every channel associated with the
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * indicated category/module pair.
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence *
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Nothing. Failure to log a message is not construed as a
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * meaningful error.
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence */
b161f87be81548d1b6d0210a7e138a08fbb2d3e5David Lawrencevoid
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austeinisc_log_write(isc_log_t *lctx, isc_logcategory_t *category,
b161f87be81548d1b6d0210a7e138a08fbb2d3e5David Lawrence isc_logmodule_t *module, int level,
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein const char *format, ...)
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein
ab023a65562e62b85a824509d829b6fad87e00b1Rob AusteinISC_FORMAT_PRINTF(5, 6);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * Write a message to the log channels.
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence *
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx can be NULL; this is allowed so that programs which use
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * libraries that use the ISC logging system are not required to
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * also use it.
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The format argument is a printf(3) string, with additional arguments
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * as necessary.
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence *
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The category and module arguments must have ids that are in the
0ef59d22882fc5d28f4683fdbe88aefd8eaad6f3Francis Dupont * range of known ids, as established by isc_log_registercategories()
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * and isc_log_registermodules().
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * channels, and explicit debugging level must be identified for
00a1623a59b1540c28781e8ccd8341c8114dbc75David Lawrence * isc_log_write() via ISC_LOG_DEBUG(level).
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li format != NULL.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The log message is written to every channel associated with the
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * indicated category/module pair.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Nothing. Failure to log a message is not construed as a
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * meaningful error.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austeinvoid
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austeinisc_log_vwrite(isc_log_t *lctx, isc_logcategory_t *category,
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein isc_logmodule_t *module, int level,
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein const char *format, va_list args)
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein
ab023a65562e62b85a824509d829b6fad87e00b1Rob AusteinISC_FORMAT_PRINTF(5, 0);
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * Write a message to the log channels, pruning duplicates that occur within
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval).
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * This function is otherwise identical to isc_log_write().
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein */
b161f87be81548d1b6d0210a7e138a08fbb2d3e5David Lawrencevoid
fc6f5743aa860861fe39ca2680d9aa08e39d3039Andreas Gustafssonisc_log_write1(isc_log_t *lctx, isc_logcategory_t *category,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_logmodule_t *module, int level, const char *format, ...)
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein
0c7b7a19e5a3c23fbb789238dcc4d43cd55387a0Brian WellingtonISC_FORMAT_PRINTF(5, 6);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * Write a message to the log channels, pruning duplicates that occur within
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval).
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * This function is otherwise identical to isc_log_vwrite().
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence */
b161f87be81548d1b6d0210a7e138a08fbb2d3e5David Lawrencevoid
fc6f5743aa860861fe39ca2680d9aa08e39d3039Andreas Gustafssonisc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category,
b161f87be81548d1b6d0210a7e138a08fbb2d3e5David Lawrence isc_logmodule_t *module, int level, const char *format,
b161f87be81548d1b6d0210a7e138a08fbb2d3e5David Lawrence va_list args)
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein
0c7b7a19e5a3c23fbb789238dcc4d43cd55387a0Brian WellingtonISC_FORMAT_PRINTF(5, 0);
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%
3fb1637c9265cc593973326ae193783413f68699Tatuya JINMEI 神明達哉 * These are four internationalized versions of the isc_log_[v]write[1]
0cfbb9285a96f1355e5a3bd458624eaed2f16846Automatic Updater * functions.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * The only difference is that they take arguments for a message
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * catalog, message set, and message number, all immediately preceding the
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * format argument. The format argument becomes the default text, a la
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * isc_msgcat_get. If the message catalog is NULL, no lookup is attempted
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * for a message -- which makes the message set and message number irrelevant,
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * and the non-internationalized call should have probably been used instead.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * Yes, that means there are now *eight* interfaces to logging a message.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * Sheesh. Make the madness stop!
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein */
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@{*/
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrencevoid
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrenceisc_log_iwrite(isc_log_t *lctx, isc_logcategory_t *category,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_logmodule_t *module, int level,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_msgcat_t *msgcat, int msgset, int message,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence const char *format, ...)
b74896ead5671943135727b50d86d1040d7ffbf3David LawrenceISC_FORMAT_PRINTF(8, 9);
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrencevoid
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrenceisc_log_ivwrite(isc_log_t *lctx, isc_logcategory_t *category,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_logmodule_t *module, int level,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_msgcat_t *msgcat, int msgset, int message,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence const char *format, va_list args)
b74896ead5671943135727b50d86d1040d7ffbf3David LawrenceISC_FORMAT_PRINTF(8, 0);
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrencevoid
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrenceisc_log_iwrite1(isc_log_t *lctx, isc_logcategory_t *category,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_logmodule_t *module, int level,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_msgcat_t *msgcat, int msgset, int message,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence const char *format, ...)
b74896ead5671943135727b50d86d1040d7ffbf3David LawrenceISC_FORMAT_PRINTF(8, 9);
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrencevoid
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrenceisc_log_ivwrite1(isc_log_t *lctx, isc_logcategory_t *category,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_logmodule_t *module, int level,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence isc_msgcat_t *msgcat, int msgset, int message,
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence const char *format, va_list args)
b74896ead5671943135727b50d86d1040d7ffbf3David LawrenceISC_FORMAT_PRINTF(8, 0);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*@}*/
b74896ead5671943135727b50d86d1040d7ffbf3David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrencevoid
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_log_setdebuglevel(isc_log_t *lctx, unsigned int level);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Set the debugging level used for logging.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Setting the debugging level to 0 disables debugging log messages.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The debugging level is set to the requested value.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceunsigned int
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_log_getdebuglevel(isc_log_t *lctx);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Get the current debugging level.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li This is provided so that a program can have a notion of
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * "increment debugging level" or "decrement debugging level"
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * without needing to keep track of what the current level is.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li A return value of 0 indicates that debugging messages are disabled.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The current logging debugging level is returned.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafssonisc_boolean_t
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafssonisc_log_wouldlog(isc_log_t *lctx, int level);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafsson * Determine whether logging something to 'lctx' at 'level' would
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafsson * actually cause something to be logged somewhere.
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafsson *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * If #ISC_FALSE is returned, it is guaranteed that nothing would
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafsson * be logged, allowing the caller to omit unnecessary
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafsson * isc_log_write() calls and possible message preformatting.
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafsson */
30576c592b538cab293cf6e1f6265d376cd5a12cAndreas Gustafsson
1b038dbf0659fce246485562601ee851a9841ba1David Lawrencevoid
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * Set the interval over which duplicate log messages will be ignored
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * by isc_log_[v]write1(), in seconds.
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence *
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Increasing the duplicate interval from X to Y will not necessarily
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * filter out duplicates of messages logged in Y - X seconds since the
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * increase. (Example: Message1 is logged at midnight. Message2
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * is logged at 00:01:00, when the interval is only 30 seconds, causing
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * Message1 to be expired from the log message history. Then the interval
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * is increased to 3000 (five minutes) and at 00:04:00 Message1 is logged
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * again. It will appear the second time even though less than five
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * passed since the first occurrence.
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence *
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence */
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence
1b038dbf0659fce246485562601ee851a9841ba1David Lawrenceunsigned int
edcd1247ad7e81bb8b430e610d9718f64c70f05dDavid Lawrenceisc_log_getduplicateinterval(isc_logconfig_t *lcfg);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * Get the current duplicate filtering interval.
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence *
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid logging context.
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence *
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The current duplicate filtering interval.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence */
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrenceisc_result_t
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrenceisc_log_settag(isc_logconfig_t *lcfg, const char *tag);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * Set the program name or other identifier for #ISC_LOG_PRINTTAG.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence *
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lcfg is a valid logging configuration.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence *
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li If this function has not set the tag to a non-NULL, non-empty value,
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * then the #ISC_LOG_PRINTTAG channel flag will not print anything.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * Unlike some implementations of syslog on Unix systems, you *must* set
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * the tag in order to get it logged. It is not implicitly derived from
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * the program name (which is pretty impossible to infer portably).
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Setting the tag to NULL or the empty string will also cause the
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * #ISC_LOG_PRINTTAG channel flag to not print anything. If tag equals the
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * empty string, calls to isc_log_gettag will return NULL.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence *
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_SUCCESS Success
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_R_NOMEMORY Resource Limit: Out of memory
87cafc5e70f79f2586d067fbdd64f61bbab069d2David Lawrence *
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * XXXDCL when creating a new isc_logconfig_t, it might be nice if the tag
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * of the currently active isc_logconfig_t was inherited. this does not
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * currently happen.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence */
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrencechar *
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrenceisc_log_gettag(isc_logconfig_t *lcfg);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * Get the current identifier printed with #ISC_LOG_PRINTTAG.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence *
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lcfg is a valid logging configuration.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence *
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Since isc_log_settag() will not associate a zero-length string
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * with the logging configuration, attempts to do so will cause
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * this function to return NULL. However, a determined programmer
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * will observe that (currently) a tag of length greater than zero
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * could be set, and then modified to be zero length.
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence *
2918b5bda6a55c301eb87992b5f2acd7176d0737David Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li A pointer to the current identifier, or NULL if none has been set.
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence */
1b038dbf0659fce246485562601ee851a9841ba1David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrencevoid
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_log_opensyslog(const char *tag, int options, int facility);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Initialize syslog logging.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li XXXDCL NT
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * This is currently equivalent to openlog(), but is not going to remain
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * that way. In the meantime, the arguments are all identical to
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * those used by openlog(3), as follows:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * \code
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * tag: The string to use in the position of the program
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * name in syslog messages. Most (all?) syslogs
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * will use basename(argv[0]) if tag is NULL.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * options: LOG_CONS, LOG_PID, LOG_NDELAY ... whatever your
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * syslog supports.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * facility: The default syslog facility. This is irrelevant
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * since isc_log_write will ALWAYS use the channel's
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * declared facility.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * \endcode
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
0ef59d22882fc5d28f4683fdbe88aefd8eaad6f3Francis Dupont *\li Zero effort has been made (yet) to accommodate systems with openlog()
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * that only takes two arguments, or to identify valid syslog
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * facilities or options for any given architecture.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li It is necessary to call isc_log_opensyslog() to initialize
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * syslogging on machines which do not support network connections to
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * syslogd because they require a Unix domain socket to be used. Since
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * this is a chore to determine at run-time, it is suggested that it
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * always be called by programs using the ISC logging system.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li Nothing.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li openlog() is called to initialize the syslog system.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrencevoid
fc80027fb54b501cdd88461bf879d078259e0226David Lawrenceisc_log_closefilelogs(isc_log_t *lctx);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * Close all open files used by #ISC_LOG_TOFILE channels.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li This function is provided for programs that want to use their own
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * log rolling mechanism rather than the one provided internally.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * For example, a program that wanted to keep daily logs would define
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein * a channel which used #ISC_LOG_ROLLNEVER, then once a day would
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * rename the log file and call isc_log_closefilelogs().
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li #ISC_LOG_TOFILEDESC channels are unaffected.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid context.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence *
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * Ensures:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The open files are closed and will be reopened when they are
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence * next needed.
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence */
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrenceisc_logcategory_t *
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrenceisc_log_categorybyname(isc_log_t *lctx, const char *name);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * Find a category by its name.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence *
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The string name of a category is not required to be unique.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
1be10d46cbdf77d1a59a2e7512b72daceea47058David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid context.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li name is not NULL.
1be10d46cbdf77d1a59a2e7512b72daceea47058David Lawrence *
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li A pointer to the _first_ isc_logcategory_t structure used by "name".
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li NULL if no category exists by that name.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence */
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrenceisc_logmodule_t *
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrenceisc_log_modulebyname(isc_log_t *lctx, const char *name);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * Find a module by its name.
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence *
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * Notes:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li The string name of a module is not required to be unique.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
1be10d46cbdf77d1a59a2e7512b72daceea47058David Lawrence * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx is a valid context.
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li name is not NULL.
1be10d46cbdf77d1a59a2e7512b72daceea47058David Lawrence *
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence * Returns:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li A pointer to the _first_ isc_logmodule_t structure used by "name".
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence *
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li NULL if no module exists by that name.
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence */
ff30a206ecc63b6681716322ed7f017e3f51ea7fDavid Lawrence
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graffvoid
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graffisc_log_setcontext(isc_log_t *lctx);
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein/*%<
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff * Sets the context used by the libisc for logging.
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff *
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff * Requires:
ab023a65562e62b85a824509d829b6fad87e00b1Rob Austein *\li lctx be a valid context.
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff */
1a487fb7d230403bf1b5d6628542134f52c80653Michael Graff
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Huntisc_result_t
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Huntisc_logfile_roll(isc_logfile_t *file);
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Hunt/*%<
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Hunt * Roll a logfile.
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Hunt *
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Hunt * Requires:
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Hunt *\li file is not NULL.
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Hunt */
3525200d9fb0e70aec4f6a3c7e0ed5a7dd8398afEvan Hunt
fc80027fb54b501cdd88461bf879d078259e0226David LawrenceISC_LANG_ENDDECLS
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence
fc80027fb54b501cdd88461bf879d078259e0226David Lawrence#endif /* ISC_LOG_H */