doc/xml/liboildebug.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
   4 >
   5 <refentry id="liboil-liboildebug">
   6 <refmeta>
   7 <refentrytitle role="top_of_page" id="liboil-liboildebug.top_of_page">Debug</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>LIBOIL Library</refmiscinfo>
  10 </refmeta>
  11
  12 <refnamediv>
  13 <refname>Debug</refname>
  14 <refpurpose>Printing and formatting debug information</refpurpose>
  15 </refnamediv>
  16
  17 <refsynopsisdiv id="liboil-liboildebug.synopsis" role="synopsis">
  18 <title role="synopsis.title">Synopsis</title>
  19
  20 <synopsis>
  21 <link linkend="void">void</link>                (<link linkend="OilDebugPrintFunc">*OilDebugPrintFunc</link>)                (<link linkend="int">int</link> level,
  22                                                          const <link linkend="char">char</link> *file,
  23                                                          const <link linkend="char">char</link> *func,
  24                                                          <link linkend="int">int</link> line,
  25                                                          const <link linkend="char">char</link> *format,
  26                                                          <link linkend="va-list">va_list</link> varargs);
  27 enum                <link linkend="OilDebugLevel">OilDebugLevel</link>;
  28 <link linkend="void">void</link>                <link linkend="oil-debug-set-print-function">oil_debug_set_print_function</link>        (<link linkend="OilDebugPrintFunc">OilDebugPrintFunc</link> func);
  29 <link linkend="int">int</link>                 <link linkend="oil-debug-get-level">oil_debug_get_level</link>                 (void);
  30 <link linkend="void">void</link>                <link linkend="oil-debug-set-level">oil_debug_set_level</link>                 (<link linkend="int">int</link> level);
  31 #define             <link linkend="OIL-ERROR--CAPS">OIL_ERROR</link>                           (...)
  32 #define             <link linkend="OIL-WARNING--CAPS">OIL_WARNING</link>                         (...)
  33 #define             <link linkend="OIL-INFO--CAPS">OIL_INFO</link>                            (...)
  34 #define             <link linkend="OIL-DEBUG--CAPS">OIL_DEBUG</link>                           (...)
  35 #define             <link linkend="OIL-LOG--CAPS">OIL_LOG</link>                             (...)
  36 #define             <link linkend="OIL-FUNCTION--CAPS">OIL_FUNCTION</link>
  37 #define             <link linkend="OIL-DEBUG-PRINT--CAPS">OIL_DEBUG_PRINT</link>                     (level, ...)
  38 </synopsis>
  39 </refsynopsisdiv>
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49 <refsect1 id="liboil-liboildebug.description" role="desc">
  50 <title role="desc.title">Description</title>
  51 <para>
  52 </para>
  53 <para>
  54 </para>
  55 </refsect1>
  56
  57 <refsect1 id="liboil-liboildebug.details" role="details">
  58 <title role="details.title">Details</title>
  59 <refsect2 id="OilDebugPrintFunc" role="function">
  60 <title>OilDebugPrintFunc ()</title>
  61 <indexterm zone="OilDebugPrintFunc"><primary sortas="OilDebugPrintFunc">OilDebugPrintFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*OilDebugPrintFunc)                (<link linkend="int">int</link> level,
  62                                                          const <link linkend="char">char</link> *file,
  63                                                          const <link linkend="char">char</link> *func,
  64                                                          <link linkend="int">int</link> line,
  65                                                          const <link linkend="char">char</link> *format,
  66                                                          <link linkend="va-list">va_list</link> varargs);</programlisting>
  67 <para>
  68 Typedef describing functions that can be registered using
  69 <link linkend="oil-debug-set-print-function"><function>oil_debug_set_print_function()</function></link> so that it is called to
  70 print debugging messages.</para>
  71 <para>
  72 </para><variablelist role="params">
  73 <varlistentry><term><parameter>level</parameter>&#160;:</term>
  74 <listitem><simpara> the debug level
  75 </simpara></listitem></varlistentry>
  76 <varlistentry><term><parameter>file</parameter>&#160;:</term>
  77 <listitem><simpara> name of the file where the debug message occurs
  78 </simpara></listitem></varlistentry>
  79 <varlistentry><term><parameter>func</parameter>&#160;:</term>
  80 <listitem><simpara> name of the function where the debug message occurs
  81 </simpara></listitem></varlistentry>
  82 <varlistentry><term><parameter>line</parameter>&#160;:</term>
  83 <listitem><simpara> line in the file where the debug message occurs
  84 </simpara></listitem></varlistentry>
  85 <varlistentry><term><parameter>format</parameter>&#160;:</term>
  86 <listitem><simpara> a printf format
  87 </simpara></listitem></varlistentry>
  88 <varlistentry><term><parameter>varargs</parameter>&#160;:</term>
  89 <listitem><simpara> varargs for the printf format
  90 </simpara></listitem></varlistentry>
  91 </variablelist></refsect2>
  92 <refsect2 id="OilDebugLevel" role="enum">
  93 <title>enum OilDebugLevel</title>
  94 <indexterm zone="OilDebugLevel"><primary sortas="OilDebugLevel">OilDebugLevel</primary></indexterm><programlisting>typedef enum {
  95   OIL_DEBUG_NONE = 0,
  96   OIL_DEBUG_ERROR,
  97   OIL_DEBUG_WARNING,
  98   OIL_DEBUG_INFO,
  99   OIL_DEBUG_DEBUG,
 100   OIL_DEBUG_LOG
 101 } OilDebugLevel;
 102 </programlisting>
 103 <para>
 104 Enumeration describing debug levels in Liboil.</para>
 105 <para>
 106 </para></refsect2>
 107 <refsect2 id="oil-debug-set-print-function" role="function">
 108 <title>oil_debug_set_print_function ()</title>
 109 <indexterm zone="oil-debug-set-print-function"><primary sortas="oil_debug_set_print_function">oil_debug_set_print_function</primary></indexterm><programlisting><link linkend="void">void</link>                oil_debug_set_print_function        (<link linkend="OilDebugPrintFunc">OilDebugPrintFunc</link> func);</programlisting>
 110 <para>
 111 Sets the function to call when outputting debugging information.
 112 A value of NULL for <parameter>func</parameter> will restore the default handler,
 113 which prints debugging information to stderr.</para>
 114 <para>
 115 </para><variablelist role="params">
 116 <varlistentry><term><parameter>func</parameter>&#160;:</term>
 117 <listitem><simpara>
 118 </simpara></listitem></varlistentry>
 119 </variablelist></refsect2>
 120 <refsect2 id="oil-debug-get-level" role="function">
 121 <title>oil_debug_get_level ()</title>
 122 <indexterm zone="oil-debug-get-level"><primary sortas="oil_debug_get_level">oil_debug_get_level</primary></indexterm><programlisting><link linkend="int">int</link>                 oil_debug_get_level                 (void);</programlisting>
 123 <para>
 124 Gets the current debug level.</para>
 125 <para>
 126 </para><variablelist role="params">
 127 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the current debug level
 128 </simpara></listitem></varlistentry>
 129 </variablelist></refsect2>
 130 <refsect2 id="oil-debug-set-level" role="function">
 131 <title>oil_debug_set_level ()</title>
 132 <indexterm zone="oil-debug-set-level"><primary sortas="oil_debug_set_level">oil_debug_set_level</primary></indexterm><programlisting><link linkend="void">void</link>                oil_debug_set_level                 (<link linkend="int">int</link> level);</programlisting>
 133 <para>
 134 Sets the current debug level.</para>
 135 <para>
 136 </para><variablelist role="params">
 137 <varlistentry><term><parameter>level</parameter>&#160;:</term>
 138 <listitem><simpara> the new debug level
 139 </simpara></listitem></varlistentry>
 140 </variablelist></refsect2>
 141 <refsect2 id="OIL-ERROR--CAPS" role="macro">
 142 <title>OIL_ERROR()</title>
 143 <indexterm zone="OIL-ERROR--CAPS"><primary sortas="OIL_ERROR">OIL_ERROR</primary></indexterm><programlisting>#define OIL_ERROR(...) OIL_DEBUG_PRINT(OIL_DEBUG_ERROR, __VA_ARGS__)
 144 </programlisting>
 145 <para>
 146 Macro to call <link linkend="OIL-DEBUG-PRINT--CAPS"><function>OIL_DEBUG_PRINT()</function></link> with a level of <link linkend="OIL-DEBUG-ERROR--CAPS"><type>OIL_DEBUG_ERROR</type></link>.</para>
 147 <para>
 148 </para><variablelist role="params">
 149 <varlistentry><term><parameter>...</parameter>&#160;:</term>
 150 <listitem><simpara>
 151 </simpara></listitem></varlistentry>
 152 </variablelist></refsect2>
 153 <refsect2 id="OIL-WARNING--CAPS" role="macro">
 154 <title>OIL_WARNING()</title>
 155 <indexterm zone="OIL-WARNING--CAPS"><primary sortas="OIL_WARNING">OIL_WARNING</primary></indexterm><programlisting>#define OIL_WARNING(...) OIL_DEBUG_PRINT(OIL_DEBUG_WARNING, __VA_ARGS__)
 156 </programlisting>
 157 <para>
 158 Macro to call <link linkend="OIL-DEBUG-PRINT--CAPS"><function>OIL_DEBUG_PRINT()</function></link> with a level of <link linkend="OIL-DEBUG-WARNING--CAPS"><type>OIL_DEBUG_WARNING</type></link>.</para>
 159 <para>
 160 </para><variablelist role="params">
 161 <varlistentry><term><parameter>...</parameter>&#160;:</term>
 162 <listitem><simpara>
 163 </simpara></listitem></varlistentry>
 164 </variablelist></refsect2>
 165 <refsect2 id="OIL-INFO--CAPS" role="macro">
 166 <title>OIL_INFO()</title>
 167 <indexterm zone="OIL-INFO--CAPS"><primary sortas="OIL_INFO">OIL_INFO</primary></indexterm><programlisting>#define OIL_INFO(...) OIL_DEBUG_PRINT(OIL_DEBUG_INFO, __VA_ARGS__)
 168 </programlisting>
 169 <para>
 170 Macro to call <link linkend="OIL-DEBUG-PRINT--CAPS"><function>OIL_DEBUG_PRINT()</function></link> with a level of <link linkend="OIL-DEBUG-INFO--CAPS"><type>OIL_DEBUG_INFO</type></link>.</para>
 171 <para>
 172 </para><variablelist role="params">
 173 <varlistentry><term><parameter>...</parameter>&#160;:</term>
 174 <listitem><simpara>
 175 </simpara></listitem></varlistentry>
 176 </variablelist></refsect2>
 177 <refsect2 id="OIL-DEBUG--CAPS" role="macro">
 178 <title>OIL_DEBUG()</title>
 179 <indexterm zone="OIL-DEBUG--CAPS"><primary sortas="OIL_DEBUG">OIL_DEBUG</primary></indexterm><programlisting>#define OIL_DEBUG(...) OIL_DEBUG_PRINT(OIL_DEBUG_DEBUG, __VA_ARGS__)
 180 </programlisting>
 181 <para>
 182 Macro to call <link linkend="OIL-DEBUG-PRINT--CAPS"><function>OIL_DEBUG_PRINT()</function></link> with a level of <link linkend="OIL-DEBUG-DEBUG--CAPS"><type>OIL_DEBUG_DEBUG</type></link>.</para>
 183 <para>
 184 </para><variablelist role="params">
 185 <varlistentry><term><parameter>...</parameter>&#160;:</term>
 186 <listitem><simpara>
 187 </simpara></listitem></varlistentry>
 188 </variablelist></refsect2>
 189 <refsect2 id="OIL-LOG--CAPS" role="macro">
 190 <title>OIL_LOG()</title>
 191 <indexterm zone="OIL-LOG--CAPS"><primary sortas="OIL_LOG">OIL_LOG</primary></indexterm><programlisting>#define OIL_LOG(...) OIL_DEBUG_PRINT(OIL_DEBUG_LOG, __VA_ARGS__)
 192 </programlisting>
 193 <para>
 194 Macro to call <link linkend="OIL-DEBUG-PRINT--CAPS"><function>OIL_DEBUG_PRINT()</function></link> with a level of <link linkend="OIL-DEBUG-LOG--CAPS"><type>OIL_DEBUG_LOG</type></link>.</para>
 195 <para>
 196 </para><variablelist role="params">
 197 <varlistentry><term><parameter>...</parameter>&#160;:</term>
 198 <listitem><simpara>
 199 </simpara></listitem></varlistentry>
 200 </variablelist></refsect2>
 201 <refsect2 id="OIL-FUNCTION--CAPS" role="macro">
 202 <title>OIL_FUNCTION</title>
 203 <indexterm zone="OIL-FUNCTION--CAPS"><primary sortas="OIL_FUNCTION">OIL_FUNCTION</primary></indexterm><programlisting>#define             OIL_FUNCTION</programlisting>
 204 <para>
 205 Internal macro that points to __PRETTY_FUNCTION__ or __func__
 206 if the former is not available.</para>
 207 <para>
 208 </para></refsect2>
 209 <refsect2 id="OIL-DEBUG-PRINT--CAPS" role="macro">
 210 <title>OIL_DEBUG_PRINT()</title>
 211 <indexterm zone="OIL-DEBUG-PRINT--CAPS"><primary sortas="OIL_DEBUG_PRINT">OIL_DEBUG_PRINT</primary></indexterm><programlisting>#define             OIL_DEBUG_PRINT(level, ...)</programlisting>
 212 <para>
 213 Macro to call <link linkend="oil-debug-print"><function>oil_debug_print()</function></link> with the correct values for
 214 the name of the source file, line of source file, and function.</para>
 215 <para>
 216 </para><variablelist role="params">
 217 <varlistentry><term><parameter>level</parameter>&#160;:</term>
 218 <listitem><simpara>
 219 </simpara></listitem></varlistentry>
 220 <varlistentry><term><parameter>...</parameter>&#160;:</term>
 221 <listitem><simpara>
 222 </simpara></listitem></varlistentry>
 223 </variablelist></refsect2>
 224
 225 </refsect1>
 226
 227
 228
 229
 230 </refentry>