.\" Copyright (c) 2000 Kungliga Tekniska Högskolan
.\" $arla: log_log.3,v 1.6 2002/10/17 09:18:06 lha Exp $
.Dd August 24, 2000
.Dt LOG_LOG 3
.Os UTIL
.Sh NAME
.Nm log_log , 
.Nm log_vlog ,
.Nm log_open ,
.Nm log_close ,
.Nm log_unit_init ,
.Nm log_unit_free ,
.Nm log_set_mask ,
.Nm log_get_mask ,
.Nm log_mask2str ,
.Nm log_set_mask_str
.Nd provides unified logging
.Sh SYNOPSIS
.Fd #include <parse_units.h>
.Fd #include <log.h>
.Fo "void log_log"
.Fa "Log_unit *unit"
.Fa "unsigned level"
.Fa "const char *fmt"
.Fa ...
.Fc
.Fo "void log_vlog"
.Fa "Log_unit *unit"
.Fa "unsigned level"
.Fa "const char *fmt"
.Fa "va_list args"
.Fc
.Fo "Log_method *log_open"
.Fa "char *progname"
.Fa "char *fname"
.Fc
.Fo "void log_close"
.Fa "Log_method *method"
.Fc
.Fo "Log_unit *log_unit_init"
.Fa "Log_method *method"
.Fa "const char *name"
.Fa "struct units *lognames"
.Fa "unsigned long default_mask"
.Fc
.Fo "void log_unit_free"
.Fa "Log_method *method"
.Fa "Log_unit *unit"
.Fc
.Fo "void log_set_mask"
.Fa "Log_unit *unit"
.Fa "unsigned long mask"
.Fc
.Fo "unsigned log_get_mask"
.Fa "Log_unit *unit"
.Fc
.Fo "void log_mask2str"
.Fa "Log_method *method"
.Fa "Log_unit *unit"
.Fa "char *buf"
.Fa "size_t sz"
.Fc
.Fo "void log_set_mask_str"
.Fa "Log_method *method"
.Fa "Log_unit *default_unit"
.Fa "const char *str"
.Fc
.Sh DESCRIPTION
.Nm log_log
will let you have a unified logging system throu-out your whole project.
No more strange errnos like
.Er EINVAL
returned from libraries since they can print to stderr (not knowing
what fd will be connected to fd number 2).
.Pp
.Fn log_open
will open a Log_method that all Log_units will log though, Log_method
controls to what device the log is sent.
Logging devices, passed in fname, are syslog, /dev/stderr, or a file.
.Pp
Options can be passes to the subsystem with an extra colon. Valid
options are:
.D1 syslog[:pid,no-delay,console,stderr[:facility]]
.D1 {/dev/stderr,/file}[:notime]
.Fn log_close
closeses the Log_method and assosiated Log_units.
.Pp
.Fn log_unit_init
will return a logging unit, that is used by a subsystem.
.Pp
.Fn log_unit_free
will free a logging unit allocated by
.Fn log_unit_init .
.Pp
.Fn log_set_mask
set the logging mask for a logging unit.
.Pp
.Fn log_get_mask
get the logging mask for a logging unit.
.Pp
.Fn log_mask2str
convert the longing mask for `unit' (or all if this is NULL), to a
string that can be printed.
The string can be parsed by
.Fn log_set_mask_str .
.Pp
.Fn log_set_mask_str
will set the mask for `default_unit' (or all if this is NULL).
.Sh EXAMPLE
.Bd -literal
#include <parse_units.h>
#include <log.h>
#include <err.h>

enum { A_WARNING = 1, A_DEBUG = 2 };

struct units u_units[] = {
    { "debug",		A_DEBUG },
    { "warning", 	A_WARNING },
    { NULL, 		0 }
};

int
main (int argc, char **argv)
{
    Log_method *m;
    Log_unit *u;
    char buf[1024];

    m = log_open ("log-tester", "/dev/stderr");
    if (m == NULL)
	errx (1, "log_open");

    u = log_unit_init (m, "test-foo", u_units, A_WARNING);
    if (u == NULL)
	errx (1, "log_unit_init");

    log_log (u, A_WARNING, "this should show");
    log_log (u, A_DEBUG, "this should NOT show");

    log_mask2str (m, NULL, buf, sizeof(buf));
    printf ("logmask: %s\\n", buf);

    log_close (m);

    return 0;
}
.Ed
.Sh BUGS
Should maybe include a log_logx version.
.Sh SEE ALSO
.Xr syslog 3 ,
.Xr syslogd 8