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.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation