libgta 1.0.6 Read and Write Generic Tagged Array (GTA) files

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- File List
- File Members

Typedefs | Enumerations
gta.h File Reference

The libgta C interface. More...

## Typedefs
typedef struct gta_internal_header_struct | gta_header_t
| The GTA header type.
typedef struct gta_internal_taglist_struct | gta_taglist_t
| The GTA tag list type. More...
typedef size_t(* | gta_read_t )(intptr_t userdata, void *buffer, size_t size, int *error)
| Custom input function. More...
typedef size_t(* | gta_write_t )(intptr_t userdata, const void *buffer, size_t size, int *error)
| Custom output function. More...
typedef void(* | gta_seek_t )(intptr_t userdata, intmax_t offset, int whence, int *error)
| Custom seek function. More...
typedef struct gta_internal_io_state_struct | gta_io_state_t
| State for element-based input/output. More...

## Enumerations
enum | gta_result_t { GTA_OK = 0, GTA_OVERFLOW = 1, GTA_UNSUPPORTED_DATA = 2, GTA_UNEXPECTED_EOF = 3, GTA_INVALID_DATA = 4, GTA_SYSTEM_ERROR = 5 }
| GTA result type. More...
enum | gta_type_t { GTA_INT8 = 1, GTA_UINT8 = 2, GTA_INT16 = 3, GTA_UINT16 = 4, GTA_INT32 = 5, GTA_UINT32 = 6, GTA_INT64 = 7, GTA_UINT64 = 8, GTA_INT128 = 9, GTA_UINT128 = 10, GTA_FLOAT32 = 11, GTA_FLOAT64 = 12, GTA_FLOAT128 = 13, GTA_CFLOAT32 = 14, GTA_CFLOAT64 = 15, GTA_CFLOAT128 = 16, GTA_BLOB = 0 }
| GTA data types. More...
enum | gta_compression_t { GTA_NONE = 0, GTA_ZLIB = 1, GTA_ZLIB1 = 4, GTA_ZLIB2 = 5, GTA_ZLIB3 = 6, GTA_ZLIB4 = 7, GTA_ZLIB5 = 8, GTA_ZLIB6 = 9, GTA_ZLIB7 = 10, GTA_ZLIB8 = 11, GTA_ZLIB9 = 12, GTA_BZIP2 = 2, GTA_XZ = 3 }
| GTA compression algorithms. More...

