The libgwyfile library contains fundamental functions for reading and writing Gwyddion GWY files as foreign data, i.e. without adopting the Gwyddion object system.
The latest libgwyfile source code and documentation can be found on the project web page at SourceForge.
All macros, declarations and exported symbols bear the gwyfile prefix to avoid clash with other names. Specifically:
Names of this form are to be treated as reserved and avoided for your own symbols. This is recommended even if you are embedding the library as it makes easier updating to its future versions.
Since the GWY file data structures always form a forest of trees, object and items are either roots (including standalone objects and items) or owned by the parent object or item. When you add an item into an object or put an object to an object-holding item, you always transfer the ownership. Only the roots are owned by you.
Specific non-atomic data, such as arrays and strings, are also typically owned by the data item containing them and the item takes care of freeing them when destroyed itself. Specifically, this is always the case when they are created by reading a file. However, the ownership can be transferred between the item and you.
For creation of non-atomic data, there are three types of functions:
Each item construction function has also an item data-setting counterpart. For instance gwyfile_item_set_string(), gwyfile_item_set_string_copy() and gwyfile_item_set_string_const() correspond to the three string item construction functions mentioned above.
For obtaining of non-atomic data, two different types of functions exist:
Roughly, libgwyfile distinguishes three severities of errors
NULL) and setting
ENOMEM. Note too large data encountered during the loading of a GWY file still belong to the previous category and are reported with error domain
NULLas item or object arguments (where not permitted) or trying to take ownership of data that was already taken. The failure to allocate a small fixed-size chunk of memory (e.g. a _GwyfileObject struct) leads to the same reaction, as total heap exhaustion is a non-recoverable error for essentially all programs.
This documentation was generated from the following source code revision:
$Id: gwyfile.c 283 2016-04-27 20:48:28Z yeti-dn $