BIND 10 trac622, updated. b23ef1cf58b0754e23e550362e7a979d5f8624ef [trac622] Additional changes to documentation
BIND 10 source code commits
bind10-changes at lists.isc.org
Mon Mar 7 18:09:52 UTC 2011
The branch, trac622 has been updated
via b23ef1cf58b0754e23e550362e7a979d5f8624ef (commit)
from 5ff855e14dca375c24404eebc4573b77dba915d3 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit b23ef1cf58b0754e23e550362e7a979d5f8624ef
Author: Stephen Morris <stephen at isc.org>
Date: Mon Mar 7 18:09:31 2011 +0000
[trac622] Additional changes to documentation
-----------------------------------------------------------------------
Summary of changes:
src/lib/log/README | 65 +++++++++++++++++++++------------------------------
1 files changed, 27 insertions(+), 38 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/log/README b/src/lib/log/README
index a6f5a99..2fc6aec 100644
--- a/src/lib/log/README
+++ b/src/lib/log/README
@@ -59,7 +59,7 @@ The steps in using the system are:
2. Run it through the message compiler to produce the .h and .cc files. It
is intended that this step be included in the build process. However,
- for not run the compiler (found in the "compiler" subdirectory) manually.
+ for now run the compiler (found in the "compiler" subdirectory) manually.
The only argument is the name of the message file: it will produce as
output two files, having the same name as the input file but with file
types of ".h" and ".cc".
@@ -74,7 +74,7 @@ The steps in using the system are:
4. Declare loggers in your code and use them to log messages. This is
described in more detail below.
-5. To set the debug level and run-time message file, call runTimeInit (declared
+5. To set the debug level and run-time message file, call initLogger (declared
in logger_support.h) in the main program unit. This is a temporary solution
for Year 2, and will be replaced at a later date, the information coming
from the configuration database.
@@ -106,7 +106,7 @@ UNKNOWN unknown message
Points to note:
* Leading and trailing space are trimmed from the line. Although the above
- exampl,e has every line starting at column 1, the lines could be indented
+ example has every line starting at column 1, the lines could be indented
if desired.
* Blank lines are ignored.
@@ -120,10 +120,8 @@ Points to note:
* $PREFIX, which has one argument: the string used to prefix symbols. If
absent, there is no prefix to the symbols. (Prefixes are explained below.)
* $NAMESPACE, which has one argument: the namespace in which the symbols are
- created. (Specifying the argument as a double colon - i.e. "$NAMESPACE
- ::" puts the symbol definitions in the unnamed namespace. And not
- including a $NAMESPACE directive will result in the symbols note being
- put in any namespace.
+ created. In the absence of a $NAMESPACE directive, symbols will be put
+ in the global namespace.
* Lines starting + indicate an explanation for the preceding message. These
are intended to be processed by a separate program and used to generate
@@ -151,13 +149,11 @@ The message compiler processes the message file to produce two files:
the form:
namespace <namespace> {
- isc::log::MessageID PREFIX_IDENTIFIER = "IDENTIFIER";
+ extern const isc::log::MessageID PREFIX_IDENTIFIER;
:
}
-The symbols define the keys in the global message dictionary. At present
-they are defined as std::strings, but a future implementation could redefine
-them as numeric values.
+The symbols define the keys in the global message dictionary.
The namespace enclosing the symbols is set by the $NAMESPACE directive.
@@ -167,14 +163,18 @@ ABC with "MSG_" to give the symbol MSG_ABC. Similarly "$PREFIX E" would
prefix it with "E" to give the symbol EABC. If no $PREFIX is given, no
prefix appears (so the symbol in this example would be ABC).
-The header file also includes a couple of lines to ensure that the message
-text is included in the final program image.
+2) A C++ source file (called <message-file-name>.cc) that holds the definitions
+of the global symbols and code to insert the symbols and messages into the map.
+Symbols are defined to be equal to strings holding the identifier, e.g.
-2) A C++ source file (called <message-file-name>.cc) that holds the code to
-insert the symbols and messages into the map.
+ extern const isc::log::MessageID MSG_DUPLNS = "DUPLNS";
-This file declares an array of identifiers/messages in the form:
+(The implementation allows symbols to be compared. However, use of strings
+should not be assumed - a future implementation may change this.)
+
+iIn addition, the file declares an array of identifiers/messages and an object
+to add them to the global dictionary:
namespace {
const char* values[] = {
@@ -183,20 +183,9 @@ This file declares an array of identifiers/messages in the form:
:
NULL
};
- }
-
-(A more complex structure to group identifiers and their messages could be
-imposed, but as the array is generated by code and will be read by code,
-it is not needed.)
-It then declares an object that will add information to the global dictionary:
-
- MessageInitializer <message-file-name>_<time>(values);
-
-(Declaring the object as "static" or in the anonymous namespace runs the risk
-of it being optimised away when the module is compiled with optimisation.
-But giving it a standard name would cause a clash when multiple files are
-used, hence an attempt at disambiguation.)
+ const isc::log::MessageInitializer initializer(values);
+ }
The constructor of the MessageInitializer object retrieves the singleton
global Dictionary object (created using standard methods to avoid the
@@ -236,7 +225,7 @@ To use the current version of the logging:
(The argument is required to support a possible future implementation of
logging. Currently it has no effect.)
-3. The main program unit should include a call to isc::log::runTimeInit()
+3. The main program unit should include a call to isc::log::initLogger()
(defined in logger_support.h) to set the logging severity, debug log level,
and external message file.
@@ -250,13 +239,13 @@ To use the current version of the logging:
isc::log::NONE
b) The debug log level is only interpreted when the severity is DEBUG and
- is an integer raning from 0 to 99. 0 should be used for the highest-level
- debug messages and 99 for the lowest-level (and typically more verbose)
- messages.
+ is an integer ranging from 0 to 99. 0 should be used for the
+ highest-level debug messages and 99 for the lowest-level (and typically
+ more verbose) messages.
c) Name of an external message file. This is the same as a standard message
- file, although it should not include the $PREFIX directive. (A single
- $PREFIX directive will be ignored; multiple directives will cause the
+ file, although it should not include any directives. (A single directive
+ of a particular type will be ignored; multiple directives will cause the
read of the file to fail with an error.) If a message is replaced, the
message should include the same printf-format directives in the same order
as the original message.
@@ -340,7 +329,7 @@ Logging Sources v Logging Severities
When logging events, make a distinction between events related to the server
and events related to DNS messages received. Caution needs to be exercised
with the latter as, if the logging is enabled in the normal course of events,
-such logging could be a denoial of service vector. For example, suppose that
+such logging could be a denial of service vector. For example, suppose that
the main authoritiative service logger were to log both zone loading and
unloading as INFO and a warning message if it received an invalid packet. An
attacker could make the INFO messages unusable by flooding the server with
@@ -353,7 +342,7 @@ DEBUG is not enabled by default, so these events will not be recorded unless
DEBUG is specifically chosen.
b) Record system-related and packet-related messages via different loggers
-(e.g. in the example given, sever events could be logged using the logger
+(e.g. in the example given, server events could be logged using the logger
"auth" and packet-related events at that level logged using the logger
"pkt-auth".) As the loggers are independent and the severity levels
independent, fine-tuning of what and what is not recorded can be achieved.
@@ -380,7 +369,7 @@ Outstanding Issues
log4cxx Issues
==============
Some experimental code to utilise log4cxx as an underlying implementation
-is present in the source code directory, although it is not currently used.
+is present in the source code directory although it is not currently used.
The files are:
logger_impl_log4cxx.{cc,h}
More information about the bind10-changes
mailing list