## Functions
Version information
const char * | gta_version (int *restrict major, int *restrict minor, int *restrict patch)
| Get the libgta version. More...
Create and destroy GTA Headers
gta_result_t | gta_create_header (gta_header_t *restrict *restrict header)
| Create a new GTA header structure and initialize it. More...
gta_result_t | gta_clone_header (gta_header_t *restrict dst_header, const gta_header_t *restrict src_header)
| Clone a GTA header structure. More...
void | gta_destroy_header (gta_header_t *restrict header)
| Destroy a GTA header structure and free its resources. More...
Read and Write GTA Headers
gta_result_t | gta_read_header (gta_header_t *restrict header, gta_read_t read_fn, intptr_t userdata)
| Read a GTA header. More...
gta_result_t | gta_read_header_from_stream (gta_header_t *restrict header, FILE *restrict f)
| Read a GTA header from a stream. More...
gta_result_t | gta_read_header_from_fd (gta_header_t *restrict header, int fd)
| Read a GTA header from a file descriptor. More...
gta_result_t | gta_write_header (const gta_header_t *restrict header, gta_write_t write_fn, intptr_t userdata)
| Write a GTA header. More...
gta_result_t | gta_write_header_to_stream (const gta_header_t *restrict header, FILE *restrict f)
| Write a GTA header to a stream. More...
gta_result_t | gta_write_header_to_fd (const gta_header_t *restrict header, int fd)
| Write a GTA header to a file descriptor. More...
Access GTA Headers
const gta_taglist_t * | gta_get_global_taglist_const (const gta_header_t *restrict header)
| Get the global tag list (non-modifiable). More...
gta_taglist_t * | gta_get_global_taglist (gta_header_t *restrict header)
| Get the global tag list (modifiable). More...
uintmax_t | gta_get_element_size (const gta_header_t *restrict header)
| Return the size of an array element. More...
uintmax_t | gta_get_components (const gta_header_t *restrict header)
| Get the number of components. More...
gta_type_t | gta_get_component_type (const gta_header_t *restrict header, uintmax_t i)
| Get the type of a component. More...
uintmax_t | gta_get_component_size (const gta_header_t *restrict header, uintmax_t i)
| Get the size of a component. More...
const gta_taglist_t * | gta_get_component_taglist_const (const gta_header_t *restrict header, uintmax_t i)
| Get the tag list of a component (non-modifiable). More...
gta_taglist_t * | gta_get_component_taglist (gta_header_t *restrict header, uintmax_t i)
| Get the tag list of a component (modifiable). More...
uintmax_t | gta_get_dimensions (const gta_header_t *restrict header)
| Get the number of dimensions. More...
uintmax_t | gta_get_dimension_size (const gta_header_t *restrict header, uintmax_t i)
| Get the size in a dimension. More...
const gta_taglist_t * | gta_get_dimension_taglist_const (const gta_header_t *restrict header, uintmax_t i)
| Get the tag list of a dimension (non-modifiable). More...
gta_taglist_t * | gta_get_dimension_taglist (gta_header_t *restrict header, uintmax_t i)
| Get the tag list of a dimension (modifiable). More...
uintmax_t | gta_get_elements (const gta_header_t *restrict header)
| Get the total number of elements in the array. More...
uintmax_t | gta_get_data_size (const gta_header_t *restrict header)
| Get the total size of the array data. More...
gta_compression_t | gta_get_compression (const gta_header_t *restrict header)
| Get the compression. More...
void | gta_set_compression (gta_header_t *restrict header, gta_compression_t compression)
| Set the compression. More...
Define an Array
gta_result_t | gta_set_components (gta_header_t *restrict header, uintmax_t n, const gta_type_t *restrict types, const uintmax_t *restrict sizes)
| Set the components of an array element. More...
gta_result_t | gta_set_dimensions (gta_header_t *restrict header, uintmax_t n, const uintmax_t *restrict sizes)
| Set the dimensions. More...
Access Tag Lists
uintmax_t | gta_get_tags (const gta_taglist_t *restrict taglist)
| Get the number of tags in a tag list. More...
const char * | gta_get_tag_name (const gta_taglist_t *restrict taglist, uintmax_t i)
| Get the tag name with the given index. More...
const char * | gta_get_tag_value (const gta_taglist_t *restrict taglist, uintmax_t i)
| Get the tag value with the given index. More...
const char * | gta_get_tag (const gta_taglist_t *restrict taglist, const char *restrict name)
| Get a tag value by its name. More...
gta_result_t | gta_set_tag (gta_taglist_t *restrict taglist, const char *restrict name, const char *restrict value)
| Set a tag. More...
gta_result_t | gta_unset_tag (gta_taglist_t *restrict taglist, const char *restrict name)
| Unset a tag. More...
void | gta_unset_all_tags (gta_taglist_t *restrict taglist)
| Unset all tags. More...
gta_result_t | gta_clone_taglist (gta_taglist_t *restrict dst_taglist, const gta_taglist_t *restrict src_taglist)
| Clone a tag list. More...
Read and Write Complete Arrays
These functions are intended to be used by applications that know that all the data will fit into memory.
gta_result_t | gta_read_data (const gta_header_t *restrict header, void *restrict data, gta_read_t read_fn, intptr_t userdata)
| Read the complete data. More...
gta_result_t | gta_read_data_from_stream (const gta_header_t *restrict header, void *restrict data, FILE *restrict f)
| Read the complete data from a stream. More...
gta_result_t | gta_read_data_from_fd (const gta_header_t *restrict header, void *restrict data, int fd)
| Read the complete data from a file descriptor. More...
gta_result_t | gta_skip_data (const gta_header_t *restrict header, gta_read_t read_fn, gta_seek_t seek_fn, intptr_t userdata)
| Skip the complete data. More...
gta_result_t | gta_skip_data_from_stream (const gta_header_t *restrict header, FILE *restrict f)
| Skip the complete data from a stream. More...
gta_result_t | gta_skip_data_from_fd (const gta_header_t *restrict header, int fd)
| Skip the complete data from a file descriptor. More...
gta_result_t | gta_write_data (const gta_header_t *restrict header, const void *restrict data, gta_write_t write_fn, intptr_t userdata)
| Write the complete data. More...
gta_result_t | gta_write_data_to_stream (const gta_header_t *restrict header, const void *restrict data, FILE *restrict f)
| Write the complete data to a stream. More...
gta_result_t | gta_write_data_to_fd (const gta_header_t *restrict header, const void *restrict data, int fd)
| Write the complete data to a file descriptor. More...
gta_result_t | gta_copy_data (const gta_header_t *restrict read_header, gta_read_t read_fn, intptr_t read_userdata, const gta_header_t *restrict write_header, gta_write_t write_fn, intptr_t write_userdata)
| Copy the complete data. More...
gta_result_t | gta_copy_data_stream (const gta_header_t *restrict read_header, FILE *restrict read_f, const gta_header_t *restrict write_header, FILE *restrict write_f)
| Copy the complete data between streams. More...
gta_result_t | gta_copy_data_fd (const gta_header_t *restrict read_header, int read_fd, const gta_header_t *restrict write_header, int write_fd)
| Copy the complete data between file descriptors. More...
In-Memory Data Access
void | gta_linear_index_to_indices (const gta_header_t *restrict header, uintmax_t index, uintmax_t *restrict indices)
| Transform a linear index to array indices. More...
uintmax_t | gta_indices_to_linear_index (const gta_header_t *restrict header, const uintmax_t *restrict indices)
| Transform array indices to a linear index. More...
const void * | gta_get_element_const (const gta_header_t *restrict header, const void *restrict data, const uintmax_t *restrict indices)
| Get the address of an array element (non-modifiable). More...
void * | gta_get_element (const gta_header_t *restrict header, void *restrict data, const uintmax_t *restrict indices)
| Get the address of an array element (modifiable). More...
const void * | gta_get_element_linear_const (const gta_header_t *restrict header, const void *restrict data, uintmax_t index)
| Get the address of an array element (non-modifiable). More...
void * | gta_get_element_linear (const gta_header_t *restrict header, void *restrict data, uintmax_t index)
| Get the address of an array element (modifiable). More...
const void * | gta_get_component_const (const gta_header_t *restrict header, const void *restrict element, uintmax_t i)
| Get the address of a component of an array element (non-modifiable). More...
void * | gta_get_component (const gta_header_t *restrict header, void *restrict element, uintmax_t i)
| Get the address of a component of an array element (modifiable). More...
Read and Write Array Elements
These functions are intended to be used for filtering a complete array on a per-element basis. They read or write a given number of elements, and it is expected that they are used repeatedly until all elements of an array have been read or written. Theses function work for all GTAs, with or without compression, an the input and output streams do not need to be seekable. Element-based input/output needs a state structure. This structure must be allocated with gta_create_io_state() before the first element is read or written, and freed with gta_destroy_io_state() after the last element was read or written, or after an error occured.
gta_result_t | gta_create_io_state (gta_io_state_t *restrict *restrict io_state)
| Create and initialize a new input/output state. More...
gta_result_t | gta_clone_io_state (gta_io_state_t *restrict dst_io_state, const gta_io_state_t *restrict src_io_state)
| Clone an input/output state. More...
void | gta_destroy_io_state (gta_io_state_t *restrict io_state)
| Destroy input/output state and free its resources. More...
gta_result_t | gta_read_elements (const gta_header_t *restrict header, gta_io_state_t *restrict io_state, uintmax_t n, void *restrict buf, gta_read_t read_fn, intptr_t userdata)
| Read array elements. More...
gta_result_t | gta_read_elements_from_stream (const gta_header_t *restrict header, gta_io_state_t *restrict io_state, uintmax_t n, void *restrict buf, FILE *restrict f)
| Read array elements. More...
gta_result_t | gta_read_elements_from_fd (const gta_header_t *restrict header, gta_io_state_t *restrict io_state, uintmax_t n, void *restrict buf, int fd)
| Read array elements. More...
gta_result_t | gta_write_elements (const gta_header_t *restrict header, gta_io_state_t *restrict io_state, uintmax_t n, const void *restrict buf, gta_write_t write_fn, intptr_t userdata)
| Write array elements. More...
gta_result_t | gta_write_elements_to_stream (const gta_header_t *restrict header, gta_io_state_t *restrict io_state, uintmax_t n, const void *restrict buf, FILE *restrict f)
| Write array elements. More...
gta_result_t | gta_write_elements_to_fd (const gta_header_t *restrict header, gta_io_state_t *restrict io_state, uintmax_t n, const void *restrict buf, int fd)
| Write array elements. More...
Read and Write Array Blocks
These functions can only be used if the data is not compression (see gta_get_compression()) and the input/output is seekable. They are suitable for applications that do not want to store the complete array data in memory. A block is given by the lowest and highest element coordinates in each dimension. For example, for a 2D array from which we want a rectangle of 20x10 elements starting at element (5,3), we would store the values (5,3) in lower_coordinates and (24, 12) in higher_coordinates.
gta_result_t | gta_read_block (const gta_header_t *restrict header, intmax_t data_offset, const uintmax_t *restrict lower_coordinates, const uintmax_t *restrict higher_coordinates, void *restrict block, gta_read_t read_fn, gta_seek_t seek_fn, intptr_t userdata)
| Read an array block. More...
gta_result_t | gta_read_block_from_stream (const gta_header_t *restrict header, intmax_t data_offset, const uintmax_t *restrict lower_coordinates, const uintmax_t *restrict higher_coordinates, void *restrict block, FILE *restrict f)
| Read an array block from a stream. More...
gta_result_t | gta_read_block_from_fd (const gta_header_t *restrict header, intmax_t data_offset, const uintmax_t *restrict lower_coordinates, const uintmax_t *restrict higher_coordinates, void *restrict block, int fd)
| Read an array block from a file descriptor. More...
gta_result_t | gta_write_block (const gta_header_t *restrict header, intmax_t data_offset, const uintmax_t *restrict lower_coordinates, const uintmax_t *restrict higher_coordinates, const void *restrict block, gta_write_t write_fn, gta_seek_t seek_fn, intptr_t userdata)
| Write an array block. More...
gta_result_t | gta_write_block_to_stream (const gta_header_t *restrict header, intmax_t data_offset, const uintmax_t *restrict lower_coordinates, const uintmax_t *restrict higher_coordinates, const void *restrict block, FILE *restrict f)
| Write an array block to a stream. More...
gta_result_t | gta_write_block_to_fd (const gta_header_t *restrict header, intmax_t data_offset, const uintmax_t *restrict lower_coordinates, const uintmax_t *restrict higher_coordinates, const void *restrict block, int fd)
| Write an array block to a file descriptor. More...

