-<!-- ##### SECTION Title ##### -->
-Logging facilities
-
-<!-- ##### SECTION Short_Description ##### -->
-An easy-to-use, fast and flexible message logging architecture.
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
- This is an adaptation of the log4c project, which is dead upstream, and which
- I was given the permission to fork under the LGPL licence by the authors. log4c
- itself was loosely based on the Apache project's Log4J, Log4CC,
- etc. project. Because C is not object oriented, a lot had to change.
-</para>
-
-<refsect2>
- <title>Overview</title>
-
- <para>
- There is 3 main concepts: category, priority and appender. These three
- concepts work together to enable developers to log messages according to
- message type and priority, and to control at runtime how these messages are
- formatted and where they are reported.
- </para>
-</refsect2>
-
-<refsect2>
- <title>Category hierarchy</title>
-
- <para>
- The first and foremost advantage of any logging API over plain printf()
- resides in its ability to disable certain log statements while allowing
- others to print unhindered. This capability assumes that the logging space,
- that is, the space of all possible logging statements, is categorized
- according to some developer-chosen criteria.
- </para>
-
- <para>
- This observation led to choosing category as the central concept of the
- system. Every category is declared by providing a name and an optional
- parent. If no parent is explicitly named, the root category, LOG_ROOT_CAT
- is the category's parent.
- </para>
-
- <para>
- A category is created by a macro call at the top level of a file. A
- category can be created with any one of the following macros:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>@GRAS_LOG_NEW_CATEGORY(MyCat);</para>
- <para>create a new root</para>
- </listitem>
-
- <listitem>
- <para>@GRAS_LOG_NEW_SUBCATEGORY(MyCat, ParentCat);</para>
- <para>Create a new category being child of the category ParentCat</para>
- </listitem>
-
- <listitem>
- <para>@GRAS_LOG_NEW_DEFAULT_CATEGORY(MyCat);</para>
- <para>Like GRAS_LOG_NEW_CATEGORY, but the new category is the default one
- in this file</para>
- </listitem>
-
- <listitem>
- <para>@GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, ParentCat);</para>
- <para>Like GRAS_LOG_NEW_SUBCATEGORY, but the new category is the default one
- in this file</para>
- </listitem>
- </itemizedlist>
-
- <para>
- The parent cat can be defined in the same file or in another file, but each
- category may have only one definition.
- </para>
-
- <para>
- Typically, there will be a Category for each module and sub-module, so you
- can independently control logging for each module.
- </para>
-</refsect2>
-
-<refsect2>
- <title>Priority</title>
-
- <para>
- A category may be assigned a threshold priorty. The set of priorites are
- defined by the @gras_log_priority_t enum. Their values are DEBUG, VERBOSE,
- INFO, WARNING, ERROR and CRITICAL.
- </para>
-
- <para>
- If a given category is not assigned a threshold priority, then it inherits
- one from its closest ancestor with an assigned threshold.
- </para>
-
- <para>
- To ensure that all categories can eventually inherit a threshold, the root
- category always has an assigned threshold priority.
- </para>
-
- <para>
- Logging requests are made by invoking a logging macro on a category. All
- of the macros have a printf-style format string followed by arguments.
- Because most C compilers do not support vararg macros, there is a version
- of the macro for any number of arguments from 0 to 6. The macro name ends
- with the total number of arguments.
- </para>
-
- <para>
- Here is an example of the most basic type of macro:
- </para>
-
- <programlisting>CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5, "oops");</programlisting>
-
- <para>This is a logging request with priority WARN.</para>
-
- <para>
- A logging request is said to be enabled if its priority is higher than or
- equal to the threshold priority of its category. Otherwise, the request is
- said to be disabled. A category without an assigned priority will inherit
- one from the hierarchy.
- </para>
-
- <para>
- It is possible to use any non-negative integer as a priority. If, as in the
- example, one of the standard priorites is used, then there is a convenience
- macro that is typically used instead. For example, the above example is
- equivalent to the shorter:
- </para>
-
- <programlisting>CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops");</programlisting>
-</refsect2>
-
-<refsect2>
- <title>Default category</title>
-
- <para>
- If @GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, Parent) or
- @GRAS_LOG_NEW_DEFAULT_CATEGORY(MyCat) is used to create the category, then
- the even shorter form can be used:
- </para>
-
- <programlisting>WARN3("Values are: %d and '%s'", 5, "oops");</programlisting>
-
- <para>
- Only one default category can be created per file, though multiple
- non-defaults can be created and used.
- </para>
-</refsect2>
-
-<refsect2>
- <title>Example</title>
-
- <para>Here is a more complete example:</para>
-
- <programlisting>
- #include "gras.h"
-
- /* create a category and a default subcategory */
- GRAS_LOG_NEW_CATEGORY(VSS);
- GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(SA, VSS);
-
- main() {
- /* Now set the parent's priority.
- (the string would typcially be a runtime option) */
- gras_log_control_set("SA.thresh=3");
-
- /* This request is enabled, because WARNING >= INFO. */
- CWARN2(VSS, "Low fuel level.");
-
- /* This request is disabled, because DEBUG < INFO. */
- CDEBUG2(VSS, "Starting search for nearest gas station.");
-
- /* The default category SA inherits its priority from VSS. Thus,
- the following request is enabled because INFO >= INFO. */
- INFO1("Located nearest gas station.");
-
- /* This request is disabled, because DEBUG < INFO. */
- DEBUG1("Exiting gas station search");
- }</programlisting>
-</refsect2>
-
-<refsect2>
- <title>Configuration</title>
-
- <para>
- Configuration is typically done during program initialization by invoking
- the gras_log_control_set() method. The control string passed to it
- typically comes from the command line. Look at the doucmentation for that
- function for the format of the control string.
- </para>
-</refsect2>
-
-<refsect2>
- <title>Performance</title>
-
- <para>
- Clever design insures efficiency. Except for the first invocation, a
- disabled logging request requires an a single comparison of a static
- variable to a constant.
- </para>
-
- <para>
- There is also compile time constant, @GRAS_LOG_STATIC_THRESHOLD, which
- causes all logging requests with a lower priority to be optimized to 0 cost
- by the compiler. By setting it to gras_log_priority_infinite, all logging
- requests are statically disabled and cost nothing. Released executables
- might typically be compiled with
- "-DGRAS_LOG_STATIC_THRESHOLD=gras_log_priority_infinite".
- </para>
-</refsect2>
-
-<refsect2>
- <title>Appenders</title>
-
- <para>
- Each category has an optional appender. An appender is a pointer to a
- structure whcih starts with a pointer to a doAppend() function. DoAppend()
- prints a message to a log.
- </para>
-
- <para>
- WHen a category is passed a message by one of the logging macros, the
- category performs the following actions:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- if the category has an appender, the message is passed to the
- appender's doAppend() function,
- </para>
- </listitem>
-
- <listitem>
- <para>
- if 'willLogToParent' is true for the category, the message is passed
- to the category's parent.
- </para>
-
- <para>
- By default, all categories except root have no appender and
- 'willLogToParent' is true. This situation causes all messages to be
- logged by the root category's appender.
- </para>
-
- <para>
- Typically, you would only change the root category's appender when you
- wanted, say, a different output format. Copying defaultLogAppender.c
- would be a good start.
- </para>
-
- <para>
- The default appender function currently prints to stderr, but more
- would be needed, like the one able to send the logs to a remote
- dedicated server.
- </para>
- </listitem>
- </itemizedlist>
-</refsect2>
-
-<refsect2>
- <title>Misc and Caveats</title>
-
- <para>
- Do not use any of the macros that start with '_'.
- </para>
-
- <para>
- The current set of macros force each file to use categories declared in
- that file. This is intentional. Make the category a child of the file's
- module category.
- </para>
-
- <para>
- Log4J has a 'rolling file appender' which you can select with a run-time
- option & specify the max file size. This would be a nice default for
- non-kernel applications.
- </para>
-
- <para>
- Careful, category names are global variables.
- </para>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### ENUM gras_log_priority_t ##### -->
-<para>
-
-</para>
-
-@gras_log_priority_none:
-@gras_log_priority_debug:
-@gras_log_priority_verbose:
-@gras_log_priority_info:
-@gras_log_priority_warning:
-@gras_log_priority_error:
-@gras_log_priority_critical:
-@gras_log_priority_infinite:
-@gras_log_priority_uninitialized:
-
-<!-- ##### FUNCTION gras_log_control_set ##### -->
-<para>
-
-</para>
-
-@cs:
-@Returns:
-
-
-<!-- ##### MACRO GRAS_LOG_NEW_CATEGORY ##### -->
-<para>
-
-</para>
-
-@catName:
-
-
-<!-- ##### MACRO GRAS_LOG_NEW_SUBCATEGORY ##### -->
-<para>
-
-</para>
-
-@catName:
-@parent:
-
-
-<!-- ##### MACRO GRAS_LOG_NEW_DEFAULT_CATEGORY ##### -->
-<para>
-
-</para>
-
-@cname:
-
-
-<!-- ##### MACRO GRAS_LOG_NEW_DEFAULT_SUBCATEGORY ##### -->
-<para>
-
-</para>
-
-@cname:
-@parent:
-
-
-<!-- ##### MACRO GRAS_LOG_DEFAULT_CATEGORY ##### -->
-<para>
-
-</para>
-
-@cname:
-
-
-<!-- ##### MACRO GRAS_LOG_EXTERNAL_CATEGORY ##### -->
-<para>
-
-</para>
-
-@cname:
-
-
-<!-- ##### MACRO GRAS_LOG_ISENABLED ##### -->
-<para>
-
-</para>
-
-@catName:
-@priority:
-
-
-<!-- ##### MACRO GRAS_LOG_STATIC_THRESHOLD ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION gras_log_appender_set ##### -->
-<para>
-
-</para>
-
-@cat:
-@app:
-
-
-<!-- ##### VARIABLE gras_log_default_appender ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### MACRO CDEBUG6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO CVERB6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO CINFO6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO CWARNING6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO CERROR6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO CCRITICAL6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO DEBUG6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO VERB6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO INFO6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO WARNING6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO ERROR6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
-<!-- ##### MACRO CRITICAL6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-
