Logging

Typedefs
typedef void(*	glip_log_fn) (struct glip_ctx *ctx, int priority, const char *file, int line, const char *fn, const char *format, va_list args)

Functions
void	glip_set_log_fn (struct glip_ctx *ctx, glip_log_fn log_fn)
int	glip_get_log_priority (struct glip_ctx *ctx)
void	glip_set_log_priority (struct glip_ctx *ctx, int priority)

Detailed Description

GLIP emits log messages in many cases to help to find problems both during development as well during usage. A configurable logging mechanism allows you to redirect, filter and/or discard the messages based on your application's needs.

GLIP supports three levels of log messages (out of the set defined in syslog.h):

• errors (LOG_ERR)
• information (LOG_INFO)
• debug messages (LOG_DEBUG)

The logging is controlled at build time of the library as well as at runtime. You can set the destination of the log message (i.e. stdout/stderr or a custom message handler) as well as the log level, i.e. which messages are discarded and which are actually logged.

When building glip, two configure options are relevant:

• --enable-logging/--disable-logging

  Enable/disable any logging infrastructure

• --enable-debug/--disable-debug

  Enable debug code and debug log messages

Note

All debugging log messages require debug support to be enabled at build time of GLIP!

Library users can modify the log level through he functions glip_get_log_priority() and glip_set_log_priority().

The end-user of an application using GLIP can modify the log level by setting the GLIP_LOG environment variable to one of the possible log levels to restrict the log output to messages of that level and above. Allowed values for the GLIP_LOG environment variable are:

• err

• info

• debug

In many cases your application using GLIP already has some kind of logging framework in place. In this case, you can route the log messages generated by GLIP to your own logging framework, show them in the user interface, etc. First, create a function matching the glip_log_fn() signature. Then, tell GLIP to use this function as destination for all log messages by registering it with glip_set_log_fn().

Note

It is not possible to redirect messages created by glip_new() to your own logging function; those messages will always be handled by the default log message handler.

Typedef Documentation

typedef void(* glip_log_fn) (struct glip_ctx *ctx, int priority, const char *file, int line, const char *fn, const char *format, va_list args)

Logging function template

Implement a function with this signature and pass it to glip_set_log_fn() if you want to implement custom logging.

Function Documentation

void glip_set_log_fn	(	struct glip_ctx *	ctx,
		glip_log_fn	log_fn
	)

Set logging function

The built-in logging writes to STDERR. It can be overridden by a custom function to log messages into the user's logging functionality.

In many cases you want the log message to be associated with a context or object of your application, i.e. the object that uses GLIP. In this case, set the context or this pointer with glip_set_caller_ctx() and retrieve it inside your log_fn.

An example in C++ could look like this:

static void MyClass::glipLogCallback(struct glip_ctx *gctx,
                                     int priority, const char *file,
                                     int line, const char *fn,
                                     const char *format, va_list args)
{
  MyClass *myclassptr = static_cast<MyClass*>(glip_get_caller_ctx(gctx));
  myclassptr->doLogging(format, args);
}

MyClass::MyClass()
{
  // ...
  glip_set_caller_ctx(gctx, this);
  glip_set_log_fn(&MyClass::glipLogCallback);
  // ...
}

MyClass::doLogging(const char* format, va_list args)
{
   printf("this = %p", this);
   vprintf(format, args);
}

Parameters

ctx	the library context
log_fn	the used logging function

int glip_get_log_priority

(

struct glip_ctx *

ctx

)

Get the logging priority

The logging priority is the lowest message type that is reported.

Parameters

ctx	the library context

Returns

the log priority

See also

glip_set_log_priority()

void glip_set_log_priority	(	struct glip_ctx *	ctx,
		int	priority
	)

Set the logging priority

The logging priority is the lowest message type that is reported.

Allowed values for priority are LOG_DEBUG, LOG_INFO and LOG_ERR as defined in syslog.h.

For example setting priority will to LOG_INFO will result in all error and info messages to be shown, and all debug messages to be discarded.

Parameters

ctx	the library context
priority	new priority value

See also

glip_get_log_priority()