## Detailed Description

The libgta C interface.

This document describes the C language interface of libgta.

## Typedef Documentation

typedef struct gta_internal_taglist_struct gta_taglist_t

The GTA tag list type.

A tag consists of a name and a value. A tag list stores these name/value pairs.
Tag names are non-empty UTF-8 strings that must not contain '='.
Tag values are UTF-8 strings.
If you do not want to deal with conversions between the local character set and UTF-8, you must restrict names and values to ASCII.

typedef size_t(* gta_read_t)(intptr_t userdata, void *buffer, size_t size, int *error)

Custom input function.

You can specify your own input function to read from your own custom sources.
It must read the given number of bytes into the given buffer.
Its return value must be the number of bytes successfully read.
If an error occured, the error flag must be set to true (1). The function must set errno to indicate the type of error. If the error type is unknown, errno should be set to EIO.

typedef size_t(* gta_write_t)(intptr_t userdata, const void *buffer, size_t size, int *error)

Custom output function.

You can specify your own output function to write to your own custum destinations.
It must write the given number of bytes from the given buffer.
Its return value must be the number of bytes successfully written.
If an error occured, the error flag must be set to true (1). The function must set errno to indicate the type of error. If the error type is unknown, errno should be set to EIO.

typedef void(* gta_seek_t)(intptr_t userdata, intmax_t offset, int whence, int *error)

Custom seek function.

You can specify your own seek function to seek in your own custum media.
It must change its file position indicator as indicated by the parameters offset and whence, just like fseeko() and lseek() do. The parameter whence can be SEEK_SET or SEEK_CUR (SEEK_END is never used).
If an error occured, the error flag must be set to true (1). The function must set errno to indicate the type of error. If the error type is unknown, errno should be set to EIO.

typedef struct gta_internal_io_state_struct gta_io_state_t

State for element-based input/output.

See gta_read_elements() and gta_write_elements().

## Enumeration Type Documentation

enum gta_result_t

GTA result type.

The return value of most GTA functions is of this type, to indicate failures and their causes.

Enumerator
GTA_OK | Success / no error.
GTA_OVERFLOW | Size overflow.
GTA_UNSUPPORTED_DATA | Unsupported data. The input seems to require features that are not available in this version of the library.
GTA_UNEXPECTED_EOF | Unexpected end of file. The GTA library intended to read more data, but the input did not provide it.
GTA_INVALID_DATA | Invalid data. Some data was invalid. For example, an input file is not in GTA format, or decompression of the data failed.
GTA_SYSTEM_ERROR | System error. A system error occured. More information is available in errno. Examples: memory allocation failure (errno == ENOMEM), input/output errors (errno == EIO), no space left on device (errno == ENOSPC).

enum gta_type_t

GTA data types.

Data types supported by GTA.

All integer types contain the exact number of bits indicated by their name and use the common two's complement representation.
All floating point types contain the exact number of bits indicated by their name and conform to the binary representation defined by IEEE 754.
The complex types (GTA_CFLOAT*) consist of two floating point values with the number of bits indicated by the name, as defined above. The first value is the real part, the second value is the imaginary part. For example, GTA_CFLOAT32 consists of two GTA_FLOAT32 values.
The name GTA_BLOB can be used for data types that are not defined in this list. In this case, the size of the data type must be given, and the data type must be independent of endianness.

