KUTIL_LOG(3)

NAME
kutil_info, kutil_log, kutil_logx, kutil_openlog, kutil_vinfo, kutil_vlog, kutil_vlogx, kutil_vwarn, kutil_vwarnx kutil_warn, kutil_warnx - format log messages

LIBRARY
libkcgi

SYNOPSIS
#include <sys/types.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <kcgi.h>
void
kutil_info(const struct kreq *r, const char *ident, const char *fmt, ...);
void
kutil_log(const struct kreq *r, const char *level, const char *ident, const char *fmt, ...);
void
kutil_logx(const struct kreq *r, const char *level, const char *ident, const char *fmt, ...);
int
kutil_openlog(const char *file);
void
kutil_vinfo(const struct kreq *r, const char *ident, const char *fmt, va_list ap);
void
kutil_vlog(const struct kreq *r, const char *level, const char *ident, const char *fmt, va_list ap);
void
kutil_vlogx(const struct kreq *r, const char *level, const char *ident, const char *fmt, va_list ap);
void
kutil_vwarn(const struct kreq *r, const char *ident, const char *fmt, va_list ap);
void
kutil_vwarnx(const struct kreq *r, const char *ident, const char *fmt, va_list ap);
void
kutil_warn(const struct kreq *r, const char *ident, const char *fmt, ...);
void
kutil_warnx(const struct kreq *r, const char *ident, const char *fmt, ...);

DESCRIPTION
These convenience functions format messages for reporting on stderr, avoiding common CGI script pitfalls such as unwittingly using localtime(3) when in a chroot(2). Moreover, they allow for a consist logging output format, as most web servers are inconsistent on how they log script output.

The logging functions should be preceded by kutil_openlog, which redirects stderr to file (if it's not NULL) and sets the output as line-buffered to minimise line clobbering. It returns zero on failure (system error) and non-zero on success. Note: if it fails to re-open stderr, the stream may no longer be operable.

The remaining functions accept r, the active request handle opened with khttp_parse(3); level, a human-readable level such as “warn” or “info”; and ident, used in the common scenario of connecting a message to a logged-in user. The level and ident variables may be NULL. For kutil_info, kutil_vinfo, kutil_vwarn, kutil_vwarnx, kutil_warn, and kutil_warnx, the level is “INFO” and “WARN”.

The kutil_vinfo, kutil_vlog, kutil_vlogx, kutil_vwarn, and kutil_vwarnx functions accept a va_start(3) list, while the others use printf(3) format string and arguments. In either format, these printed values are considered untrusted and have non-printable characters replaced with “”? and with white-space (\t, \r, \n) shown as literal escape characters.

The kutil_log, kutil_vlog, kutil_vwarn, and kutil_warn functions print out the current errno as an additional error message.

The output format is as follows, with a trailing newline:

    addr ident [date] level msg
    addr ident [date] level msg: errmsg

Here, “addr” is the remote host as passed to the CGI script; and where “ident” and “level”, if NULL, will be rendered as “-”. The date is formatted as an HTTP date (RFC 822) in GMT.

AUTHORS
The kutil_info, kutil_log, kutil_logx, kutil_openlog, kutil_vinfo, kutil_vlog, kutil_vlogx, kutil_vwarn, kutil_vwarnx, kutil_warn, and kutil_warnx functions were written by Kristaps Dzonsons <kristaps@bsd.lv>.