<?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">Error handling</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>CAIRO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Error handling</refname>
<refpurpose>Decoding cairo's status</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>



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









<refsect1 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*<link linkend="status"><function>_status()</function></link> 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 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="cairo-status-t" role="enum"/>enum cairo_status_t</title>
<indexterm><primary>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
    /* after adding a new error: update CAIRO_STATUS_LAST_STATUS in cairoint.h */
} 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>
<para>

</para><variablelist role="enum">
<varlistentry>
<term><anchor id="CAIRO-STATUS-SUCCESS:CAPS" role="constant"/><literal>CAIRO_STATUS_SUCCESS</literal></term>
<listitem><simpara> no error has occurred
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-NO-MEMORY:CAPS" role="constant"/><literal>CAIRO_STATUS_NO_MEMORY</literal></term>
<listitem><simpara> out of memory
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-RESTORE:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_RESTORE</literal></term>
<listitem><simpara> <link linkend="cairo-restore"><function>cairo_restore()</function></link> called without matching <link linkend="cairo-save"><function>cairo_save()</function></link>
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-POP-GROUP:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_POP_GROUP</literal></term>
<listitem><simpara> no saved group to pop
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-NO-CURRENT-POINT:CAPS" role="constant"/><literal>CAIRO_STATUS_NO_CURRENT_POINT</literal></term>
<listitem><simpara> no current point defined
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-MATRIX:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_MATRIX</literal></term>
<listitem><simpara> invalid matrix (not invertible)
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-STATUS:CAPS" role="constant"/><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>
<term><anchor id="CAIRO-STATUS-NULL-POINTER:CAPS" role="constant"/><literal>CAIRO_STATUS_NULL_POINTER</literal></term>
<listitem><simpara> <link linkend="NULL:CAPS"><literal>NULL</literal></link> pointer
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-STRING:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_STRING</literal></term>
<listitem><simpara> input string not valid UTF-8
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-PATH-DATA:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_PATH_DATA</literal></term>
<listitem><simpara> input path data not valid
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-READ-ERROR:CAPS" role="constant"/><literal>CAIRO_STATUS_READ_ERROR</literal></term>
<listitem><simpara> error while reading from input stream
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-WRITE-ERROR:CAPS" role="constant"/><literal>CAIRO_STATUS_WRITE_ERROR</literal></term>
<listitem><simpara> error while writing to output stream
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-SURFACE-FINISHED:CAPS" role="constant"/><literal>CAIRO_STATUS_SURFACE_FINISHED</literal></term>
<listitem><simpara> target surface has been finished
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-SURFACE-TYPE-MISMATCH:CAPS" role="constant"/><literal>CAIRO_STATUS_SURFACE_TYPE_MISMATCH</literal></term>
<listitem><simpara> the surface type is not appropriate for the operation
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-PATTERN-TYPE-MISMATCH:CAPS" role="constant"/><literal>CAIRO_STATUS_PATTERN_TYPE_MISMATCH</literal></term>
<listitem><simpara> the pattern type is not appropriate for the operation
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-CONTENT:CAPS" role="constant"/><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>
<term><anchor id="CAIRO-STATUS-INVALID-FORMAT:CAPS" role="constant"/><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>
<term><anchor id="CAIRO-STATUS-INVALID-VISUAL:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_VISUAL</literal></term>
<listitem><simpara> invalid value for an input Visual*
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-FILE-NOT-FOUND:CAPS" role="constant"/><literal>CAIRO_STATUS_FILE_NOT_FOUND</literal></term>
<listitem><simpara> file not found
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-DASH:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_DASH</literal></term>
<listitem><simpara> invalid value for a dash setting
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-DSC-COMMENT:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_DSC_COMMENT</literal></term>
<listitem><simpara> invalid value for a DSC comment (Since 1.2)
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-INVALID-INDEX:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_INDEX</literal></term>
<listitem><simpara> invalid index passed to getter (Since 1.4)
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-CLIP-NOT-REPRESENTABLE:CAPS" role="constant"/><literal>CAIRO_STATUS_CLIP_NOT_REPRESENTABLE</literal></term>
<listitem><simpara> clip region not representable in desired format (Since 1.4)
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="CAIRO-STATUS-TEMP-FILE-ERROR:CAPS" role="constant"/><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>
<term><anchor id="CAIRO-STATUS-INVALID-STRIDE:CAPS" role="constant"/><literal>CAIRO_STATUS_INVALID_STRIDE</literal></term>
<listitem><simpara> invalid value for stride (Since 1.6)
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-status-to-string" role="function"/>cairo_status_to_string ()</title>
<indexterm><primary>cairo_status_to_string</primary></indexterm><programlisting>const <link linkend="char">char</link>*         cairo_status_to_string              (<link linkend="cairo-status-t">cairo_status_t</link> status);</programlisting>
<para>
Provides a human-readable description of a <link linkend="cairo-status-t"><type>cairo_status_t</type></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>status</parameter>&nbsp;:</term>
<listitem><simpara> a cairo status
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a string representation of the status
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="cairo-debug-reset-static-data" role="function"/>cairo_debug_reset_static_data ()</title>
<indexterm><primary>cairo_debug_reset_static_data</primary></indexterm><programlisting><link linkend="void">void</link>                cairo_debug_reset_static_data       (void);</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>
<para>

</para></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<itemizedlist>
<listitem><link linkend="cairo-status"><function>cairo_status()</function></link></listitem>
<listitem><link linkend="cairo-surface-status"><function>cairo_surface_status()</function></link></listitem>
<listitem><link linkend="cairo-pattern-status"><function>cairo_pattern_status()</function></link></listitem>
<listitem><link linkend="cairo-font-face-status"><function>cairo_font_face_status()</function></link></listitem>
<listitem><link linkend="cairo-scaled-font-status"><function>cairo_scaled_font_status()</function></link></listitem>
</itemizedlist>
</para>
</refsect1>


<refsect1><refsect2 /><refsect2 /></refsect1>
</refentry>