Enumerator
GTA_INT8 | int8_t
GTA_UINT8 | uint8_t
GTA_INT16 | int16_t
GTA_UINT16 | uint16_t
GTA_INT32 | int32_t
GTA_UINT32 | uint32_t
GTA_INT64 | int64_t
GTA_UINT64 | uint64_t
GTA_INT128 | int128_t (unavailable on many platforms)
GTA_UINT128 | uint128_t (unavailable on many platforms)
GTA_FLOAT32 | IEEE 754 single precision floating point (on many platforms: float)
GTA_FLOAT64 | IEEE 754 double precision floating point (on many platforms: double)
GTA_FLOAT128 | IEEE 754 quadrupel precision floating point (unavailable on many platforms, even if long double exists)
GTA_CFLOAT32 | complex (re,im) based on two GTA_FLOAT32
GTA_CFLOAT64 | complex (re,im) based on two GTA_FLOAT64
GTA_CFLOAT128 | complex (re,im) based on two GTA_FLOAT128
GTA_BLOB | Data blob; must be endianness-independent; user must specify the size.

enum gta_compression_t

GTA compression algorithms.

Compression algorithms used to compress the array.
Only uncompressed files are suitable for out-of-core data access; compressed files must be decompressed first.
GTA_ZLIB compression is fast and achieves a moderate compression ratio. GTA_BZIP2 compression is moderately fast and achieves a good compression ratio. GTA_XZ compression is slow for compression, moderately fast for decompression, and achieves good or very good compression rates.

Enumerator
GTA_NONE | No compression.
GTA_ZLIB | ZLIB compression with default level (fast, moderate compression rate)
GTA_ZLIB1 | ZLIB compression with level 1.
GTA_ZLIB2 | ZLIB compression with level 2.
GTA_ZLIB3 | ZLIB compression with level 3.
GTA_ZLIB4 | ZLIB compression with level 4.
GTA_ZLIB5 | ZLIB compression with level 5.
GTA_ZLIB6 | ZLIB compression with level 6.
GTA_ZLIB7 | ZLIB compression with level 7.
GTA_ZLIB8 | ZLIB compression with level 8.
GTA_ZLIB9 | ZLIB compression with level 9.
GTA_BZIP2 | BZIP2 compression (moderate speed, good compression rates)
GTA_XZ | XZ compression (low/moderate speed, good/very good compression rates)

## Function Documentation

const char* gta_version | ( | int *restrict | major,
|  | int *restrict | minor,
|  | int *restrict | patch
| ) |  |

Get the libgta version.

Parameters

  major | Buffer for the major version number, or NULL.
  minor | Buffer for the minor version number, or NULL.
  patch | Buffer for the patch version number, or NULL.

Returns
  The libgta version string.

This function returns the version string "MAJOR.MINOR.PATCH". If the pointers major, minor, patch are not NULL, the requested version number will be stored there.

gta_result_t gta_create_header | ( | gta_header_t *restrict *restrict | header | ) |

Create a new GTA header structure and initialize it.

Parameters

  header | The header.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Creates a new GTA header and initializes it. The GTA will initially be empty (zero element components, zero dimensions) and contain no tags. The compression method will be GTA_NONE.

gta_result_t gta_clone_header | ( | gta_header_t *restrict | dst_header,
|  | const gta_header_t *restrict | src_header
| ) |  |

Clone a GTA header structure.

Parameters

  dst_header | The destination header.
  src_header | The source header.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Clones src_header into dst_header.

void gta_destroy_header | ( | gta_header_t *restrict | header | ) |

Destroy a GTA header structure and free its resources.

Parameters

  header | The header.

Destroys a GTA header structure and fress all of its resources.

gta_result_t gta_read_header | ( | gta_header_t *restrict | header,
|  | gta_read_t | read_fn,
|  | intptr_t | userdata
| ) |  |

Read a GTA header.

Parameters

  header | The header.
  read_fn | The custom input function.
  userdata | A parameter to the custom input function.

Returns
  GTA_OK, GTA_OVERFLOW, GTA_INVALID_DATA, or GTA_SYSTEM_ERROR.

gta_result_t gta_read_header_from_stream | ( | gta_header_t *restrict | header,
|  | FILE *restrict | f
| ) |  |

Read a GTA header from a stream.

Parameters

  header | The header.
  f | The stream.

Returns
  GTA_OK, GTA_OVERFLOW, GTA_INVALID_DATA, or GTA_SYSTEM_ERROR.

Reads a GTA header from a stream.
The file position indicator will be positioned after the GTA header, on the first data byte.

gta_result_t gta_read_header_from_fd | ( | gta_header_t *restrict | header,
|  | int | fd
| ) |  |

Read a GTA header from a file descriptor.

Parameters

  header | The header.
  fd | The file descriptor.

Returns
  GTA_OK, GTA_OVERFLOW, GTA_INVALID_DATA, or GTA_SYSTEM_ERROR.

Reads a GTA header from a file descriptor.
The file position indicator will be positioned after the GTA header, on the first data byte.

gta_result_t gta_write_header | ( | const gta_header_t *restrict | header,
|  | gta_write_t | write_fn,
|  | intptr_t | userdata
| ) |  |

Write a GTA header.

Parameters

  header | The header.
  write_fn | The custom output function.
  userdata | A parameter to the custom output function.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

gta_result_t gta_write_header_to_stream | ( | const gta_header_t *restrict | header,
|  | FILE *restrict | f
| ) |  |

Write a GTA header to a stream.

Parameters

  header | The header.
  f | The stream.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

gta_result_t gta_write_header_to_fd | ( | const gta_header_t *restrict | header,
|  | int | fd
| ) |  |

Write a GTA header to a file descriptor.

Parameters

  header | The header.
  fd | The file descriptor.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

const gta_taglist_t* gta_get_global_taglist_const | ( | const gta_header_t *restrict | header | ) |

