util/log_log.3

   1 .\" Copyright (c) 2000 Kungliga Tekniska Högskolan
   2 .\" $Id$
   3 .Dd August 24, 2000
   4 .Dt LOG_LOG 3
   5 .Os UTIL
   6 .Sh NAME
   7 .Nm log_log ,
   8 .Nm log_vlog ,
   9 .Nm log_open ,
  10 .Nm log_close ,
  11 .Nm log_unit_init ,
  12 .Nm log_unit_free ,
  13 .Nm log_set_mask ,
  14 .Nm log_get_mask ,
  15 .Nm log_mask2str ,
  16 .Nm log_set_mask_str
  17 .Nd provides unified logging
  18 .Sh SYNOPSIS
  19 .Fd #include <parse_units.h>
  20 .Fd #include <log.h>
  21 .Fo "void log_log"
  22 .Fa "Log_unit *unit"
  23 .Fa "unsigned level"
  24 .Fa "const char *fmt"
  25 .Fa ...
  26 .Fc
  27 .Fo "void log_vlog"
  28 .Fa "Log_unit *unit"
  29 .Fa "unsigned level"
  30 .Fa "const char *fmt"
  31 .Fa "va_list args"
  32 .Fc
  33 .Fo "Log_method *log_open"
  34 .Fa "char *progname"
  35 .Fa "char *fname"
  36 .Fc
  37 .Fo "void log_close"
  38 .Fa "Log_method *method"
  39 .Fc
  40 .Fo "Log_unit *log_unit_init"
  41 .Fa "Log_method *method"
  42 .Fa "const char *name"
  43 .Fa "struct units *lognames"
  44 .Fa "unsigned long default_mask"
  45 .Fc
  46 .Fo "void log_unit_free"
  47 .Fa "Log_method *method"
  48 .Fa "Log_unit *unit"
  49 .Fc
  50 .Fo "void log_set_mask"
  51 .Fa "Log_unit *unit"
  52 .Fa "unsigned long mask"
  53 .Fc
  54 .Fo "unsigned log_get_mask"
  55 .Fa "Log_unit *unit"
  56 .Fc
  57 .Fo "void log_mask2str"
  58 .Fa "Log_method *method"
  59 .Fa "Log_unit *unit"
  60 .Fa "char *buf"
  61 .Fa "size_t sz"
  62 .Fc
  63 .Fo "void log_set_mask_str"
  64 .Fa "Log_method *method"
  65 .Fa "Log_unit *default_unit"
  66 .Fa "const char *str"
  67 .Fc
  68 .Sh DESCRIPTION
  69 .Nm log_log
  70 will let you have a unified logging system throu-out your whole project.
  71 No more strange errnos like
  72 .Er EINVAL
  73 returned from libraries since they can print to stderr (not knowing
  74 what fd will be connected to fd number 2).
  75 .Pp
  76 .Fn log_open
  77 will open a Log_method that all Log_units will log though, Log_method
  78 controls to what device the log is sent.
  79 Logging devices, passed in fname, are syslog, /dev/stderr, or a file.
  80 .Pp
  81 Options can be passes to the subsystem with an extra colon. Valid
  82 options are:
  83 .D1 syslog[:pid,no-delay,console,stderr[:facility]]
  84 .D1 {/dev/stderr,/file}[:notime]
  85 .Fn log_close
  86 closeses the Log_method and assosiated Log_units.
  87 .Pp
  88 .Fn log_unit_init
  89 will return a logging unit, that is used by a subsystem.
  90 .Pp
  91 .Fn log_unit_free
  92 will free a logging unit allocated by
  93 .Fn log_unit_init .
  94 .Pp
  95 .Fn log_set_mask
  96 set the logging mask for a logging unit.
  97 .Pp
  98 .Fn log_get_mask
  99 get the logging mask for a logging unit.
 100 .Pp
 101 .Fn log_mask2str
 102 convert the longing mask for `unit' (or all if this is NULL), to a
 103 string that can be printed.
 104 The string can be parsed by
 105 .Fn log_set_mask_str .
 106 .Pp
 107 .Fn log_set_mask_str
 108 will set the mask for `default_unit' (or all if this is NULL).
 109 .Sh EXAMPLE
 110 .Bd -literal
 111 #include <parse_units.h>
 112 #include <log.h>
 113 #include <err.h>
 114
 115 enum { A_WARNING = 1, A_DEBUG = 2 };
 116
 117 struct units u_units[] = {
 118     { "debug",          A_DEBUG },
 119     { "warning",        A_WARNING },
 120     { NULL,             0 }
 121 };
 122
 123 int
 124 main (int argc, char **argv)
 125 {
 126     Log_method *m;
 127     Log_unit *u;
 128     char buf[1024];
 129
 130     m = log_open ("log-tester", "/dev/stderr");
 131     if (m == NULL)
 132         errx (1, "log_open");
 133
 134     u = log_unit_init (m, "test-foo", u_units, A_WARNING);
 135     if (u == NULL)
 136         errx (1, "log_unit_init");
 137
 138     log_log (u, A_WARNING, "this should show");
 139     log_log (u, A_DEBUG, "this should NOT show");
 140
 141     log_mask2str (m, NULL, buf, sizeof(buf));
 142     printf ("logmask: %s\\n", buf);
 143
 144     log_close (m);
 145
 146     return 0;
 147 }
 148 .Ed
 149 .Sh BUGS
 150 Should maybe include a log_logx version.
 151 .Sh SEE ALSO
 152 .Xr syslog 3 ,
 153 .Xr syslogd 8