OSSP L2
=======

Idea:
l2_handler_t:
   - function pointers
   - sizeof(handler struct)
   - table of config callsbacks
     which use offsetof into handler struct
Auf diese Weise ist l2_channel_setparams aus API
draussen und..

Timeplan
--------

o M1 
  - fixed C API
  - established build environment
o M2
  - implemented C API
  - fixed C++ API
o M3
  - implemented C++ API
  - documented C API
  - documented C++ API
  - release version 0.9.0
o M4
  - release version 1.0.0

ATTENTION
---------

o hook_write's should perhaps receive a nul-termined string
  instead of buf+size, because syslog else has to re-buffer it.

BRAINSTORMING
-------------

Channel Handler Configuration:
o l2_handler_null
  - no configuration at all
o l2_handler_fd
  - mode="unix|stdio"
  - fd=int|FILE*
o l2_handler_file
  - mode="unix|stdio"
  - path=char*
  - append="yes|no"
o l2_handler_pipe
  - url="prg:/path/to/program"
  - fd=int
o l2_handler_socket
  - url="tcp://hostname:port"
  - fd=int
o l2_handler_syslog
  - ident=char*
o l2_handler_filter
  - pattern=char*
o l2_handler_prefix
  - prefix=char*
o l2_handler_buffer
  - size=size_t

Stream Members:
o channels static array
  - consider dynamic

Braindump:
- debugging is special case of logging
- tracing is special case of debugging

License:
- ISC/MIT/BSD

Sprache:
- C++
- C

Aufbau:
1. Layer C++ API      log.hpp,  log.cpp
2. Layer C   API      log.h     log.c
3. Layer C   Backend  backend.h backend.c
- "make striptease"

- optimierung:
log(..)
{
}
:
log(....);
:

API Levels:
- PANIC    (-> LOG_EMERG)
- CRITICAL (-> LOG_CRIT)
- ERROR    (-> LOG_ERR)
- WARNING
- NOTICE
- INFO
- TRACE    (-> LOG_DEBUG)
- DEBUG    (-> LOG_DEBUG)

Level Entscheidungen:
>= (default)
<=
=
;
*

Backend Channels:
1 Level -> N Channels
- file (append)
- program (stdin)
- syslog
- stderr/stdout
- null (discard, nicht nur /dev/null)
- filedescriptor (escape/ext)
- callback function

Log Messages:
- raw
- optional prefixes (inclusive order):
  string
  facility
  level
  timestamp
  pid
  (tid)
- errno (like syslog %m)
- eigene %{foo}x mit callback function mit context
- automatisch: number -> string mapping (fuer error strings)
- __FILE__, __LINE__, (__FUNCTION__)

Configuration:
- ueber C/C++ API
- zusaetzlich Config-File
  1. /etc/liblog.conf
  2. (in ., .., ../..)
  3. $HOME/.liblog.conf

- !debug -> !code

API C (ala MM):
- reentrant: log_xxx
- non-reentrant: Log_xxx

Message Filtering/Masking:
- facility und/oder levels und/oder wildcard pattern

API Using:
- C++:
  LogManager logm;
  logm.debug1("test");
  logm.configure("

- C:
  log lh;
  lh = log_init(LOG_CFGFILE|LOG_CFGPARENT|LOG_XXX|..., "foo" (=facility));
  log_configure(lh, "foo", LOG_WARN|LOG_LESSER, null);
  log_cb(lh, "x", func, ctx);
  int func(void *ctx, char *str, ...);
  log_msg(lh, LOG_WARN, "..%{foo}x %s...%E..", cp);
  log_dbg(lh, "..%{foo}x %s...%E..", cp);
  log_kill(lh);

- Buffered I/O:
  fuer manche channels non-buffered (debug, errors)
  fuer manche andere aber buffered (access log, performance)
  loesung: I/O ueber callbacks (3x: open, write, close) z.B. RRDTool

- Varargs:
  log ist nur wrapper fuer vlog

- Error Handling:
  o log kein Return Code
  o aber error callback function (dadrin in C++: throw, in C: exit)

- Newline Handling:
  option fuer channel: \r, \r\n, \n oder gleich string
  und moeglichkeit gar nix (string="")

- Perhaps:
  optionally reopen logfile on each write

- An optional syslog(3) compatible API for converting syslog-only based
  applications (like sendmail) to (restricted) liblog-based applications.

- Ein Wort noch zu variablen Argumentlisten in cpp-Makros: gcc
  unterstützt dies in in der GNU- und der C99-Ausführung. Das heißt,
  der "..." Parameter kann im Makro respektive über "args" und über
  "__VA_ARGS__" angesprochen werden. Wichtig ist dabei, daß "..."
  nicht leer sein -- also kein Argument enthalten -- darf, da sonst
  der Präprocessor an einem eventuell vorhandenen Komma scheitert.
  Dies kann beim gcc durch Voranstellen von "##" vor dem "__VA_ARGS__"
  umgangen werden. Ouch.
  Beide Erweiterungen sind derzeit nicht aktiv, wenn mit -ansi
  compiliert wird. Explizit anschalten läßt sich die standard-konforme
  Erweiterung über "-std=c9x", bzw. "-std=c99" bei neueren gccs.