Get the global tag list (non-modifiable).

Parameters

  header | The header.

Returns
  The global tag list (non-modifiable).

gta_taglist_t* gta_get_global_taglist | ( | gta_header_t *restrict | header | ) |

Get the global tag list (modifiable).

Parameters

  header | The header.

Returns
  The global tag list (modifiable).

uintmax_t gta_get_element_size | ( | const gta_header_t *restrict | header | ) |

Return the size of an array element.

Parameters

  header | The header.

Returns
  The size of an array element, which is the sum of the component sizes.

uintmax_t gta_get_components | ( | const gta_header_t *restrict | header | ) |

Get the number of components.

Parameters

  header | The header.

Returns
  The number of components in an array element.

gta_type_t gta_get_component_type | ( | const gta_header_t *restrict | header,
|  | uintmax_t | i
| ) |  |

Get the type of a component.

Parameters

  header | The header.
  i | The component index.

Returns
  The type of the element component.

uintmax_t gta_get_component_size | ( | const gta_header_t *restrict | header,
|  | uintmax_t | i
| ) |  |

Get the size of a component.

Parameters

  header | The header.
  i | The component index.

Returns
  The size (in bytes) of the element component.

const gta_taglist_t* gta_get_component_taglist_const | ( | const gta_header_t *restrict | header,
|  | uintmax_t | i
| ) |  |

Get the tag list of a component (non-modifiable).

Parameters

  header | The header.
  i | The component index.

Returns
  The tag list of the element component (non-modifiable).

gta_taglist_t* gta_get_component_taglist | ( | gta_header_t *restrict | header,
|  | uintmax_t | i
| ) |  |

Get the tag list of a component (modifiable).

Parameters

  header | The header.
  i | The component index.

Returns
  The tag list of the element component (modifiable).

uintmax_t gta_get_dimensions | ( | const gta_header_t *restrict | header | ) |

Get the number of dimensions.

Parameters

  header | The header.

Returns
  The number of dimensions of the array data.

uintmax_t gta_get_dimension_size | ( | const gta_header_t *restrict | header,
|  | uintmax_t | i
| ) |  |

Get the size in a dimension.

Parameters

  header | The header.
  i | The dimension index.

Returns
  The size of the array in the given dimension.

const gta_taglist_t* gta_get_dimension_taglist_const | ( | const gta_header_t *restrict | header,
|  | uintmax_t | i
| ) |  |

Get the tag list of a dimension (non-modifiable).

Parameters

  header | The header.
  i | The dimension index.

Returns
  The tag list of the dimension (non-modifiable).

gta_taglist_t* gta_get_dimension_taglist | ( | gta_header_t *restrict | header,
|  | uintmax_t | i
| ) |  |

Get the tag list of a dimension (modifiable).

Parameters

  header | The header.
  i | The dimension index.

Returns
  The tag list of the dimension (modifiable).

uintmax_t gta_get_elements | ( | const gta_header_t *restrict | header | ) |

Get the total number of elements in the array.

Parameters

  header | The header.

Returns
  The total number of elements in the array.

uintmax_t gta_get_data_size | ( | const gta_header_t *restrict | header | ) |

Get the total size of the array data.

Parameters

  header | The header.

Returns
  The total size (in bytes) of the array data.

gta_compression_t gta_get_compression | ( | const gta_header_t *restrict | header | ) |

Get the compression.

Parameters

  header | The header.

Returns
  The compression type.

Gets the compression type for the header and data.
See gta_compression_t for more information on compression types.
Compressed data is always stored in chunks, while uncompressed data is never stored in chunks.

void gta_set_compression | ( | gta_header_t *restrict | header,
|  | gta_compression_t | compression
| ) |  |

Set the compression.

Parameters

  header | The header.
  compression | The compression type.

Sets the compression type for writing the header and data.
See gta_compression_t for more information on compression types.

gta_result_t gta_set_components | ( | gta_header_t *restrict | header,
|  | uintmax_t | n,
|  | const gta_type_t *restrict | types,
|  | const uintmax_t *restrict | sizes
| ) |  |

Set the components of an array element.

Parameters

  header | The header.
  n | The number of components.
  types | The types of the n components.
  sizes | NULL, or the sizes of the components that have type GTA_BLOB.

Returns
  GTA_OK, GTA_OVERFLOW, GTA_UNSUPPORTED_DATA, or GTA_SYSTEM_ERROR.

Set the components of the array elements.
The sizes parameter can be NULL if no components have the type GTA_BLOB. Otherwise, it must point to a list that contains the sizes of these components (and only these components). For example, if there are five components, but only two have the type GTA_BLOB, then the sizes list must contain two size values.
All components will initially have an empty tag list.

gta_result_t gta_set_dimensions | ( | gta_header_t *restrict | header,
|  | uintmax_t | n,
|  | const uintmax_t *restrict | sizes
| ) |  |

Set the dimensions.

Parameters

  header | The header.
  n | The number of dimensions.
  sizes | The array sizes in each of the dimensions.

Returns
  GTA_OK, GTA_OVERFLOW, GTA_INVALID_DATA, or GTA_SYSTEM_ERROR.

Sets the array dimensions.
All dimensions will initially have an empty tag list.

uintmax_t gta_get_tags | ( | const gta_taglist_t *restrict | taglist | ) |

Get the number of tags in a tag list.

Parameters

  taglist | The tag list.

Returns
  The number of tags in the list.

const char* gta_get_tag_name | ( | const gta_taglist_t *restrict | taglist,
|  | uintmax_t | i
| ) |  |

Get the tag name with the given index.

Parameters

  taglist | The tag list.
  i | The tag index.

Returns
  The name of the tag.

const char* gta_get_tag_value | ( | const gta_taglist_t *restrict | taglist,
|  | uintmax_t | i
| ) |  |

Get the tag value with the given index.

Parameters

  taglist | The tag list.
  i | The tag index.

Returns
  The value of the tag.

const char* gta_get_tag | ( | const gta_taglist_t *restrict | taglist,
|  | const char *restrict | name
| ) |  |

