Error handling: Cairo: A Vector Graphics Library

+ + +

Error handling

Error handling — Decoding cairo's status

Functions

++++ + + + + + + + + + + +

const char * +	+cairo_status_to_string () +
+void +	+cairo_debug_reset_static_data () +

Types and Values

++++ + + + + +

enum	cairo_status_t

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.

Functions

cairo_status_to_string ()

const char *
+cairo_status_to_string (cairo_status_t status);

Provides a human-readable description of a cairo_status_t.

Parameters

+++++ + + + + + +

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

Types and Values

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

Members

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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_JBIG2_GLOBAL_MISSING	+ `CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID` has been used on at least one image + but no image provided `CAIRO_MIME_TYPE_JBIG2_GLOBAL` (Since 1.14) +
CAIRO_STATUS_PNG_ERROR	+ error occurred in libpng while reading from or writing to a PNG file (Since 1.16) +
CAIRO_STATUS_FREETYPE_ERROR	+ error occurred in libfreetype (Since 1.16) +
CAIRO_STATUS_WIN32_GDI_ERROR	+ error occurred in the Windows Graphics Device Interface (Since 1.16) +
CAIRO_STATUS_TAG_ERROR	+ invalid tag name, attributes, or nesting (Since 1.16) +
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

Error handling

Functions

Types and Values

Description

Functions

cairo_status_to_string ()

Parameters

Returns

cairo_debug_reset_static_data ()

Types and Values

enum cairo_status_t

Members

See Also