man/waffle_error.3.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   Copyright Intel 2012
   7
   8   This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0
   9   US). To view a copy of this license, visit http://creativecommons.org.license/by-sa/3.0/us.
  10 -->
  11
  12 <refentry
  13     id="waffle_error"
  14     xmlns:xi="http://www.w3.org/2001/XInclude">
  15
  16   <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->
  17
  18   <refmeta>
  19     <refentrytitle>waffle_init</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>waffle_error</refname>
  25     <refname>waffle_error_get_info</refname>
  26     <refname>waffle_error_get_code</refname>
  27     <refname>waffle_error_to_string</refname>
  28     <refpurpose>Thread-local error state</refpurpose>
  29   </refnamediv>
  30
  31   <refentryinfo>
  32     <title>Waffle Manual</title>
  33     <productname>waffle</productname>
  34     <xi:include href="common/author-chad.versace.xml"/>
  35     <xi:include href="common/copyright.xml"/>
  36     <xi:include href="common/legalnotice.xml"/>
  37   </refentryinfo>
  38
  39   <refsynopsisdiv>
  40
  41     <funcsynopsis language="C">
  42
  43       <funcsynopsisinfo>
  44 #include &lt;waffle.h&gt;
  45
  46 enum waffle_error {...};
  47
  48 struct waffle_error_info {
  49     enum waffle_error code;
  50     const char *message;
  51     size_t message_length;
  52 };
  53       </funcsynopsisinfo>
  54
  55       <funcprototype>
  56         <funcdef>const struct waffle_error_info* <function>waffle_error_get_info</function></funcdef>
  57         <void/>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>enum waffle_error <function>waffle_error_get_code</function></funcdef>
  62         <void/>
  63       </funcprototype>
  64
  65       <funcprototype>
  66         <funcdef>const char* <function>waffle_error_to_string</function></funcdef>
  67         <paramdef>enum waffle_error<parameter>e</parameter></paramdef>
  68       </funcprototype>
  69
  70     </funcsynopsis>
  71   </refsynopsisdiv>
  72
  73   <refsect1>
  74     <title>Description</title>
  75
  76     <para>
  77       Waffle functions usually return either a <type>bool</type>, in which false indicates failure, or a pointer, in
  78       which null indicates failure. In addition to returning a flag indicating failure, most functions also clear and
  79       then set some thread-local error state.
  80     </para>
  81     <para>
  82       The only functions that do not alter waffle's error state are listed here and are explicitly documented as such.
  83       All functions listed here can be called before waffle has been successfully initialized with
  84       <citerefentry><refentrytitle><function>waffle_init</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
  85     </para>
  86
  87     <variablelist>
  88
  89       <varlistentry>
  90         <term><type>struct waffle_error_info</type></term>
  91         <listitem>
  92           <para>
  93             This struct contains the user-visible portion of waffle's thread-local error state.
  94           </para>
  95           <para>
  96             <structfield>code</structfield> may be any token from <type>enum waffle_error</type>.
  97           </para>
  98           <para>
  99             <structfield>message</structfield> often contains a descriptive message about the error.
 100             It is never null, though it may be the empty string.
 101           </para>
 102           <para>
 103             <structfield>message_length</structfield> is the length of <structfield>message</structfield> according to
 104             <citerefentry><refentrytitle><function>strlen</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 105           </para>
 106         </listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><function>waffle_error_to_string()</function></term>
 111         <listitem>
 112           <para>
 113             Convert a <type>waffle_error</type> token to a string.
 114             For example, convert <constant>WAFFLE_ERROR_UNKNOWN</constant> to <code>"WAFFLE_ERROR_UNKNOWN"</code>.
 115             Return null if the token is not a valid error token.
 116           </para>
 117           <para>
 118             This function always sets the error code to <constant>WAFFLE_ERROR_NONE</constant>.
 119           </para>
 120         </listitem>
 121       </varlistentry>
 122
 123
 124       <varlistentry>
 125         <term><function>waffle_error_get_info()</function></term>
 126         <listitem>
 127           <para>
 128             Get information about the current thread's error state.
 129           </para>
 130           <para>
 131             This function never returns null. The returned pointer becomes invalid when the thread-local error state
 132             changes.
 133           </para>
 134           <para>
 135             This function does not alter waffle's error state.
 136           </para>
 137         </listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term><function>waffle_error_get_code()</function></term>
 142         <listitem>
 143           <para>
 144             Get the current thread's error code. Calling this function is equivalent to obtaining the error code with
 145             <code>waffle_error_get_info()->code</code>.
 146           </para>
 147           <para>
 148             This function does not alter waffle's error state.
 149           </para>
 150         </listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><type>enum waffle_error</type></term>
 155         <listitem>
 156           <para>
 157             For reference, below is the complete list of waffle's error codes.
 158
 159             <variablelist>
 160
 161               <varlistentry>
 162                 <term><constant>WAFFLE_NO_ERROR</constant> = 0x00</term>
 163                 <listitem>
 164                   <para>
 165                     The function succeeded.
 166                   </para>
 167                 </listitem>
 168               </varlistentry>
 169
 170               <varlistentry>
 171                 <term><constant>WAFFLE_ERROR_FATAL</constant> = 0x01</term>
 172                 <listitem>
 173                   <para>
 174                     Waffle encountered a fatal error.  All future waffle calls result in
 175                     undefined behavior.
 176                   </para>
 177                 </listitem>
 178               </varlistentry>
 179
 180               <varlistentry>
 181                 <term><constant>WAFFLE_ERROR_UNKNOWN</constant> = 0x02</term>
 182                 <listitem>
 183                   <para>
 184                     Waffle encountered an error for which it lacks an error code.  This is
 185                     usually produced when an underlying native call, such as
 186                     <citerefentry><refentrytitle><function>XOpenDisplay</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 187                     fails for an unknown reason.
 188                   </para>
 189                 </listitem>
 190               </varlistentry>
 191
 192               <varlistentry>
 193                 <term><constant>WAFFLE_ERROR_INTERNAL</constant> = 0x03</term>
 194                 <listitem>
 195                   <para>
 196                     You found a bug in waffle.  Please report it.  The error message, obtained by
 197                     <function>waffle_error_get_info()</function>, should contain a description of the bug.
 198                   </para>
 199                 </listitem>
 200               </varlistentry>
 201
 202               <varlistentry>
 203                 <term><constant>WAFFLE_ERROR_BAD_ALLOC</constant> = 0x04</term>
 204                 <listitem>
 205                   <para>
 206                     Waffle failed to allocate memory.
 207                   </para>
 208                 </listitem>
 209               </varlistentry>
 210
 211               <varlistentry>
 212                 <term><constant>WAFFLE_ERROR_NOT_INITIALIZED</constant> = 0x05</term>
 213                 <listitem>
 214                   <para>
 215                     The failed function requires waffle to be initialized with
 216                     <citerefentry><refentrytitle><function>waffle_init</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 217                   </para>
 218                 </listitem>
 219               </varlistentry>
 220
 221               <varlistentry>
 222                 <term><constant>WAFFLE_ERROR_ALREADY_INITIALIZED</constant> = 0x06</term>
 223                 <listitem>
 224                   <para>
 225                     If waffle has already been initialized by a successful call to
 226                     <citerefentry><refentrytitle><function>waffle_init</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 227                     then subsequent calls to <function>waffle_init()</function> produce this error.
 228                   </para>
 229                 </listitem>
 230               </varlistentry>
 231
 232               <varlistentry>
 233                 <term><constant>WAFFLE_ERROR_BAD_ATTRIBUTE</constant> = 0x08</term>
 234                 <listitem>
 235                   <para>
 236                     An unrecognized attribute name or attribute value was passed in an
 237                     attribute list.
 238                   </para>
 239                 </listitem>
 240               </varlistentry>
 241
 242               <varlistentry>
 243                 <term><constant>WAFFLE_ERROR_BAD_PARAMETER</constant> = 0x10</term>
 244                 <listitem>
 245                   <para>
 246                     The failed function was passed an invalid argument.
 247                   </para>
 248                 </listitem>
 249               </varlistentry>
 250
 251               <varlistentry>
 252                 <term><constant>WAFFLE_ERROR_BAD_DISPLAY_MATCH</constant> = 0x11</term>
 253                 <listitem>
 254                   <para>
 255                     The waffle objects passed to the failed function belong to different
 256                     displays.
 257                   </para>
 258                 </listitem>
 259               </varlistentry>
 260
 261               <varlistentry>
 262                 <term><constant>WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM</constant> = 0x12</term>
 263                 <listitem>
 264                   <para>
 265                     The requested action is unsupported on the current system or platform, but is otherwise valid.
 266                   </para>
 267                   <para>
 268                     For example, attempting to choose a <type>waffle_config</type> whose API is OpenGL ES1 on a system
 269                     that doesn't OpenGL ES1 will produce this error.
 270                   </para>
 271                 </listitem>
 272               </varlistentry>
 273
 274               <varlistentry>
 275                 <term><constant>WAFFLE_ERROR_BUILT_WITHOUT_SUPPORT</constant> = 0x13</term>
 276                 <listitem>
 277                   <para>
 278                     Waffle was built without support for the requested action.
 279                   </para>
 280                   <para>
 281                     For example, if waffle was built without support for GBM, then calling <code>waffle_init()</code>
 282                     with attribute <code>WAFFLE_PLATFORM=WAFFLE_PLATFORM_GBM</code> will produce this error.
 283                 </para>
 284                 </listitem>
 285               </varlistentry>
 286
 287             </variablelist>
 288           </para>
 289         </listitem>
 290       </varlistentry>
 291
 292     </variablelist>
 293
 294   </refsect1>
 295
 296   <xi:include href="common/issues.xml"/>
 297
 298   <refsect1>
 299     <title>See Also</title>
 300     <para>
 301       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 302     </para>
 303   </refsect1>
 304
 305 </refentry>
 306
 307 <!--
 308 vim:tw=120 et ts=2 sw=2:
 309 -->