path: root/doc/public/xml/cairo-status.xml

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="cairo-Error-handling">
<refmeta>
<refentrytitle role="top_of_page" id="cairo-Error-handling.top_of_page">Error handling</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CAIRO Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Error handling</refname>
<refpurpose>Decoding cairo's status</refpurpose>
</refnamediv>

<refsynopsisdiv id="cairo-Error-handling.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>enum                <link linkend="cairo-status-t">cairo_status_t</link>;
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cairo-status-to-string">cairo_status_to_string</link>              (<parameter><link linkend="cairo-status-t"><type>cairo_status_t</type></link> status</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cairo-debug-reset-static-data">cairo_debug_reset_static_data</link>       (<parameter><type>void</type></parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="cairo-Error-handling.description" role="desc">
<title role="desc.title">Description</title>
<para>
Cairo uses a single status type to represent all kinds of errors.  A status
value of <link linkend="CAIRO-STATUS-SUCCESS:CAPS"><literal>CAIRO_STATUS_SUCCESS</literal></link> represents no error and has an integer value
of zero.  All other status values represent an error.
</para>
<para>
Cairo's error handling is designed to be easy to use and safe.  All major
cairo objects <firstterm>retain</firstterm> an error status internally which
can be queried anytime by the users using cairo*_status() calls.  In
the mean time, it is safe to call all cairo functions normally even if the
underlying object is in an error status.  This means that no error handling
code is required before or after each individual cairo function call.
</para>
</refsect1>
<refsect1 id="cairo-Error-handling.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="cairo-status-t" role="enum">
<title>enum cairo_status_t</title>
<indexterm zone="cairo-status-t"><primary sortas="status_t">cairo_status_t</primary></indexterm>
<programlisting>typedef enum _cairo_status {
    CAIRO_STATUS_SUCCESS = 0,

    CAIRO_STATUS_NO_MEMORY,
    CAIRO_STATUS_INVALID_RESTORE,
    CAIRO_STATUS_INVALID_POP_GROUP,
    CAIRO_STATUS_NO_CURRENT_POINT,
    CAIRO_STATUS_INVALID_MATRIX,
    CAIRO_STATUS_INVALID_STATUS,
    CAIRO_STATUS_NULL_POINTER,
    CAIRO_STATUS_INVALID_STRING,
    CAIRO_STATUS_INVALID_PATH_DATA,
    CAIRO_STATUS_READ_ERROR,
    CAIRO_STATUS_WRITE_ERROR,
    CAIRO_STATUS_SURFACE_FINISHED,
    CAIRO_STATUS_SURFACE_TYPE_MISMATCH,
    CAIRO_STATUS_PATTERN_TYPE_MISMATCH,
    CAIRO_STATUS_INVALID_CONTENT,
    CAIRO_STATUS_INVALID_FORMAT,
    CAIRO_STATUS_INVALID_VISUAL,
    CAIRO_STATUS_FILE_NOT_FOUND,
    CAIRO_STATUS_INVALID_DASH,
    CAIRO_STATUS_INVALID_DSC_COMMENT,
    CAIRO_STATUS_INVALID_INDEX,
    CAIRO_STATUS_CLIP_NOT_REPRESENTABLE,
    CAIRO_STATUS_TEMP_FILE_ERROR,
    CAIRO_STATUS_INVALID_STRIDE,
    CAIRO_STATUS_FONT_TYPE_MISMATCH,
    CAIRO_STATUS_USER_FONT_IMMUTABLE,
    CAIRO_STATUS_USER_FONT_ERROR,
    CAIRO_STATUS_NEGATIVE_COUNT,
    CAIRO_STATUS_INVALID_CLUSTERS,
    CAIRO_STATUS_INVALID_SLANT,
    CAIRO_STATUS_INVALID_WEIGHT,
    CAIRO_STATUS_INVALID_SIZE,
    CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED,
    CAIRO_STATUS_DEVICE_TYPE_MISMATCH,
    CAIRO_STATUS_DEVICE_ERROR,
    CAIRO_STATUS_INVALID_MESH_CONSTRUCTION,

    CAIRO_STATUS_LAST_STATUS
} cairo_status_t;
</programlisting>
<para>
<link linkend="cairo-status-t"><type>cairo_status_t</type></link> is used to indicate errors that can occur when
using Cairo. In some cases it is returned directly by functions.
but when using <link linkend="cairo-t"><type>cairo_t</type></link>, the last error, if any, is stored in
the context and can be retrieved with <link linkend="cairo-status"><function>cairo_status()</function></link>.
</para>
<para>
New entries may be added in future versions.  Use <link linkend="cairo-status-to-string"><function>cairo_status_to_string()</function></link>
to get a human-readable representation of an error message.
</para><variablelist role="enum">
<varlistentry id="CAIRO-STATUS-SUCCESS:CAPS" role="constant">
<term><literal>CAIRO_STATUS_SUCCESS</literal></term>
<listitem><simpara>no error has occurred
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-NO-MEMORY:CAPS" role="constant">
<term><literal>CAIRO_STATUS_NO_MEMORY</literal></term>
<listitem><simpara>out of memory
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-RESTORE:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_RESTORE</literal></term>
<listitem><simpara>cairo_restore() called without matching <link linkend="cairo-save"><function>cairo_save()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-POP-GROUP:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_POP_GROUP</literal></term>
<listitem><simpara>no saved group to pop, i.e. <link linkend="cairo-pop-group"><function>cairo_pop_group()</function></link> without matching <link linkend="cairo-push-group"><function>cairo_push_group()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-NO-CURRENT-POINT:CAPS" role="constant">
<term><literal>CAIRO_STATUS_NO_CURRENT_POINT</literal></term>
<listitem><simpara>no current point defined
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-MATRIX:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_MATRIX</literal></term>
<listitem><simpara>invalid matrix (not invertible)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-STATUS:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_STATUS</literal></term>
<listitem><simpara>invalid value for an input <link linkend="cairo-status-t"><type>cairo_status_t</type></link>
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-NULL-POINTER:CAPS" role="constant">
<term><literal>CAIRO_STATUS_NULL_POINTER</literal></term>
<listitem><simpara><link linkend="NULL:CAPS"><literal>NULL</literal></link> pointer
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-STRING:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_STRING</literal></term>
<listitem><simpara>input string not valid UTF-8
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-PATH-DATA:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_PATH_DATA</literal></term>
<listitem><simpara>input path data not valid
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-READ-ERROR:CAPS" role="constant">
<term><literal>CAIRO_STATUS_READ_ERROR</literal></term>
<listitem><simpara>error while reading from input stream
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-WRITE-ERROR:CAPS" role="constant">
<term><literal>CAIRO_STATUS_WRITE_ERROR</literal></term>
<listitem><simpara>error while writing to output stream
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-SURFACE-FINISHED:CAPS" role="constant">
<term><literal>CAIRO_STATUS_SURFACE_FINISHED</literal></term>
<listitem><simpara>target surface has been finished
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-SURFACE-TYPE-MISMATCH:CAPS" role="constant">
<term><literal>CAIRO_STATUS_SURFACE_TYPE_MISMATCH</literal></term>
<listitem><simpara>the surface type is not appropriate for the operation
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-PATTERN-TYPE-MISMATCH:CAPS" role="constant">
<term><literal>CAIRO_STATUS_PATTERN_TYPE_MISMATCH</literal></term>
<listitem><simpara>the pattern type is not appropriate for the operation
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-CONTENT:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_CONTENT</literal></term>
<listitem><simpara>invalid value for an input <link linkend="cairo-content-t"><type>cairo_content_t</type></link>
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-FORMAT:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_FORMAT</literal></term>
<listitem><simpara>invalid value for an input <link linkend="cairo-format-t"><type>cairo_format_t</type></link>
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-VISUAL:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_VISUAL</literal></term>
<listitem><simpara>invalid value for an input Visual*
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-FILE-NOT-FOUND:CAPS" role="constant">
<term><literal>CAIRO_STATUS_FILE_NOT_FOUND</literal></term>
<listitem><simpara>file not found
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-DASH:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_DASH</literal></term>
<listitem><simpara>invalid value for a dash setting
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-DSC-COMMENT:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_DSC_COMMENT</literal></term>
<listitem><simpara>invalid value for a DSC comment (Since 1.2)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-INDEX:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_INDEX</literal></term>
<listitem><simpara>invalid index passed to getter (Since 1.4)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-CLIP-NOT-REPRESENTABLE:CAPS" role="constant">
<term><literal>CAIRO_STATUS_CLIP_NOT_REPRESENTABLE</literal></term>
<listitem><simpara>clip region not representable in desired format (Since 1.4)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-TEMP-FILE-ERROR:CAPS" role="constant">
<term><literal>CAIRO_STATUS_TEMP_FILE_ERROR</literal></term>
<listitem><simpara>error creating or writing to a temporary file (Since 1.6)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-STRIDE:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_STRIDE</literal></term>
<listitem><simpara>invalid value for stride (Since 1.6)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-FONT-TYPE-MISMATCH:CAPS" role="constant">
<term><literal>CAIRO_STATUS_FONT_TYPE_MISMATCH</literal></term>
<listitem><simpara>the font type is not appropriate for the operation (Since 1.8)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-USER-FONT-IMMUTABLE:CAPS" role="constant">
<term><literal>CAIRO_STATUS_USER_FONT_IMMUTABLE</literal></term>
<listitem><simpara>the user-font is immutable (Since 1.8)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-USER-FONT-ERROR:CAPS" role="constant">
<term><literal>CAIRO_STATUS_USER_FONT_ERROR</literal></term>
<listitem><simpara>error occurred in a user-font callback function (Since 1.8)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-NEGATIVE-COUNT:CAPS" role="constant">
<term><literal>CAIRO_STATUS_NEGATIVE_COUNT</literal></term>
<listitem><simpara>negative number used where it is not allowed (Since 1.8)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-CLUSTERS:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_CLUSTERS</literal></term>
<listitem><simpara>input clusters do not represent the accompanying text and glyph array (Since 1.8)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-SLANT:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_SLANT</literal></term>
<listitem><simpara>invalid value for an input <link linkend="cairo-font-slant-t"><type>cairo_font_slant_t</type></link> (Since 1.8)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-WEIGHT:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_WEIGHT</literal></term>
<listitem><simpara>invalid value for an input <link linkend="cairo-font-weight-t"><type>cairo_font_weight_t</type></link> (Since 1.8)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-SIZE:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_SIZE</literal></term>
<listitem><simpara>invalid value (typically too big) for the size of the input (surface, pattern, etc.) (Since 1.10)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-USER-FONT-NOT-IMPLEMENTED:CAPS" role="constant">
<term><literal>CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED</literal></term>
<listitem><simpara>user-font method not implemented (Since 1.10)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-DEVICE-TYPE-MISMATCH:CAPS" role="constant">
<term><literal>CAIRO_STATUS_DEVICE_TYPE_MISMATCH</literal></term>
<listitem><simpara>the device type is not appropriate for the operation (Since 1.10)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-DEVICE-ERROR:CAPS" role="constant">
<term><literal>CAIRO_STATUS_DEVICE_ERROR</literal></term>
<listitem><simpara>an operation to the device caused an unspecified error (Since 1.10)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-INVALID-MESH-CONSTRUCTION:CAPS" role="constant">
<term><literal>CAIRO_STATUS_INVALID_MESH_CONSTRUCTION</literal></term>
<listitem><simpara>a mesh pattern
  construction operation was used outside of a
  <link linkend="cairo-pattern-mesh-begin-patch"><function>cairo_pattern_mesh_begin_patch()</function></link>/<link linkend="cairo-pattern-mesh-end-patch"><function>cairo_pattern_mesh_end_patch()</function></link>
  pair (Since 1.12)
</simpara></listitem>
</varlistentry>
<varlistentry id="CAIRO-STATUS-LAST-STATUS:CAPS" role="constant">
<term><literal>CAIRO_STATUS_LAST_STATUS</literal></term>
<listitem><simpara>this is a special value indicating the number of
  status values defined in this enumeration.  When using this value, note
  that the version of cairo at run-time may have additional status values
  defined than the value of this symbol at compile-time. (Since 1.10)
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="cairo-status-to-string" role="function">
<title>cairo_status_to_string ()</title>
<indexterm zone="cairo-status-to-string"><primary sortas="status_to_string">cairo_status_to_string</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cairo_status_to_string              (<parameter><link linkend="cairo-status-t"><type>cairo_status_t</type></link> status</parameter>);</programlisting>
<para>
Provides a human-readable description of a <link linkend="cairo-status-t"><type>cairo_status_t</type></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>status</parameter>&#160;:</term>
<listitem><simpara>a cairo status
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a string representation of the status
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="cairo-debug-reset-static-data" role="function">
<title>cairo_debug_reset_static_data ()</title>
<indexterm zone="cairo-debug-reset-static-data"><primary sortas="debug_reset_static_data">cairo_debug_reset_static_data</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cairo_debug_reset_static_data       (<parameter><type>void</type></parameter>);</programlisting>
<para>
Resets all static data within cairo to its original state,
(ie. identical to the state at the time of program invocation). For
example, all caches within cairo will be flushed empty.
</para>
<para>
This function is intended to be useful when using memory-checking
tools such as valgrind. When valgrind's memcheck analyzes a
cairo-using program without a call to <link linkend="cairo-debug-reset-static-data"><function>cairo_debug_reset_static_data()</function></link>,
it will report all data reachable via cairo's static objects as
"still reachable". Calling <link linkend="cairo-debug-reset-static-data"><function>cairo_debug_reset_static_data()</function></link> just prior
to program termination will make it easier to get squeaky clean
reports from valgrind.
</para>
<para>
WARNING: It is only safe to call this function when there are no
active cairo objects remaining, (ie. the appropriate destroy
functions have been called as necessary). If there are active cairo
objects, this call is likely to cause a crash, (eg. an assertion
failure due to a hash table being destroyed when non-empty).
</para></refsect2>

</refsect1>
<refsect1 id="cairo-Error-handling.see-also">
<title>See Also</title>
cairo_status(), <link linkend="cairo-surface-status"><function>cairo_surface_status()</function></link>, <link linkend="cairo-pattern-status"><function>cairo_pattern_status()</function></link>,
           <link linkend="cairo-font-face-status"><function>cairo_font_face_status()</function></link>, <link linkend="cairo-scaled-font-status"><function>cairo_scaled_font_status()</function></link>, 
           <link linkend="cairo-region-status"><function>cairo_region_status()</function></link>
</refsect1>

</refentry>