Get a tag value by its name.

Parameters

  taglist | The tag list.
  name | The tag name.

Returns
  The tag value, or NULL if the tag name is not found.

gta_result_t gta_set_tag | ( | gta_taglist_t *restrict | taglist,
|  | const char *restrict | name,
|  | const char *restrict | value
| ) |  |

Set a tag.

Parameters

  taglist | The tag list.
  name | The name.
  value | The value.

Returns
  GTA_OK, GTA_INVALID_DATA, GTA_OVERFLOW, or GTA_SYSTEM_ERROR.

Sets the given tag, possibly overwriting an existing tag with the same name. The name and value must be valid UTF-8 strings without control characters. Additionally, the name must not contain the equal sign and must not be empty.

gta_result_t gta_unset_tag | ( | gta_taglist_t *restrict | taglist,
|  | const char *restrict | name
| ) |  |

Unset a tag.

Parameters

  taglist | The tag list.
  name | The tag name.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Removes the tag with the given name, if it exists.

void gta_unset_all_tags | ( | gta_taglist_t *restrict | taglist | ) |

Unset all tags.

Parameters

  taglist | The tag list.

Removes all tags from the tag list.

gta_result_t gta_clone_taglist | ( | gta_taglist_t *restrict | dst_taglist,
|  | const gta_taglist_t *restrict | src_taglist
| ) |  |

Clone a tag list.

Parameters

  dst_taglist | The destination tag list.
  src_taglist | The source tag list.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Copies src_taglist to dst_taglist.

gta_result_t gta_read_data | ( | const gta_header_t *restrict | header,
|  | void *restrict | data,
|  | gta_read_t | read_fn,
|  | intptr_t | userdata
| ) |  |

Read the complete data.

Parameters

  header | The header.
  data | The data buffer.
  read_fn | The custom input function.
  userdata | A parameter to the custom input function.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the complete data into the given buffer. The buffer must be large enough.

gta_result_t gta_read_data_from_stream | ( | const gta_header_t *restrict | header,
|  | void *restrict | data,
|  | FILE *restrict | f
| ) |  |

Read the complete data from a stream.

Parameters

  header | The header.
  data | The data buffer.
  f | The stream.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the complete data into the given buffer. The buffer must be large enough.

gta_result_t gta_read_data_from_fd | ( | const gta_header_t *restrict | header,
|  | void *restrict | data,
|  | int | fd
| ) |  |

Read the complete data from a file descriptor.

Parameters

  header | The header.
  data | The data buffer.
  fd | The file descriptor.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the complete data into the given buffer. The buffer must be large enough.

gta_result_t gta_skip_data | ( | const gta_header_t *restrict | header,
|  | gta_read_t | read_fn,
|  | gta_seek_t | seek_fn,
|  | intptr_t | userdata
| ) |  |

Skip the complete data.

Parameters

  header | The header.
  read_fn | The custom input function.
  seek_fn | The custom seek function, or NULL for non-seekable input.
  userdata | A parameter to the custom input and seek functions.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Skips the complete data, so that the next GTA header can be read.

gta_result_t gta_skip_data_from_stream | ( | const gta_header_t *restrict | header,
|  | FILE *restrict | f
| ) |  |

Skip the complete data from a stream.

Parameters

  header | The header.
  f | The stream.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Skips the complete data, so that the next GTA header can be read.

gta_result_t gta_skip_data_from_fd | ( | const gta_header_t *restrict | header,
|  | int | fd
| ) |  |

Skip the complete data from a file descriptor.

Parameters

  header | The header.
  fd | The file descriptor.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Skips the complete data, so that the next GTA header can be read.

gta_result_t gta_write_data | ( | const gta_header_t *restrict | header,
|  | const void *restrict | data,
|  | gta_write_t | write_fn,
|  | intptr_t | userdata
| ) |  |

Write the complete data.

Parameters

  header | The header.
  data | The data buffer.
  write_fn | The custom output function.
  userdata | A parameter to the custom output function.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Writes the complete data.

gta_result_t gta_write_data_to_stream | ( | const gta_header_t *restrict | header,
|  | const void *restrict | data,
|  | FILE *restrict | f
| ) |  |

Write the complete data to a stream.

Parameters

  header | The header.
  data | The data buffer.
  f | The stream.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Writes the complete data.

gta_result_t gta_write_data_to_fd | ( | const gta_header_t *restrict | header,
|  | const void *restrict | data,
|  | int | fd
| ) |  |

Write the complete data to a file descriptor.

Parameters

  header | The header.
  data | The data buffer.
  fd | The file descriptor.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Writes the complete data.

gta_result_t gta_copy_data | ( | const gta_header_t *restrict | read_header,
|  | gta_read_t | read_fn,
|  | intptr_t | read_userdata,
|  | const gta_header_t *restrict | write_header,
|  | gta_write_t | write_fn,
|  | intptr_t | write_userdata
| ) |  |

Copy the complete data.

Parameters

  read_header | The input header.
  read_fn | The custom input function.
  read_userdata | A parameter to the custom input function.
  write_header | The ourput header.
  write_fn | The custom output function.
  write_userdata | A parameter to the custom output function.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Copies the complete data. The data encoding is altered as necessary (endianness correction, compression). Note that the data encoding may change even if read_header and write_header point to the same header!

gta_result_t gta_copy_data_stream | ( | const gta_header_t *restrict | read_header,
|  | FILE *restrict | read_f,
|  | const gta_header_t *restrict | write_header,
|  | FILE *restrict | write_f
| ) |  |

Copy the complete data between streams.

Parameters

  read_header | The input header.
  read_f | The input stream.
  write_header | The output header.
  write_f | The output stream.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Copies the complete data. The data encoding is altered as necessary (endianness correction, compression). Note that the data encoding may change even if read_header and write_header point to the same header!

gta_result_t gta_copy_data_fd | ( | const gta_header_t *restrict | read_header,
|  | int | read_fd,
|  | const gta_header_t *restrict | write_header,
|  | int | write_fd
| ) |  |

Copy the complete data between file descriptors.

