.. _logging:

Logging
=======

.. warning::

	This document only describes the library user control interface, which
	doesn't cover the actual logging, aimed at library developers.

For debugging purposes, libtio has a debugging interface that allows
displaying messages in the debug stream (usually ``stderr``) with four
different levels (plus a special one):

``info``
	Debug information.

``warn``
	Warnings.

``error``
	Non-fatal errors.

``fatal``
	Fatal errors.

``none``
	Special log level not to print messages.

Each level includes the message from the levels below in the list.

The log level used to be hardcoded into the library (with the configure
script), but it appeared that some users wanted to be able to control it
from the utilities using the library (with a ``--log`` option).

This interface is declared in ``<libtio/log.h>``. For forward compatibility
purposes, it works with strings.

.. c:function:: void tio_setlog(char const *level)

	Set the log level using its name. Setting a log level unknown to the
	library will result in setting the log level to ``none``.

.. c:function:: char const *tio_getlog(void)

	Get a pointer to the current log level (which you shall not free).

Before setting the log level, you should list the recognized log levels. It
is recommended to iterate on them using the following functions for this:

.. c:function:: int tio_iter_log(tio_iter_t **iter)

	Get a log level iterator.

.. c:function:: int tio_next_log(tio_iter_t *iter, char const **ptr)

	Get the next log level on the iterator.

The equivalent in blocking mode is the following:

.. c:type:: tio_log_list_t

	Function type that is called back to list available log levels in a
	blocking way. Is defined as the following:

	.. code-block:: c

		typedef void tio_log_list_t(void *cookie, char const *str);

.. c:function:: void tio_listlog(tio_log_list_t *callback, void *cookie)

	Calls the callback on every recognized log level. It is possible for
	the function to call the callback only once (see the ``--no-log``
	option in :ref:`installing`).

An example log level listing is the following:

.. code-block:: c

	#include <stdio.h>
	#include <stdlib.h>
	#include <libtio.h>

	void callback(void *cookie, const char *str)
	{
		(void)cookie; /* no, cookie, we don't want to use you */
		printf("- %s\n", str);
	}

	int main(void)
	{
		printf("Available log levels:\n");
		tio_listlog(&callback, NULL);
		return (0);
	}