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>