Parameters

  read_header | The input header.
  read_fd | The input file descriptor.
  write_header | The output header.
  write_fd | The output file descriptor.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Copies the complete data. The data encoding is altered as necessary (endianness correction, compression). Note that the data encoding may change even if read_header and write_header point to the same header!

void gta_linear_index_to_indices | ( | const gta_header_t *restrict | header,
|  | uintmax_t | index,
|  | uintmax_t *restrict | indices
| ) |  |

Transform a linear index to array indices.

Parameters

  header | The header.
  index | The linear index.
  indices | The array indices.

uintmax_t gta_indices_to_linear_index | ( | const gta_header_t *restrict | header,
|  | const uintmax_t *restrict | indices
| ) |  |

Transform array indices to a linear index.

Parameters

  header | The header.
  indices | The array indices.

Returns
  The linear index.

const void* gta_get_element_const | ( | const gta_header_t *restrict | header,
|  | const void *restrict | data,
|  | const uintmax_t *restrict | indices
| ) |  |

Get the address of an array element (non-modifiable).

Parameters

  header | The header.
  data | The data.
  indices | The indices for each dimension of the array.

Returns
  A pointer to the element.

void* gta_get_element | ( | const gta_header_t *restrict | header,
|  | void *restrict | data,
|  | const uintmax_t *restrict | indices
| ) |  |

Get the address of an array element (modifiable).

Parameters

  header | The header.
  data | The data.
  indices | The indices for each dimension of the array.

Returns
  A pointer to the element.

const void* gta_get_element_linear_const | ( | const gta_header_t *restrict | header,
|  | const void *restrict | data,
|  | uintmax_t | index
| ) |  |

Get the address of an array element (non-modifiable).

Parameters

  header | The header.
  data | The data.
  index | The linear index of the element.

Returns
  A pointer to the element.

void* gta_get_element_linear | ( | const gta_header_t *restrict | header,
|  | void *restrict | data,
|  | uintmax_t | index
| ) |  |

Get the address of an array element (modifiable).

Parameters

  header | The header.
  data | The data.
  index | The linear index of the element.

Returns
  A pointer to the element.

const void* gta_get_component_const | ( | const gta_header_t *restrict | header,
|  | const void *restrict | element,
|  | uintmax_t | i
| ) |  |

Get the address of a component of an array element (non-modifiable).

Parameters

  header | The header.
  element | The element.
  i | The component index.

Returns
  A pointer to the component.

void* gta_get_component | ( | const gta_header_t *restrict | header,
|  | void *restrict | element,
|  | uintmax_t | i
| ) |  |

Get the address of a component of an array element (modifiable).

Parameters

  header | The header.
  element | The element.
  i | The component index.

Returns
  A pointer to the component.

gta_result_t gta_create_io_state | ( | gta_io_state_t *restrict *restrict | io_state | ) |

Create and initialize a new input/output state.

Parameters

  io_state | The input/output state.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Creates and initializes a state structure for element-based input/output.

gta_result_t gta_clone_io_state | ( | gta_io_state_t *restrict | dst_io_state,
|  | const gta_io_state_t *restrict | src_io_state
| ) |  |

Clone an input/output state.

Parameters

  dst_io_state | The destination state.
  src_io_state | The source state.

Returns
  GTA_OK or GTA_SYSTEM_ERROR.

Clones src_io_state into dst_io_state.

void gta_destroy_io_state | ( | gta_io_state_t *restrict | io_state | ) |

Destroy input/output state and free its resources.

Parameters

  io_state | The input/output state.

Destroys a state structure for element-based input/output and frees its resources.

gta_result_t gta_read_elements | ( | const gta_header_t *restrict | header,
|  | gta_io_state_t *restrict | io_state,
|  | uintmax_t | n,
|  | void *restrict | buf,
|  | gta_read_t | read_fn,
|  | intptr_t | userdata
| ) |  |

Read array elements.

Parameters

  header | The header.
  io_state | The input/output state.
  n | The number of elements to read.
  buf | The buffer for the elements.
  read_fn | The custom input function.
  userdata | A parameter to the custom input function.

Returns
  GTA_OK, GTA_OVERFLOW, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the given number of elements into the given buffer, which must be large enough.

gta_result_t gta_read_elements_from_stream | ( | const gta_header_t *restrict | header,
|  | gta_io_state_t *restrict | io_state,
|  | uintmax_t | n,
|  | void *restrict | buf,
|  | FILE *restrict | f
| ) |  |

Read array elements.

Parameters

  header | The header.
  io_state | The input/output state.
  n | The number of elements to read.
  buf | The buffer for the elements.
  f | The stream.

Returns
  GTA_OK, GTA_INVALID_DATA, GTA_OVERFLOW, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the given number of elements into the given buffer, which must be large enough.

gta_result_t gta_read_elements_from_fd | ( | const gta_header_t *restrict | header,
|  | gta_io_state_t *restrict | io_state,
|  | uintmax_t | n,
|  | void *restrict | buf,
|  | int | fd
| ) |  |

Read array elements.

Parameters

  header | The header.
  io_state | The input/output state.
  n | The number of elements to read.
  buf | The buffer for the elements.
  fd | The file descriptor.

Returns
  GTA_OK, GTA_INVALID_DATA, GTA_OVERFLOW, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the given number of elements into the given buffer, which must be large enough.

gta_result_t gta_write_elements | ( | const gta_header_t *restrict | header,
|  | gta_io_state_t *restrict | io_state,
|  | uintmax_t | n,
|  | const void *restrict | buf,
|  | gta_write_t | write_fn,
|  | intptr_t | userdata
| ) |  |

Write array elements.

Parameters

  header | The header.
  io_state | The input/output state.
  n | The number of elements to write.
  buf | The buffer for the elements.
  write_fn | The custom output function.
  userdata | A parameter to the custom output function.

Returns
  GTA_OK, GTA_INVALID_DATA, GTA_OVERFLOW, or GTA_SYSTEM_ERROR.

Writes the given number of elements from the given buffer.

