## Error handling

Error handling — Decoding cairo's status

## Synopsis

    enum                cairo_status_t;
    const char *        cairo_status_to_string              (cairo_status_t status);
    void                cairo_debug_reset_static_data       (void);

## Description

Cairo uses a single status type to represent all kinds of errors. A status value of `CAIRO_STATUS_SUCCESS` represents no error and has an integer value of zero. All other status values represent an error.

Cairo's error handling is designed to be easy to use and safe. All major cairo objects retain 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.

## Details

### enum cairo_status_t

    typedef enum {
        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_DEVICE_FINISHED,

        CAIRO_STATUS_LAST_STATUS
    } cairo_status_t;

cairo_status_t is used to indicate errors that can occur when using Cairo. In some cases it is returned directly by functions. but when using cairo_t, the last error, if any, is stored in the context and can be retrieved with `cairo_status()`.

New entries may be added in future versions. Use `cairo_status_to_string()` to get a human-readable representation of an error message.

`CAIRO_STATUS_SUCCESS` | no error has occurred (Since 1.0)
`CAIRO_STATUS_NO_MEMORY` | out of memory (Since 1.0)
`CAIRO_STATUS_INVALID_RESTORE` | cairo_restore() called without matching `cairo_save()` (Since 1.0)
`CAIRO_STATUS_INVALID_POP_GROUP` | no saved group to pop, i.e. `cairo_pop_group()` without matching `cairo_push_group()` (Since 1.0)
`CAIRO_STATUS_NO_CURRENT_POINT` | no current point defined (Since 1.0)
`CAIRO_STATUS_INVALID_MATRIX` | invalid matrix (not invertible) (Since 1.0)
`CAIRO_STATUS_INVALID_STATUS` | invalid value for an input cairo_status_t (Since 1.0)
`CAIRO_STATUS_NULL_POINTER` | `NULL` pointer (Since 1.0)
`CAIRO_STATUS_INVALID_STRING` | input string not valid UTF-8 (Since 1.0)
`CAIRO_STATUS_INVALID_PATH_DATA` | input path data not valid (Since 1.0)
`CAIRO_STATUS_READ_ERROR` | error while reading from input stream (Since 1.0)
`CAIRO_STATUS_WRITE_ERROR` | error while writing to output stream (Since 1.0)
`CAIRO_STATUS_SURFACE_FINISHED` | target surface has been finished (Since 1.0)
`CAIRO_STATUS_SURFACE_TYPE_MISMATCH` | the surface type is not appropriate for the operation (Since 1.0)
`CAIRO_STATUS_PATTERN_TYPE_MISMATCH` | the pattern type is not appropriate for the operation (Since 1.0)
`CAIRO_STATUS_INVALID_CONTENT` | invalid value for an input cairo_content_t (Since 1.0)
`CAIRO_STATUS_INVALID_FORMAT` | invalid value for an input cairo_format_t (Since 1.0)
`CAIRO_STATUS_INVALID_VISUAL` | invalid value for an input Visual* (Since 1.0)
`CAIRO_STATUS_FILE_NOT_FOUND` | file not found (Since 1.0)
`CAIRO_STATUS_INVALID_DASH` | invalid value for a dash setting (Since 1.0)
`CAIRO_STATUS_INVALID_DSC_COMMENT` | invalid value for a DSC comment (Since 1.2)
`CAIRO_STATUS_INVALID_INDEX` | invalid index passed to getter (Since 1.4)
`CAIRO_STATUS_CLIP_NOT_REPRESENTABLE` | clip region not representable in desired format (Since 1.4)
`CAIRO_STATUS_TEMP_FILE_ERROR` | error creating or writing to a temporary file (Since 1.6)
`CAIRO_STATUS_INVALID_STRIDE` | invalid value for stride (Since 1.6)
`CAIRO_STATUS_FONT_TYPE_MISMATCH` | the font type is not appropriate for the operation (Since 1.8)
`CAIRO_STATUS_USER_FONT_IMMUTABLE` | the user-font is immutable (Since 1.8)
`CAIRO_STATUS_USER_FONT_ERROR` | error occurred in a user-font callback function (Since 1.8)
`CAIRO_STATUS_NEGATIVE_COUNT` | negative number used where it is not allowed (Since 1.8)
`CAIRO_STATUS_INVALID_CLUSTERS` | input clusters do not represent the accompanying text and glyph array (Since 1.8)
`CAIRO_STATUS_INVALID_SLANT` | invalid value for an input cairo_font_slant_t (Since 1.8)
`CAIRO_STATUS_INVALID_WEIGHT` | invalid value for an input cairo_font_weight_t (Since 1.8)
`CAIRO_STATUS_INVALID_SIZE` | invalid value (typically too big) for the size of the input (surface, pattern, etc.) (Since 1.10)
`CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED` | user-font method not implemented (Since 1.10)
`CAIRO_STATUS_DEVICE_TYPE_MISMATCH` | the device type is not appropriate for the operation (Since 1.10)
`CAIRO_STATUS_DEVICE_ERROR` | an operation to the device caused an unspecified error (Since 1.10)
`CAIRO_STATUS_INVALID_MESH_CONSTRUCTION` | a mesh pattern construction operation was used outside of a `cairo_mesh_pattern_begin_patch()`/`cairo_mesh_pattern_end_patch()` pair (Since 1.12)
`CAIRO_STATUS_DEVICE_FINISHED` | target device has been finished (Since 1.12)
`CAIRO_STATUS_LAST_STATUS` | 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)

Since 1.0

### cairo_status_to_string ()

    const char *        cairo_status_to_string              (cairo_status_t status);

Provides a human-readable description of a cairo_status_t.

`status` : | a cairo status
Returns : | a string representation of the status

Since 1.0

### cairo_debug_reset_static_data ()

    void                cairo_debug_reset_static_data       (void);

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.

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 `cairo_debug_reset_static_data()`, it will report all data reachable via cairo's static objects as "still reachable". Calling `cairo_debug_reset_static_data()` just prior to program termination will make it easier to get squeaky clean reports from valgrind.

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).

Since 1.0

## See Also

cairo_status(), `cairo_surface_status()`, `cairo_pattern_status()`, `cairo_font_face_status()`, `cairo_scaled_font_status()`, `cairo_region_status()`