NAME¶
log_open, log_close, log_reset, log_flush, log_printf, log_vprintf, log_putc,
log_puts - log routines for debugging
LIBRARIES¶
Debug Library (-ldebug)
SYNOPSIS¶
#include <debug/log.h>
int log_open(const char *logfile, int level, int flags);
void log_close(void);
int log_reset(void);
int log_flush(void);
int log_printf(int level, const char *fmt, ...);
int log_vprintf(int level, const char *fmt, va_list ap);
int log_putc(int level, int c);
int log_puts(int level, const char *str);
DESCRIPTION¶
log_open() initializes the logging system. The filename of the file to
which messages are logged should be specified by
logfile, or
NULL if messages should be printed to the console. The values for
level and
flags are given in the next section.
From version 0.4.1 onwards the debug library also supports logging to syslog
instead of a file. Instead of specifying a file, just specify a string in the
form
ident.facility, where
ident is a string which will be
prepended to each syslog message and is usually the program name. The
facility should be the facility to which messages should be logged.
log_close() flushes all pending messages, and closes the file descriptor
of the log file (if any).
log_reset() reinitializes the logging system. If any files are currently
opened for writing, it will be closed and reopened. This is useful if you need
to rotate log files.
log_flush() flushes all pending messages (if any).
log_printf() and
log_vprintf() are replacements for
printf(3) and
vprintf(3) respectively.
log_putc() will log a single character. This is the equivalent of
putchar(3).
log_puts() will log a string. It is the equivalent of
puts(3),
except that is does not append a trailing newline.
PARAMETERS¶
This section lists the parameters used to set the values of
level and
flags.
level¶
This determines the importance of the message. The levels are, in order of
decreasing verbosity:
- LOG_NOISY
- verbose debug messages
- LOG_DEBUG
- debug messages
- LOG_VERBOSE
- informational messages
- LOG_NORMAL
- normal, but significant, conditions
- LOG_WARNING
- warning conditions
- LOG_ERROR
- error conditions
- LOG_QUIET
- no messages are printed
The
level argument to
log_printf(),
log_vprintf(),
log_putc(), and
log_puts() specify the level at which the
message should be printed. It does not make sense to specify
LOG_QUIET
to these functions.
The
level argument to
log_open() sets the verbosity of the
program. Any messages printed with a
level higher (more verbose) than
that specified to the
log_open() function, will be discarded.
flags¶
The
flags argument to
log_open() is an OR of any of these:
- LOG_HAVE_COLORS
- If this flag is specified and messages are printed to the console (i.e. no
log file is specified), messages will be printed in different colors,
depending on their log level.
- LOG_PRINT_FUNCTION
- If this flag is specified, the function in which the print function was
called would be printed in addition to the filename and line number.
- LOG_DEBUG_PREFIX_ONLY
- If this flag is specified, only messages with a level higher or equal to
(i.e. more or as verbose) LOG_DEBUG will be printed in color and
with file, line number, and (if necessary), the function.
- LOG_DETECT_DUPLICATES
- If this flag is specified, messages would be buffered and duplicate lines
would not be printed. Instead, the first message would be printed,
followed by a line describing the number of times the message repeated.
This is a great way to prevent flooding, but unfortunately it has the side
effect of always being one statement behind.
- LOG_DETECT_FLOODING
- If specified, the rate at which messages are printed would be limited in
order to avoid flooding. This feature have not been implemented yet, and
is currently ignored.
RETURN VALUE¶
All functions except
log_close() return 0 if successful, -1 if some error
occurred. Check errno to see which error occurred.
If
log_reset() or
log_open() fails, behaviour is undefined and it
should be assumed that no logging is possible.
The
log_close() function returns no value.
NOTES¶
If this routines are combined with the memory routines, care should be taken to
call open and close functions in the right order. The correct order is as
follows:
mem_open (NULL);
log_open (NULL,LOG_NORMAL,LOG_HAVE_COLORS | LOG_PRINT_FUNCTION);
atexit (mem_close);
atexit (log_close);
Of course,
atexit(3) should only be used if the program will not forked.
None of the libdebug routines are thread-safe. I'm not planning to change this
either! For more information, please see
http://threading.2038bug.com/
SEE ALSO¶
mem_open(3),
errno(3),
atexit(3),
printf(3),
vprintf(3),
putchar(3),
puts(3)
logrotate(8),
syslog(3),
logger(1)
AUTHOR¶
Written by Abraham vd Merwe <abz@blio.com>