gta_result_t gta_write_elements_to_stream | ( | const gta_header_t *restrict | header,
|  | gta_io_state_t *restrict | io_state,
|  | uintmax_t | n,
|  | const void *restrict | buf,
|  | FILE *restrict | f
| ) |  |

Write array elements.

Parameters

  header | The header.
  io_state | The input/output state.
  n | The number of elements to write.
  buf | The buffer for the elements.
  f | The stream.

Returns
  GTA_OK, GTA_INVALID_DATA, GTA_OVERFLOW, or GTA_SYSTEM_ERROR.

Writes the given number of elements from the given buffer.

gta_result_t gta_write_elements_to_fd | ( | const gta_header_t *restrict | header,
|  | gta_io_state_t *restrict | io_state,
|  | uintmax_t | n,
|  | const void *restrict | buf,
|  | int | fd
| ) |  |

Write array elements.

Parameters

  header | The header.
  io_state | The input/output state.
  n | The number of elements to write.
  buf | The buffer for the elements.
  fd | The file descriptor.

Returns
  GTA_OK, GTA_INVALID_DATA, GTA_OVERFLOW, or GTA_SYSTEM_ERROR.

Writes the given number of elements from the given buffer.

gta_result_t gta_read_block | ( | const gta_header_t *restrict | header,
|  | intmax_t | data_offset,
|  | const uintmax_t *restrict | lower_coordinates,
|  | const uintmax_t *restrict | higher_coordinates,
|  | void *restrict | block,
|  | gta_read_t | read_fn,
|  | gta_seek_t | seek_fn,
|  | intptr_t | userdata
| ) |  |

Read an array block.

Parameters

  header | The header.
  data_offset | Offset of the first data byte.
  lower_coordinates | Coordinates of the lower corner element of the block.
  higher_coordinates | Coordinates of the higher corner element of the block.
  block | The block buffer.
  read_fn | The custom input function.
  seek_fn | The custom seek function.
  userdata | A parameter to the custom input function.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA (if the data is compressed), GTA_OVERFLOW, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the given array block and copies it to the given block buffer, which must be large enough.
This function modifies the file position indicator of the input.

gta_result_t gta_read_block_from_stream | ( | const gta_header_t *restrict | header,
|  | intmax_t | data_offset,
|  | const uintmax_t *restrict | lower_coordinates,
|  | const uintmax_t *restrict | higher_coordinates,
|  | void *restrict | block,
|  | FILE *restrict | f
| ) |  |

Read an array block from a stream.

Parameters

  header | The header.
  data_offset | Offset of the first data byte.
  lower_coordinates | Coordinates of the lower corner element of the block.
  higher_coordinates | Coordinates of the higher corner element of the block.
  block | The block buffer.
  f | The stream.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA (if the data is compressed), GTA_OVERFLOW, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the given array block and copies it to the given block buffer, which must be large enough.
This function modifies the file position indicator of the input.

gta_result_t gta_read_block_from_fd | ( | const gta_header_t *restrict | header,
|  | intmax_t | data_offset,
|  | const uintmax_t *restrict | lower_coordinates,
|  | const uintmax_t *restrict | higher_coordinates,
|  | void *restrict | block,
|  | int | fd
| ) |  |

Read an array block from a file descriptor.

Parameters

  header | The header.
  data_offset | Offset of the first data byte.
  lower_coordinates | Coordinates of the lower corner element of the block.
  higher_coordinates | Coordinates of the higher corner element of the block.
  block | The block buffer.
  fd | The file descriptor.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA (if the data is compressed), GTA_OVERFLOW, GTA_UNEXPECTED_EOF, or GTA_SYSTEM_ERROR.

Reads the given array block and copies it to the given block buffer, which must be large enough.
This function modifies the file position indicator of the input.

gta_result_t gta_write_block | ( | const gta_header_t *restrict | header,
|  | intmax_t | data_offset,
|  | const uintmax_t *restrict | lower_coordinates,
|  | const uintmax_t *restrict | higher_coordinates,
|  | const void *restrict | block,
|  | gta_write_t | write_fn,
|  | gta_seek_t | seek_fn,
|  | intptr_t | userdata
| ) |  |

Write an array block.

Parameters

  header | The header.
  data_offset | Offset of the first data byte.
  lower_coordinates | Coordinates of the lower corner element of the block.
  higher_coordinates | Coordinates of the higher corner element of the block.
  block | The block buffer.
  write_fn | The custom output function.
  seek_fn | The custom seek function.
  userdata | A parameter to the custom output function.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA (if the data is compressed), GTA_OVERFLOW, or GTA_SYSTEM_ERROR.

This function modifies the file position indicator of the output.

gta_result_t gta_write_block_to_stream | ( | const gta_header_t *restrict | header,
|  | intmax_t | data_offset,
|  | const uintmax_t *restrict | lower_coordinates,
|  | const uintmax_t *restrict | higher_coordinates,
|  | const void *restrict | block,
|  | FILE *restrict | f
| ) |  |

Write an array block to a stream.

Parameters

  header | The header.
  data_offset | Offset of the first data byte.
  lower_coordinates | Coordinates of the lower corner element of the block.
  higher_coordinates | Coordinates of the higher corner element of the block.
  block | The block buffer.
  f | The stream.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA (if the data is compressed), GTA_OVERFLOW, or GTA_SYSTEM_ERROR.

This function modifies the file position indicator of the output.

gta_result_t gta_write_block_to_fd | ( | const gta_header_t *restrict | header,
|  | intmax_t | data_offset,
|  | const uintmax_t *restrict | lower_coordinates,
|  | const uintmax_t *restrict | higher_coordinates,
|  | const void *restrict | block,
|  | int | fd
| ) |  |

Write an array block to a file descriptor.

Parameters

  header | The header.
  data_offset | Offset of the first data byte.
  lower_coordinates | Coordinates of the lower corner element of the block.
  higher_coordinates | Coordinates of the higher corner element of the block.
  block | The block buffer.
  fd | The file descriptor.

Returns
  GTA_OK, GTA_UNSUPPORTED_DATA (if the data is compressed), GTA_OVERFLOW, GTA_SYSTEM_ERROR.

This function modifies the file position indicator of the output.