Llog -- A leveled message logging library.
The Llog library provides a means to write log
messages from your software and control which message are logged and
if logged their destination at run time. Using Llog is very
much like putting fprintf() statments in your code however with
Llog
each message is tagged by level and compared to a level threshold before
it is logged. Also messages can be directed to either std[err|out],
a log file or to the system's syslog facility. This later option
provides great flexibilty. In addition is is possible to automatically
prepend the program name and/or a time stamp to each message. Also
provided are a small set of debugging macros. These include an implementation
of ASSERT and work like the library functions in messages thay
accept are routed and thresholded but in addition the macros can be disabled
at compile time and not take up any space in the production code.
Quick Start.
To begin using the library simply follow the example
code below:
int main()
{
Llog_setlvl(LL_DEBUG);
Llog_debug("Hello World, I can
count %d, %d, %d\n", 1, 2, 3);
exit(0);
}
The Functions:
There are to groups of functions. The first called
"Setup Functions" below are used to tell the Llog library what to do.
There are reasonable default setting so you don't need to call any of these
unless you don't like the defaulf settings. The next set called "Logging
Functions" is what you would typically sprinkle throughout your program.
Notice that these functions accept a variable number of arguments much
like fprintf() does. These is also a set of debugging macros
supplied. The macros use the loging functions so theirmessages are
subjected to the same thresholding and routing logic but the marcos my
be completely removed by definnning LLOG_NODEBUG when compiling.
Setup Funtions
-
void Llog_setlvl(int level);
-
void Llog_setprefix(const char *pre);
-
void Llog_timestamp_UTC();
-
void Llog_timestamp_local();
-
void Llog_syslog();
-
void Llog_setlogfile(const char *logfilename);
-
void Llog_close();
Logging Funtions
-
void Llog(int level, const char *fmt, ...);
-
void Llog_debug (const char *fmt,
...);
-
void Llog_verbose (const char *fmt, ...);
-
void Llog_warning (const char *fmt, ...);
-
void Llog_error (const char *fmt,
...);
Debugging Macros
-
LLOG_MARK
-
LLOG_DEBUG(a)
-
LLOG_ASSERT(a)
Alphabitical Listing
-
void Llog(int level, const char *fmt, ...);
Process a message if its level is above the current threshold.
The message may go to either a log file, std[err|out] or to the
syslog facility. Llog acepts a variable number of arguments.
The second argument "fmt" is a format specification identical
to the one used in fprintf(). Any arguments that follow
are put into the format in the manner of fprintf().
If level is set to either LL_ERROR or LL_WARNING
then the word "ERROR " or "WARNING " will
be automatically prepended to the message text. (Note the space inside
the quotes.) If level is set to anything else nothing is prepended
to the message text.
A fixed string may also be appended to all messages by
using the function Llog_prefix. The suggested use of this function
is to prepend the name of the program to each logged message.
Each message may also have a timestamp prepended to it.
The time can be either local or UTC. See the Llog_timestamp_UTC()
and Llog_timestamp_local().
-
void Llog_close();
Close the log. This is not really needed as they
will be closed automatically when the program terminates but if loging
is to be stopped or changed before termination this function may help free
upresources.
-
void Llog_debug(const char *fmt, ...);
Much like calling Llog() with level = LL_DEBUG.
-
void Llog_error(const char *fmt, ...);
Much like calling Llog() with level = LL_ERROR.
-
void Llog_setlogfile(const char *logfilename);
If a valid file name is given all messages will be sent
there and NOT send to std[err|out]. Note that Llog_syslog()
will override.
-
void Llog_setlvl(int level);
Set the message level threshold. Only messages
that are at or "above" the current message level threshold will be processed.
The valid message levels are and their intended use are:
-
LL_ERROR
A significant problem where the program cannot continue.
-
LL_WARNING
An unexpected condition but the program can continue
-
LL_VERBOSE
A normal condition or informational message to the user
-
LL_DEBUG
An informative message that would only be usfull to a
programer who is debugging or testing the application.
If Llog_setlvl() is not called the message level defaults
to LL_WARNING. This is a resonable default for most applications
as only warnning and error messages would be processed. It is suggested
that the message threshold line be made an argument on the program's comand
like or a setting, perhaps a "radio button" on a GUI. This way the
threshold can be adjusted at run time by theuser without need to re-compile.
-
void Llog_setprefix(const char *pre);
Set text string to be prepended to ever message.
Normally one would do something like: Llog_setprefix("ProgramName:
")
-
void Llog_syslog();
Calling this function will cause all messages to be routed
to the syslog facility and NOT and any other place. When messages are being
send to the syslog they are not timestamped as the syslog facility does
it's own timestamping.
-
void Llog_timestamp_UTC();
Calling this function will cause all messages to be "timestamped"
using UTC time. UTC time is also called GMT time or Zulu time.
Messages are NOT timestamped if they are being routed to the syslog as
the syslog facility does it's own timestamping.
-
void Llog_timestamp_local();
Calling this function will cause all messages to be "timestamped"
using local time. Messages are NOT timestamped if they are being
routed to the syslog as the syslog facility does it's own timestamping.
-
void Llog_verbose(const char *fmt, ...);
Much like calling Llog() with level = LL_VERBOSE.
-
void Llog_warning(const char *fmt, ...);
Much like calling Llog() with level = LL_WARNING.