LOG_OPEN(3debug) Library calls LOG_OPEN(3debug)
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 spec-
ified 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 dif-
ferent 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 unfor-
tunately 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 imple-
mented 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 cor-
rect 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://thread-
ing.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>
Unix August 2004 LOG_OPEN(3debug)