/* ** OSSP l2 - Flexible Logging ** Copyright (c) 2001-2005 Cable & Wireless ** Copyright (c) 2001-2005 The OSSP Project ** Copyright (c) 2001-2005 Ralf S. Engelschall ** ** This file is part of OSSP l2, a flexible logging library which ** can be found at http://www.ossp.org/pkg/lib/l2/. ** ** Permission to use, copy, modify, and distribute this software for ** any purpose with or without fee is hereby granted, provided that ** the above copyright notice and this permission notice appear in all ** copies. ** ** THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED ** WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF ** MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. ** IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR ** CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF ** USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ** ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, ** OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT ** OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF ** SUCH DAMAGE. ** ** l2.h: C API */ #ifndef __L2_H__ #define __L2_H__ /* version information (compile-time) */ #define L2_VERSION_STR "@L2_VERSION_STR@" #define L2_VERSION_HEX @L2_VERSION_HEX@ /* version information (run-time) */ typedef struct { const int v_hex; const char *v_short; const char *v_long; const char *v_tex; const char *v_gnu; const char *v_web; const char *v_sccs; const char *v_rcs; } l2_version_t; extern l2_version_t l2_version; /* include standard environment we are based on */ #include #include #include #include /* counterbalance poor standard environments */ #ifndef NULL #define NULL (void *)0 #endif #ifndef FALSE #define FALSE (0) #endif #ifndef TRUE #define TRUE (!FALSE) #endif /* forward declarations for opaque data structures */ union l2_context_un; struct l2_param_st; struct l2_stream_st; struct l2_channel_st; struct l2_handler_st; struct l2_env_st; /* corresponding data types for data structures */ typedef union l2_context_un l2_context_t; typedef struct l2_param_st l2_param_t; typedef struct l2_handler_st l2_handler_t; typedef struct l2_stream_st l2_stream_t; typedef struct l2_channel_st l2_channel_t; typedef struct l2_env_st l2_env_t; /* list of logging levels (high to low priority; low to high amount of logging) */ typedef enum { L2_LEVEL_NONE = 0, L2_LEVEL_PANIC = (1 << 0), L2_LEVEL_CRITICAL = (1 << 1), L2_LEVEL_ERROR = (1 << 2), L2_LEVEL_WARNING = (1 << 3), L2_LEVEL_NOTICE = (1 << 4), L2_LEVEL_INFO = (1 << 5), L2_LEVEL_TRACE = (1 << 6), L2_LEVEL_DEBUG = (1 << 7) } l2_level_t; /* macro describing a particular custom level */ #define L2_LEVEL_CUSTOM(n) (1 << (8+(n)) /* macro describing all levels */ #define L2_LEVEL_ALL ((1 << (8+9+1))-1) /* macro describing all levels from highest (PANIC) to and including a particular low level */ #define L2_LEVEL_UPTO(level) (((level)-1)|(level)) /* list of return values */ typedef enum { L2_OK, /* everything ok */ L2_OK_PASS, /* everything ok - pass downstream */ L2_ERR_ARG, /* invalid argument */ L2_ERR_USE, /* invalid usage */ L2_ERR_MEM, /* no more memory available */ L2_ERR_SYS, /* system error (see errno) */ L2_ERR_IO, /* input/output error */ L2_ERR_FMT, /* message formating error */ L2_ERR_INT, /* internal error */ L2_ERR_SYN, /* syntax error */ L2_ERR_CH /* no (more) channel found */ } l2_result_t; /* context union for storing data */ union l2_context_un { char c; short s; int i; long l; float f; double d; char *cp; void *vp; }; /* list of types for storing data */ typedef enum { L2_TYPE_INT, L2_TYPE_FLT, L2_TYPE_STR } l2_type_t; /* parameter specification */ struct l2_param_st { char *name; l2_type_t type; void *store; }; /* parameter constructors */ #define L2_PARAM_SET(pa,n,t,s) \ pa.name = #n, pa.type = L2_TYPE_##t, pa.store = s #define L2_PARAM_END(pa) \ pa.name = NULL /* list of handler types */ typedef enum { L2_CHANNEL_FILTER, L2_CHANNEL_OUTPUT } l2_chtype_t; /* list of linking modes */ typedef enum { L2_LINK_CHILD, L2_LINK_SIBLING } l2_link_t; /* channel handler specification structure */ struct l2_handler_st { const char *name; l2_chtype_t type; l2_result_t (*create) (l2_context_t *ctx, l2_channel_t *ch); l2_result_t (*configure)(l2_context_t *ctx, l2_channel_t *ch, const char *fmt, va_list ap); l2_result_t (*open) (l2_context_t *ctx, l2_channel_t *ch); l2_result_t (*write) (l2_context_t *ctx, l2_channel_t *ch, l2_level_t level, const char *buf, size_t bufsize); l2_result_t (*flush) (l2_context_t *ctx, l2_channel_t *ch); l2_result_t (*close) (l2_context_t *ctx, l2_channel_t *ch); l2_result_t (*destroy) (l2_context_t *ctx, l2_channel_t *ch); }; /* type of formatter callback function */ typedef l2_result_t (*l2_formatter_t)( l2_context_t *ctx, /* application context */ const char id, /* input arg: format string id ('x' of '%x') */ const char *param, /* input arg: format string parameter ('foo' of '%{foo}x') */ char *bufptr, /* input arg: pointer to output buffer */ size_t bufsize, /* input arg: maximum size of output buffer */ size_t *buflen, /* ouput arg: written characters in output buffer */ va_list *ap /* in/out arg: variable argument pointer */ ); /* list of shipped (output) channel handlers (pre-configured in l2_env_t objects) */ extern l2_handler_t l2_handler_null; extern l2_handler_t l2_handler_fd; extern l2_handler_t l2_handler_file; extern l2_handler_t l2_handler_pipe; extern l2_handler_t l2_handler_socket; extern l2_handler_t l2_handler_syslog; extern l2_handler_t l2_handler_smtp; /* list of shipped (filter) channel handlers (pre-configured in l2_env_t objects) */ extern l2_handler_t l2_handler_noop; extern l2_handler_t l2_handler_filter; extern l2_handler_t l2_handler_prefix; extern l2_handler_t l2_handler_buffer; /* context operations */ l2_result_t l2_env_create (l2_env_t **env); l2_result_t l2_env_destroy (l2_env_t *env); l2_result_t l2_env_levels (l2_env_t *env, unsigned int levelmask, unsigned int flushmask); l2_result_t l2_env_formatter (l2_env_t *env, char id, l2_formatter_t cb, l2_context_t *ctx); l2_result_t l2_env_handler (l2_env_t *env, l2_handler_t *h); l2_result_t l2_env_errorinfo (l2_env_t *env, l2_result_t rv, const char *fmt, ...); char *l2_env_strerror (l2_env_t *env, l2_result_t rv); l2_result_t l2_env_settimer (l2_env_t *env, int iInterval); /* channel operations */ l2_result_t l2_channel_create (l2_channel_t **ch, l2_env_t *env, const char *name); l2_result_t l2_channel_destroy (l2_channel_t *ch); l2_result_t l2_channel_levels (l2_channel_t *ch, unsigned int levelmask, unsigned int flushmask); l2_result_t l2_channel_configure (l2_channel_t *ch, const char *fmt, ...); l2_result_t l2_channel_open (l2_channel_t *ch); l2_result_t l2_channel_write (l2_channel_t *ch, l2_level_t level, const char *buf, size_t bufsize); l2_result_t l2_channel_flush (l2_channel_t *ch); l2_result_t l2_channel_close (l2_channel_t *ch); l2_result_t l2_channel_log (l2_channel_t *ch, l2_level_t level, const char *fmt, ...); l2_result_t l2_channel_vlog (l2_channel_t *ch, l2_level_t level, const char *fmt, va_list ap); l2_result_t l2_channel_link (l2_channel_t *ch, l2_link_t id, l2_channel_t *ch2, ...); l2_result_t l2_channel_unlink (l2_channel_t *ch); l2_result_t l2_channel_upstream (l2_channel_t *ch, l2_channel_t **chU); l2_result_t l2_channel_downstream (l2_channel_t *ch, l2_channel_t **chD); l2_result_t l2_channel_type (l2_channel_t *ch, l2_chtype_t *type); l2_result_t l2_channel_env (l2_channel_t *ch, l2_env_t **env); /* channel tree specification operations */ l2_result_t l2_spec (l2_channel_t **ch, l2_env_t *env, const char *spec, ...); l2_result_t l2_vspec (l2_channel_t **ch, l2_env_t *env, const char *spec, va_list ap); /* utility operations */ l2_result_t l2_util_setparams (l2_env_t *env, l2_param_t p[], const char *fmt, va_list ap); l2_result_t l2_util_l2s (char *string, size_t maxlen, int sep, unsigned int levelmask); l2_result_t l2_util_s2l (const char *string, size_t maxlen, int sep, unsigned int *levelmask); l2_result_t l2_util_fmt_string (l2_context_t *, const char, const char *, char *, size_t, size_t *, va_list *); l2_result_t l2_util_fmt_dump (l2_context_t *, const char, const char *, char *, size_t, size_t *, va_list *); l2_result_t l2_util_fmt_errno (l2_context_t *, const char, const char *, char *, size_t, size_t *, va_list *); #endif /* __L2_H__ */