Errors

Data Structures
struct	GwyfileError
	Detailed information about an error. More...
struct	GwyfileErrorList
	List of errors. More...

Enumerations
enum	GwyfileErrorDomain { GWYFILE_ERROR_DOMAIN_SYSTEM = 0 , GWYFILE_ERROR_DOMAIN_DATA = 1 , GWYFILE_ERROR_DOMAIN_VALIDITY = 2 , GWYFILE_ERROR_DOMAIN_WARNING = 3 }
enum	GwyfileErrorCode {   GWYFILE_ERROR_MAGIC = 0 , GWYFILE_ERROR_ITEM_TYPE = 1 , GWYFILE_ERROR_CONFINEMENT = 2 , GWYFILE_ERROR_ARRAY_SIZE = 3 ,   GWYFILE_ERROR_DUPLICATE_NAME = 4 , GWYFILE_ERROR_LONG_STRING = 5 , GWYFILE_ERROR_OBJECT_SIZE = 6 , GWYFILE_ERROR_OBJECT_NAME = 7 ,   GWYFILE_ERROR_MISSING_ITEM = 8 , GWYFILE_ERROR_TOO_DEEP_NESTING = 9 , GWYFILE_ERROR_TRUNCATED = 10 }

Functions
void	gwyfile_error_clear (GwyfileError **error)
	Clears a GwyfileError. More...
void	gwyfile_error_list_init (GwyfileErrorList *errlist)
	Initializes a GwyfileErrorList. More...
void	gwyfile_error_list_clear (GwyfileErrorList *errlist)
	Frees all errors in a GwyfileErrorList. More...

Detailed Description

Details about run-time (expected) errors such as I/O failures or malformed files are reported using GwyfileError structures. See Error handling for a general overview of error handling.

If you are not interested in details of errors you can always pass NULL as the GwyfileError** pointer and just check the function return values.

To request the detailed information, pass the pointer to a NULL initialised GwyfileError* as the error argument. You must then always check the success or failure of each function because error pileup (calling functions with the error struct already filled) is not permitted. Furthermore, GwyfileError* filled with error details has to be freed with gwyfile_error_clear() when no longer needed.

These rules are essentially identical as those for GError in GLib. If you are familiar with GError you should feel at home.

Enumeration Type Documentation

GwyfileErrorCode

enum GwyfileErrorCode

Enumerator
GWYFILE_ERROR_MAGIC	The file does not have the expected magic header.
GWYFILE_ERROR_ITEM_TYPE	Unknown data item type was encountered.
GWYFILE_ERROR_CONFINEMENT	A piece of data does not fit inside its parent object or item. This error means a child object or item tries to be bigger than its parent allows. See also GWYFILE_ERROR_TRUNCATED which is reported for truncated files or buffer.
GWYFILE_ERROR_ARRAY_SIZE	An array has an invalid size, i.e. zero or mismatching other sizes.
GWYFILE_ERROR_DUPLICATE_NAME	Multiple items of the same name were encountered in an object.
GWYFILE_ERROR_LONG_STRING	Too long string was encountered. Currently, libgwyfile has an internal limitation of maximum string size to 0x7ffffffffu (2GB), even though the GWY file format does not have such limitation. No sane file should exceed that.
GWYFILE_ERROR_OBJECT_SIZE	An object size does not fit into a 32bit integer. This error can occur during file writing on systems with larger than 32bit size_t. While it is possible to construct an object larger than 4GB in memory, it cannot be written to a file because sizes in the GWY file format are 32bit.
GWYFILE_ERROR_OBJECT_NAME	A Gwyddion-specific GWY file data object has the wrong name (type).
GWYFILE_ERROR_MISSING_ITEM	A mandatory item in a Gwyddion-specific GWY file data object is missing.
GWYFILE_ERROR_TOO_DEEP_NESTING	The object/item nesting depth exceeds the allowed maximum. Currently, libgwyfile has an internal limitation of maximum object/item nesting level of 200. This is to avoid stack overflow for files with devilishly deep nesting.
GWYFILE_ERROR_TRUNCATED	The top-level object is truncated. For writing this means the buffer size is insufficient. For reading it means the buffer or file does not contain a complete top-level object or item. See also GWYFILE_ERROR_CONFINEMENT. Since 1.4

GwyfileErrorDomain

enum GwyfileErrorDomain

Enumerator
GWYFILE_ERROR_DOMAIN_SYSTEM	System error domain: codes are equal to errno values. They reflect I/O failures and other system errors.
GWYFILE_ERROR_DOMAIN_DATA	Libgwyfle data error domain: codes are equal to GwyfileErrorCode values. They represent data format errors at the physical level, preventing serialization or deserialization.
GWYFILE_ERROR_DOMAIN_VALIDITY	Libgwyfle validity error domain: codes are equal to GwyfileInvalidCode values. Errors from this domain represent violations by the GWY file format specifications not physically prevented during normal libgwyfile calls. They are only reported by explicit gwyfile_check_object() calls. Since 1.1
GWYFILE_ERROR_DOMAIN_WARNING	Libgwyfle validity error domain: codes are equal to GwyfileInvalidCode values. Errors from this domain represent problematic uses of the GWY file format that are, however, not forbidden by the specifications. They are only reported by explicit gwyfile_check_object() calls. Since 1.1

Function Documentation

gwyfile_error_clear()

void gwyfile_error_clear

(

GwyfileError **

error

)

Clears a GwyfileError.

If the argument is NULL or pointer to NULL this function is no-op.

Otherwise it frees the error structure and sets the pointer back to NULL.

Parameters

error

Error structure to clear.

gwyfile_error_list_clear()

void gwyfile_error_list_clear

(

GwyfileErrorList *

errlist

)

Frees all errors in a GwyfileErrorList.

This function clears (frees) all errors in the errors list and resets the list to empty. NULL items may be present in the list.

Note that the structure itself is not freed.

Parameters

errlist

Error list structure to clear.

gwyfile_error_list_init()

void gwyfile_error_list_init

(

GwyfileErrorList *

errlist

)

Initializes a GwyfileErrorList.

The argument should be the pointer to an uninitialized error list structure. It will be initialized to an empty error list.

Parameters

errlist

Error list structure to initialize.