Selog hacking notes Please send bug reports and patches to either of my email addresses below, with "selog" in the message subject. I will assume that any contributions are usable under the same terms as selog. Selog is divided into a portable front end written in pure ANSI C (with a few C99 features) and a system-specific back end. (At the moment there is only a Unix back-end; it would be nice to have a Windows back-end if selog becomes popular.) Selog comes with various bindings that adapt other APIs to use selog. The bulk of the portable front-end is in selog_api.c, with the API declarations in selog.h. The latter covers both the public API and the internal API provided by the system-specific back-end. The public API is documented in the manual pages; the comments in the header are for selog's internals. Selog's portablt code is mostly C89, though it uses declarations in for statements, variadic macros, and the boolean type from C99. The portable front-end is responsible for the definitions of the selector and buffer types, and parsing the configuration strings. Selectors are entirely handled by the front-end. The details of buffer filling (such as overflow protection) are handled by the front-end, though the back-end may directly read the internals since there aren't accessor functions. The system-specific back-end defines the available channel types. It's also responsible for parsing the channel specifier parts of the configuration string. The range of channels depends on the system, e.g. the protocol for talking to syslogd on Unix is different from talking to the event logger on Windows. Also the best way of handling concurrent programs appending to the same file tends to require fairly system-specific APIs. So I have deliberately gathered the non-portable code into a single relatively large lump. The requirements for the back-end are documented in selog.h. The current user documentation describes both the generic configuration syntax and the specifics of the Unix channels. Because of that it'll need to be significantly adapted if another back-end is written - and also because man page markup is not that useful on non-Unix systems. The bindings are: selog.c - command-line tool selog_err.c - selog-based replacement for 4.4BSD err & warn selog_syslog.c - selog-based replacement for 4.2BSD syslog selog_lua.c - selog API for Lua These provide some examples of how to use selog. TODO: * Environment variables Ian Jackson - per-program environment variables - an environment variable that is added to the user's configuration, so that it's easy to turn on debugging without affecting normal logging. Patrick Gosling - setuid programs must ignore their environment * Portability Will C99 turn out to be a problem? - Use GNU varargs macros if C99 macros are not available. - Move C99 declarations to traditional locations. * Error handling selog_open() - keep the old config in place while setting up a new one so that the log_config selector continues to work - if there's no previous config, do selog_open("",NULL) first which will prepare things for log_config without the current code's hack selog_write() - remove log_panic stuff from unix code, and instead pass errors up to the portable code; this eliminates recursive panics - some kind of selector-dependent error handling? die/return/sleep? maybe punt problem to an upcall after trying to log the error. --------------------------------------------------------------------------- Written by Tony Finch at the University of Cambridge Computing Service. You may do anything with this, at your own risk. $Cambridge: users/fanf2/selog/HACKING,v 1.5 2008/04/11 18:24:51 fanf2 Exp $