<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="redland-log">
<refmeta>
<refentrytitle role="top_of_page">Logging.</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>REDLAND Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Logging.</refname>
<refpurpose>Message and error logging.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>
<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>
<synopsis>
<link linkend="int">int</link> (<link linkend="librdf-log-level-func">*librdf_log_level_func</link>) (<link linkend="void">void</link> *user_data,
const <link linkend="char">char</link> *message,
<link linkend="va-list">va_list</link> arguments);
<link linkend="int">int</link> (<link linkend="librdf-log-func">*librdf_log_func</link>) (<link linkend="void">void</link> *user_data,
<link linkend="librdf-log-message">librdf_log_message</link> *message);
enum <link linkend="librdf-log-level">librdf_log_level</link>;
enum <link linkend="librdf-log-facility">librdf_log_facility</link>;
<link linkend="int">int</link> <link linkend="librdf-log-message-code">librdf_log_message_code</link> (<link linkend="librdf-log-message">librdf_log_message</link> *message);
<link linkend="librdf-log-level">librdf_log_level</link> <link linkend="librdf-log-message-level">librdf_log_message_level</link> (<link linkend="librdf-log-message">librdf_log_message</link> *message);
<link linkend="librdf-log-facility">librdf_log_facility</link> <link linkend="librdf-log-message-facility">librdf_log_message_facility</link>
(<link linkend="librdf-log-message">librdf_log_message</link> *message);
const <link linkend="char">char</link>* <link linkend="librdf-log-message-message">librdf_log_message_message</link> (<link linkend="librdf-log-message">librdf_log_message</link> *message);
<link linkend="raptor-locator">raptor_locator</link>* <link linkend="librdf-log-message-locator">librdf_log_message_locator</link> (<link linkend="librdf-log-message">librdf_log_message</link> *message);
</synopsis>
</refsynopsisdiv>
<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
Provides structured access to debug, information, warning and error
messages from the libraries. Structured information is most often
used from errors such as parsing where file or URI and line numbers
can be returned via a <link linkend="raptor-locator"><type>raptor_locator</type></link> object pointer found by
<link linkend="librdf-log-message-locator"><function>librdf_log_message_locator()</function></link> on the <link linkend="librdf-log-message"><type>librdf_log_message</type></link>.
</para>
</refsect1>
<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="librdf-log-level-func" role="function"/>librdf_log_level_func ()</title>
<indexterm><primary>librdf_log_level_func</primary></indexterm><programlisting><link linkend="int">int</link> (*librdf_log_level_func) (<link linkend="void">void</link> *user_data,
const <link linkend="char">char</link> *message,
<link linkend="va-list">va_list</link> arguments);</programlisting>
<para>
Handler for one log level, for the warning and error levels ONLY.
Used by <link linkend="librdf-world-set-warning"><type>librdf_world_set_warning</type></link> and <link linkend="librdf-world-set-error"><type>librdf_world_set_error</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara> User data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>message</parameter> :</term>
<listitem><simpara> Log message.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>arguments</parameter> :</term>
<listitem><simpara> Message arguments.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> non-zero to indicate log message has been handled
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="librdf-log-func" role="function"/>librdf_log_func ()</title>
<indexterm><primary>librdf_log_func</primary></indexterm><programlisting><link linkend="int">int</link> (*librdf_log_func) (<link linkend="void">void</link> *user_data,
<link linkend="librdf-log-message">librdf_log_message</link> *message);</programlisting>
<para>
Handler for all log levels.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara> User data pointer
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>message</parameter> :</term>
<listitem><simpara> Log message structure pointer.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> non-zero to indicate log message has been handled
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="librdf-log-level" role="enum"/>enum librdf_log_level</title>
<indexterm><primary>librdf_log_level</primary></indexterm><programlisting>typedef enum {
LIBRDF_LOG_NONE = 0,
LIBRDF_LOG_DEBUG,
LIBRDF_LOG_INFO,
LIBRDF_LOG_WARN,
LIBRDF_LOG_ERROR,
LIBRDF_LOG_FATAL,
LIBRDF_LOG_LAST=LIBRDF_LOG_FATAL
} librdf_log_level;
</programlisting>
<para>
Indicates the level of the log message.</para>
<para>
</para><variablelist role="enum">
<varlistentry>
<term><anchor id="LIBRDF-LOG-NONE:CAPS" role="constant"/><literal>LIBRDF_LOG_NONE</literal></term>
<listitem><simpara> No level
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-LOG-DEBUG:CAPS" role="constant"/><literal>LIBRDF_LOG_DEBUG</literal></term>
<listitem><simpara> Debug.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-LOG-INFO:CAPS" role="constant"/><literal>LIBRDF_LOG_INFO</literal></term>
<listitem><simpara> Information.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-LOG-WARN:CAPS" role="constant"/><literal>LIBRDF_LOG_WARN</literal></term>
<listitem><simpara> Warning.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-LOG-ERROR:CAPS" role="constant"/><literal>LIBRDF_LOG_ERROR</literal></term>
<listitem><simpara> Recoverable error. Program can continue.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-LOG-FATAL:CAPS" role="constant"/><literal>LIBRDF_LOG_FATAL</literal></term>
<listitem><simpara> Fatal error. Program will abort if this is not caught.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-LOG-LAST:CAPS" role="constant"/><literal>LIBRDF_LOG_LAST</literal></term>
<listitem><simpara> Internal, never returned.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="librdf-log-facility" role="enum"/>enum librdf_log_facility</title>
<indexterm><primary>librdf_log_facility</primary></indexterm><programlisting>typedef enum {
LIBRDF_FROM_NONE = 0,
LIBRDF_FROM_CONCEPTS,
LIBRDF_FROM_DIGEST,
LIBRDF_FROM_FILES,
LIBRDF_FROM_HASH,
LIBRDF_FROM_INIT,
LIBRDF_FROM_ITERATOR,
LIBRDF_FROM_LIST,
LIBRDF_FROM_MODEL,
LIBRDF_FROM_NODE,
LIBRDF_FROM_PARSER,
LIBRDF_FROM_QUERY,
LIBRDF_FROM_SERIALIZER,
LIBRDF_FROM_STATEMENT,
LIBRDF_FROM_STORAGE,
LIBRDF_FROM_STREAM,
LIBRDF_FROM_URI,
LIBRDF_FROM_UTF8,
LIBRDF_FROM_MEMORY,
LIBRDF_FROM_LAST=LIBRDF_FROM_MEMORY
} librdf_log_facility;
</programlisting>
<para>
Indicates the part of the system that generated the log message</para>
<para>
</para><variablelist role="enum">
<varlistentry>
<term><anchor id="LIBRDF-FROM-NONE:CAPS" role="constant"/><literal>LIBRDF_FROM_NONE</literal></term>
<listitem><simpara> Associated with no part.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-CONCEPTS:CAPS" role="constant"/><literal>LIBRDF_FROM_CONCEPTS</literal></term>
<listitem><simpara> Concepts
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-DIGEST:CAPS" role="constant"/><literal>LIBRDF_FROM_DIGEST</literal></term>
<listitem><simpara> Digest
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-FILES:CAPS" role="constant"/><literal>LIBRDF_FROM_FILES</literal></term>
<listitem><simpara> Files
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-HASH:CAPS" role="constant"/><literal>LIBRDF_FROM_HASH</literal></term>
<listitem><simpara> Hash
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-INIT:CAPS" role="constant"/><literal>LIBRDF_FROM_INIT</literal></term>
<listitem><simpara> Init
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-ITERATOR:CAPS" role="constant"/><literal>LIBRDF_FROM_ITERATOR</literal></term>
<listitem><simpara> Iterator
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-LIST:CAPS" role="constant"/><literal>LIBRDF_FROM_LIST</literal></term>
<listitem><simpara> List
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-MODEL:CAPS" role="constant"/><literal>LIBRDF_FROM_MODEL</literal></term>
<listitem><simpara> Model
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-NODE:CAPS" role="constant"/><literal>LIBRDF_FROM_NODE</literal></term>
<listitem><simpara> Node
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-PARSER:CAPS" role="constant"/><literal>LIBRDF_FROM_PARSER</literal></term>
<listitem><simpara> Parser
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-QUERY:CAPS" role="constant"/><literal>LIBRDF_FROM_QUERY</literal></term>
<listitem><simpara> Query
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-SERIALIZER:CAPS" role="constant"/><literal>LIBRDF_FROM_SERIALIZER</literal></term>
<listitem><simpara> Serializer
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-STATEMENT:CAPS" role="constant"/><literal>LIBRDF_FROM_STATEMENT</literal></term>
<listitem><simpara> Statement
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-STORAGE:CAPS" role="constant"/><literal>LIBRDF_FROM_STORAGE</literal></term>
<listitem><simpara> Storage
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-STREAM:CAPS" role="constant"/><literal>LIBRDF_FROM_STREAM</literal></term>
<listitem><simpara> Stream
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-URI:CAPS" role="constant"/><literal>LIBRDF_FROM_URI</literal></term>
<listitem><simpara> URI
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-UTF8:CAPS" role="constant"/><literal>LIBRDF_FROM_UTF8</literal></term>
<listitem><simpara> UTF8
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-MEMORY:CAPS" role="constant"/><literal>LIBRDF_FROM_MEMORY</literal></term>
<listitem><simpara> Memory
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="LIBRDF-FROM-LAST:CAPS" role="constant"/><literal>LIBRDF_FROM_LAST</literal></term>
<listitem><simpara> Internal, never returned.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="librdf-log-message-code" role="function"/>librdf_log_message_code ()</title>
<indexterm><primary>librdf_log_message_code</primary></indexterm><programlisting><link linkend="int">int</link> librdf_log_message_code (<link linkend="librdf-log-message">librdf_log_message</link> *message);</programlisting>
<para>
Retrieve error code from log message.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>message</parameter> :</term>
<listitem><simpara> log message
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> int error code
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="librdf-log-message-level" role="function"/>librdf_log_message_level ()</title>
<indexterm><primary>librdf_log_message_level</primary></indexterm><programlisting><link linkend="librdf-log-level">librdf_log_level</link> librdf_log_message_level (<link linkend="librdf-log-message">librdf_log_message</link> *message);</programlisting>
<para>
Retrieve severity of log message.
</para>
<para>
The log message severity level is defined in rdf_log.h as values
of enum <link linkend="librdf-log-level"><type>librdf_log_level</type></link></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>message</parameter> :</term>
<listitem><simpara> log message
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> severity level
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="librdf-log-message-facility" role="function"/>librdf_log_message_facility ()</title>
<indexterm><primary>librdf_log_message_facility</primary></indexterm><programlisting><link linkend="librdf-log-facility">librdf_log_facility</link> librdf_log_message_facility
(<link linkend="librdf-log-message">librdf_log_message</link> *message);</programlisting>
<para>
Retrieve facility that generated the message.
</para>
<para>
The log message facility is defined in rdf_log.h as values
of enum <link linkend="librdf-log-facility"><type>librdf_log_facility</type></link></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>message</parameter> :</term>
<listitem><simpara> log message
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> ID of Redland facility that generated the log message.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="librdf-log-message-message" role="function"/>librdf_log_message_message ()</title>
<indexterm><primary>librdf_log_message_message</primary></indexterm><programlisting>const <link linkend="char">char</link>* librdf_log_message_message (<link linkend="librdf-log-message">librdf_log_message</link> *message);</programlisting>
<para>
Retrieve text message from log entry.
</para>
<para>
The string returned is shared and must be copied by the caller
if required to be retained.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>message</parameter> :</term>
<listitem><simpara> log message
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> shared pointer to the log message string
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="librdf-log-message-locator" role="function"/>librdf_log_message_locator ()</title>
<indexterm><primary>librdf_log_message_locator</primary></indexterm><programlisting><link linkend="raptor-locator">raptor_locator</link>* librdf_log_message_locator (<link linkend="librdf-log-message">librdf_log_message</link> *message);</programlisting>
<para>
Retrieve locator of log entry.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>message</parameter> :</term>
<listitem><simpara> log message
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> pointer to an appropriate raptor_locator* or NULL if not available
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>