]> Error handling 3 CAIRO Library Error handling Decoding cairo's status const char * cairo_status_to_string () void cairo_debug_reset_static_data () enumcairo_status_t 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. 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 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 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_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 cairo_status(), cairo_surface_status(), cairo_pattern_status(), cairo_font_face_status(), cairo_scaled_font_status(), cairo_region_status()