Basic header file for eventio data format. More...

#include "initial.h"
#include "warning.h"

Include dependency graph for io_basic.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	_struct_IO_BUFFER
	The IO_BUFFER structure contains all data needed the manage the stuff. More...

struct	_struct_IO_ITEM_HEADER
	An IO_ITEM_HEADER is to access header info for an I/O block and as a handle to the I/O buffer. More...

struct	ev_reg_entry

Macros
#define	COPY_BYTES(_target, _source, _num) memcpy(_target,_source,_num)

#define	COPY_BYTES_SWAB(_target, _source, _num) swab(_source,_target,_num)

#define	EVENTIO_EXTENSION_FLAG 2

#define	EVENTIO_USER_FLAG 1

#define	get_byte(p) (--(p)->r_remaining>=0? *(p)->data++ : -1)

#define	get_bytes(p, k) (((p)->r_remaining -= k) >=0 ? (*(p)->data+=k)-k : -1)

#define	get_vector_of_int16 get_vector_of_short

#define	get_vector_of_uint8 get_vector_of_byte

#define	HAVE_EVENTIO_EXTENDED_LENGTH 1

#define	HAVE_EVENTIO_HEADER_LENGTH 1

#define	HAVE_EVENTIO_USER_FLAG 1

#define	IO_BUFFER_INITIAL_LENGTH 32768L

#define	IO_BUFFER_LENGTH_INCREMENT 65536L

#define	IO_BUFFER_MAXIMUM_LENGTH 3000000L

#define	MAX_IO_ITEM_LEVEL 20

#define	put_byte(_c, _p)

#define	put_vector_of_int16 put_vector_of_short

#define	put_vector_of_uint8 put_vector_of_byte

Typedefs
typedef unsigned char	BYTE

typedef struct ev_reg_entry (	EVREGSEARCH) (unsigned long t)

typedef struct _struct_IO_BUFFER	IO_BUFFER

typedef struct _struct_IO_ITEM_HEADER	IO_ITEM_HEADER

typedef int(*	IO_USER_FUNCTION) (unsigned char *, long, int)

Functions
IO_BUFFER *	allocate_io_buffer (size_t buflen)
	Dynamic allocation of an I/O buffer. More...

int	append_io_block_as_item (IO_BUFFER iobuf, IO_ITEM_HEADER item_header, BYTE *_buffer, long length)
	Append data from one I/O block into another one. More...

int	copy_item_to_io_block (IO_BUFFER iobuf2, IO_BUFFER iobuf, const IO_ITEM_HEADER *item_header)
	Copy a sub-item to another I/O buffer as top-level item. More...

double	dbl_from_sfloat (const uint16_t *snum)
	Convert from the internal representation of an OpenGL 16-bit floating point number back to normal floating point representation.

void	dbl_to_sfloat (double dnum, uint16_t *snum)
	Convert a double to the internal representation of a 16 bit floating point number as specified in the OpenGL 3.1 standard, also called a half-float. More...

const char *	eventio_registered_description (unsigned long type)
	Extract the optional description for a given type number, if available.

const char *	eventio_registered_typename (unsigned long type)
	This functions using the stored function pointer are now in the core eventio code. More...

int	extend_io_buffer (IO_BUFFER *iobuf, unsigned next_byte, long increment)
	Extend the dynamically allocated I/O buffer. More...

struct ev_reg_entry *	find_ev_reg (unsigned long t)
	This optionally available function is implemented externally.

int	find_io_block (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Find the beginning of the next I/O data block in the input. More...

void	fltp_to_sfloat (const float fnum, uint16_t snum)
	Convert a float to the internal representation of a 16 bit floating point number as specified in the OpenGL 3.1 standard, also called a half-float. More...

void	free_io_buffer (IO_BUFFER *iobuf)
	Free an I/O buffer that has been allocated at run-time. More...

uintmax_t	get_count (IO_BUFFER *iobuf)
	Get an unsigned integer of unspecified length from an I/O buffer. More...

uint16_t	get_count16 (IO_BUFFER *iobuf)
	Get an unsigned 16 bit integer of unspecified length from an I/O buffer. More...

uint32_t	get_count32 (IO_BUFFER *iobuf)
	Get an unsigned 32 bit integer of unspecified length from an I/O buffer. More...

double	get_double (IO_BUFFER *iobuf)
	Get a double from the I/O buffer. More...

int32_t	get_int32 (IO_BUFFER *iobuf)
	Read a four byte integer from an I/O buffer. More...

int	get_item_begin (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Begin reading an item. More...

int	get_item_end (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	End reading an item. More...

long	get_long (IO_BUFFER *iobuf)
	Get 4-byte integer from I/O buffer and return as a long int. More...

int	get_long_string (char s, int nmax, IO_BUFFER iobuf)
	Get a long string of ASCII characters from an I/O buffer. More...

double	get_real (IO_BUFFER *iobuf)
	Get a floating point number (as written by put_real) from the I/O buffer. More...

intmax_t	get_scount (IO_BUFFER *iobuf)
	Get a signed integer of unspecified length from an I/O buffer. More...

int16_t	get_scount16 (IO_BUFFER *iobuf)
	Shortened version of get_scount for up to 16 bits of data.

int32_t	get_scount32 (IO_BUFFER *iobuf)
	Shortened version of get_scount for up to 32 bits of data.

double	get_sfloat (IO_BUFFER *iobuf)
	Get a 16-bit float from an I/O buffer and expand it to a double.

int	get_short (IO_BUFFER *iobuf)
	Get a two-byte integer from an I/O buffer. More...

int	get_string (char s, int nmax, IO_BUFFER iobuf)
	Get a string of ASCII characters from an I/O buffer. More...

uint16_t	get_uint16 (IO_BUFFER *iobuf)
	Get one unsigned short from an I/O buffer. More...

uint32_t	get_uint32 (IO_BUFFER *iobuf)
	Get a four-byte unsigned integer from an I/O buffer. More...

int	get_var_string (char s, int nmax, IO_BUFFER iobuf)
	Get a string of ASCII characters from an I/O buffer. More...

void	get_vector_of_byte (BYTE vec, int num, IO_BUFFER iobuf)
	Get a vector of bytes from an I/O buffer. More...

void	get_vector_of_double (double vec, int num, IO_BUFFER iobuf)
	Get a vector of floating point numbers as 'doubles' from an I/O buffer.

void	get_vector_of_float (float vec, int num, IO_BUFFER iobuf)
	Get a vector of floating point numbers as 'floats' from an I/O buffer.

void	get_vector_of_int (int vec, int num, IO_BUFFER iobuf)
	Get a vector of (small) integers from I/O buffer.

void	get_vector_of_int32 (int32_t vec, int num, IO_BUFFER iobuf)
	Get a vector of 32 bit integers from I/O buffer.

void	get_vector_of_int_scount (int vec, int num, IO_BUFFER iobuf)
	Get an array of ints as scount32 data from an I/O buffer.

void	get_vector_of_long (long vec, int num, IO_BUFFER iobuf)
	Get a vector of 4-byte integers as long int from I/O buffer.

void	get_vector_of_real (double vec, int num, IO_BUFFER iobuf)
	Get a vector of floating point numbers as 'doubles' from an I/O buffer.

void	get_vector_of_short (short vec, int num, IO_BUFFER iobuf)
	Get a vector of short integers from I/O buffer.

void	get_vector_of_uint16 (uint16_t uval, int num, IO_BUFFER iobuf)
	Get a vector of unsigned shorts from an I/O buffer. More...

void	get_vector_of_uint16_scount_differential (uint16_t vec, int num, IO_BUFFER iobuf)
	Get an array of uint16_t as differential scount data from an I/O buffer. More...

void	get_vector_of_uint32 (uint32_t vec, int num, IO_BUFFER iobuf)
	Get a vector of 32 bit integers from I/O buffer.

void	get_vector_of_uint32_scount_differential (uint32_t vec, int num, IO_BUFFER iobuf)
	Get an array of uint32_t as differential scount data from an I/O buffer. More...

int	list_io_blocks (IO_BUFFER *iobuf, int verbosity)
	Show the top-level item of an I/O block on standard output. More...

int	list_sub_items (IO_BUFFER iobuf, IO_ITEM_HEADER item_header, int maxlevel, int verbosity)
	Display the contents of sub-items on standard output. More...

long	next_subitem_ident (IO_BUFFER *iobuf)
	Reads the header of a sub-item and return the identifier of it. More...

long	next_subitem_length (IO_BUFFER *iobuf)
	Reads the header of a sub-item and return the length of it. More...

int	next_subitem_type (IO_BUFFER *iobuf)
	Reads the header of a sub-item and return the type of it. More...

void	put_count (uintmax_t num, IO_BUFFER *iobuf)
	Put an unsigned integer of unspecified length to an I/O buffer. More...

void	put_count16 (uint16_t num, IO_BUFFER *iobuf)
	Shortened version of put_count for up to 16 bits of data. More...

void	put_count32 (uint32_t num, IO_BUFFER *iobuf)
	Shortened version of put_count for up to 32 bits of data. More...

void	put_double (double d, IO_BUFFER *iobuf)
	Put a 'double' as such into an I/O buffer. More...

void	put_int32 (int32_t num, IO_BUFFER *iobuf)
	Write a four-byte integer to an I/O buffer. More...

int	put_item_begin (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Begin putting another (sub-) item into the output buffer. More...

int	put_item_begin_with_flags (IO_BUFFER iobuf, IO_ITEM_HEADER item_header, int user_flag, int extended)
	Begin putting another (sub-) item into the output buffer. More...

int	put_item_end (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	End of putting an item into the output buffer. More...

void	put_long (long num, IO_BUFFER *iobuf)
	Put a four-byte integer taken from a 'long' into an I/O buffer. More...

int	put_long_string (const char s, IO_BUFFER iobuf)
	Put a long string of ASCII characters into an I/O buffer. More...

void	put_real (double d, IO_BUFFER *iobuf)
	Put a 4-byte floating point number into an I/O buffer. More...

void	put_scount (intmax_t num, IO_BUFFER *iobuf)
	Put a signed integer of unspecified length to an I/O buffer. More...

void	put_scount16 (int16_t num, IO_BUFFER *iobuf)
	Shorter version of put_scount for up to 16 bytes of data. More...

void	put_scount32 (int32_t num, IO_BUFFER *iobuf)
	Shorter version of put_scount for up to 32 bytes of data. More...

void	put_sfloat (double dnum, IO_BUFFER *iobuf)
	Put a 16-bit float to an I/O buffer.

void	put_short (int num, IO_BUFFER *iobuf)
	Put a two-byte integer on an I/O buffer. More...

int	put_string (const char s, IO_BUFFER iobuf)
	Put a string of ASCII characters into an I/O buffer. More...

void	put_uint32 (uint32_t num, IO_BUFFER *iobuf)
	Put a four-byte integer into an I/O buffer. More...

int	put_var_string (const char s, IO_BUFFER iobuf)
	Put a string of ASCII characters into an I/O buffer. More...

void	put_vector_of_byte (const BYTE vec, int num, IO_BUFFER iobuf)
	Put a vector of bytes into an I/O buffer. More...

void	put_vector_of_double (const double vec, int num, IO_BUFFER iobuf)
	Put a vector of doubles into an I/O buffer. More...

void	put_vector_of_float (const float vec, int num, IO_BUFFER iobuf)
	Put a vector of floats as IEEE 'float' numbers into an I/O buffer.

void	put_vector_of_int (const int vec, int num, IO_BUFFER iobuf)
	Put a vector of integers (range -32768 to 32767) into I/O buffer. More...

void	put_vector_of_int32 (const int32_t vec, int num, IO_BUFFER iobuf)
	Put a vector of 32 bit integers into I/O buffer.

void	put_vector_of_int_scount (const int vec, int num, IO_BUFFER iobuf)
	Put an array of ints as scount32 data into an I/O buffer.

void	put_vector_of_long (const long vec, int num, IO_BUFFER iobuf)
	Put a vector of long int as 4-byte integers into an I/O buffer.

void	put_vector_of_real (const double vec, int num, IO_BUFFER iobuf)
	Put a vector of doubles as IEEE 'float' numbers into an I/O buffer.

void	put_vector_of_short (const short vec, int num, IO_BUFFER iobuf)
	Put a vector of 2-byte integers on an I/O buffer. More...

void	put_vector_of_uint16 (const uint16_t uval, int num, IO_BUFFER iobuf)
	Put a vector of unsigned shorts into an I/O buffer. More...

void	put_vector_of_uint16_scount_differential (uint16_t vec, int num, IO_BUFFER iobuf)
	Put an array of uint16_t as differential scount data into an I/O buffer.

void	put_vector_of_uint32 (const uint32_t vec, int num, IO_BUFFER iobuf)
	Put a vector of 32 bit integers into I/O buffer.

void	put_vector_of_uint32_scount_differential (uint32_t vec, int num, IO_BUFFER iobuf)
	Put an array of uint16_t as differential scount data into an I/O buffer.

int	read_io_block (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Read the data of an I/O block from the input. More...

int	remove_item (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Remove an item from an I/O buffer. More...

int	reset_io_block (IO_BUFFER *iobuf)
	Reset an I/O block to its empty status. More...

int	rewind_item (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Go back to the beginning of an item. More...

int	search_sub_item (IO_BUFFER iobuf, IO_ITEM_HEADER item_header, IO_ITEM_HEADER *sub_item_header)
	Search for an item of a specified type. More...

void	set_eventio_registry_hook (EVREGSEARCH fptr)
	This function should be used to set the find_ev_reg_ptr function pointer. More...

int	skip_io_block (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Skip the data of an I/O block from the input. More...

int	skip_subitem (IO_BUFFER *iobuf)
	When the next sub-item is of no interest, it can be skipped. More...

int	unget_item (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Go back to the beginning of an item being read. More...

int	unput_item (IO_BUFFER iobuf, IO_ITEM_HEADER item_header)
	Undo writing at the present level. More...

int	write_io_block (IO_BUFFER *iobuf)
	Write an I/O block to the block's output. More...

Detailed Description

Author: Konrad Bernloehr

Date

1991 to 2014

CVS $Date: 2019/02/20 14:50:15 $

Version

CVS $Revision: 1.27 $

Header file for structures and function prototypes for the basic eventio functions. Not to be used to declare any project-specific structures and prototypes! Declare any such things in 'io_project.h' or in separate header files.

Macro Definition Documentation

◆ put_byte

#define put_byte	(	_c,
		_p
	)

Value:

(--(_p)->w_remaining>=0 ? \
   (*(_p)->data++ = (BYTE)(_c)) : \
   (BYTE)extend_io_buffer(_p,(unsigned)(_c), \
     (IO_BUFFER_LENGTH_INCREMENT)))

Function Documentation

◆ allocate_io_buffer()

IO_BUFFER* allocate_io_buffer ( size_t buflen )

Dynamic allocation of an I/O buffer. The actual length of the buffer is passed as an argument. The buffer descriptor is initialized.

Parameters

buflen The length of the actual buffer in bytes. A safety margin of 4 bytes is added.

Returns: Pointer to I/O buffer or NULL if allocation failed.

◆ append_io_block_as_item()

int append_io_block_as_item	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header,
		BYTE *	buffer,
		long	length
	)

Append the data from a complete i/o block as an additional subitem to another i/o block.

Parameters

iobuf	The target I/O buffer descriptor, must be 'opened' for 'writing', i.e. 'put_item_begin()' must be called.
item_header	Item header of the item in iobuf which is currently being filled.
buffer	Data to be filled in. Must be all data from an I/O buffer, including the 4 signature bytes.
length	The length of buffer in bytes.

Returns: 0 (o.k.), -1 (error), -2 (not enough memory etc.)

◆ copy_item_to_io_block()

int copy_item_to_io_block	(	IO_BUFFER *	iobuf2,
		IO_BUFFER *	iobuf,
		const IO_ITEM_HEADER *	item_header
	)

Parameters

iobuf2	Target I/O buffer descriptor.
iobuf	Source I/O buffer descriptor.
item_header	Header for the item in iobuf that should be copied to iobuf2.

Returns: 0 (o.k.), -1 (error), -2 (not enough memory etc.)

◆ dbl_to_sfloat()

void dbl_to_sfloat	(	double	dnum,
		uint16_t *	snum
	)

This is done via an intermediate float representation.

Parameters

dnum	The number to be converted.
snum	Pointer for the resulting representation, as stored in an unsigned 16-bit integer (1 bit sign, 5 bits exponent, 10 bits mantissa).

References fltp_to_sfloat().

◆ eventio_registered_typename()

const char* eventio_registered_typename ( unsigned long type )

This functions using the stored function pointer are now in the core eventio code.

References find_ev_reg(), ev_reg_entry::name, and ev_reg_entry::type.

◆ extend_io_buffer()

int extend_io_buffer	(	IO_BUFFER *	iobuf,
		unsigned	next_byte,
		long	increment
	)

Extend the dynamically allocated I/O buffer and if an item has been started and the argument 'next_byte' is smaller than 256 that argument will be appended as the next byte to the buffer.

Parameters

iobuf	The I/O buffer descriptor
next_byte	The value of the next byte or >= 256
increment	The no. of bytes by which to increase the buffer beyond the current point. If there is remaining space for writing, the buffer is extended by less than 'increment'.

Returns: next_byte (modulo 256) if successful, -1 for failure

◆ find_io_block()

int find_io_block	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

Read byte for byte from the input file specified for the I/O buffer and look for the sync-tag (magic number in little-endian or big-endian byte order. As long as the input is properly synchronized this sync-tag should be found in the first four bytes. Otherwise, input data is skipped until the next sync-tag is found. After the sync tag 10 more bytes (item type, version number, and length field) are read. The type of I/O (raw, buffered, or user-defined) depends on the settings of the I/O block.

Parameters

iobuf	The I/O buffer descriptor.
item_header	An item header structure to be filled in.

Returns: 0 (O.k.), -1 (error), or -2 (end-of-file)

◆ fltp_to_sfloat()

void fltp_to_sfloat	(	const float *	fnum,
		uint16_t *	snum
	)

Both input and output come as pointers to avoid extra conversions.

Parameters

fnum	Pointer to the number to be converted.
snum	Pointer for the resulting representation, as stored in an unsigned 16-bit integer (1 bit sign, 5 bits exponent, 10 bits mantissa).

Here is the caller graph for this function:

◆ free_io_buffer()

void free_io_buffer ( IO_BUFFER * iobuf )

Free an I/O buffer that has been allocated at run-time (e.g. by a call to allocate_io_buf()).

Parameters

iobuf The buffer descriptor to be de-allocated.

Returns: (none)

◆ get_count()

uintmax_t get_count ( IO_BUFFER * iobuf )

Get an unsigned integer of unspecified length from an I/O buffer where it is encoded in a way similar to the UTF-8 character encoding. Even though the scheme in principle allows for arbitrary length data, the current implementation is limited for data of up to 64 bits. On systems with uintmax_t shorter than 64 bits, the result could be clipped unnoticed. It could also be clipped unnoticed in the application calling this function.

◆ get_count16()

uint16_t get_count16 ( IO_BUFFER * iobuf )

Get an unsigned 16 bit integer of unspecified length from an I/O buffer where it is encoded in a way similar to the UTF-8 character encoding. This is a shorter version of get_count, for efficiency reasons.

◆ get_count32()

uint32_t get_count32 ( IO_BUFFER * iobuf )

Get an unsigned 32 bit integer of unspecified length from an I/O buffer where it is encoded in a way similar to the UTF-8 character encoding. This is a shorter version of get_count, for efficiency reasons.

◆ get_double()

double get_double ( IO_BUFFER * iobuf )

Get a double-precision floating point number (as written by put_double) from the I/O buffer. The current implementation is only for machines using IEEE format internally.

Parameters

iobuf – The I/O buffer descriptor;

Returns: The floating point number.

◆ get_int32()

int32_t get_int32 ( IO_BUFFER * iobuf )

Read a four byte integer with little-endian or big-endian byte order from memory. Should be machine independent (see put_short()).

◆ get_item_begin()

int get_item_begin	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

Reads the header of an item.

Reads the header of an item. If a specific item type is requested but a different type is found and the length of that item is known, the item is skipped.

Parameters

iobuf	The input buffer descriptor.
item_header	The item header descriptor.

Returns: 0 (O.k.), -1 (error), -2 (end-of-buffer) or -3 (wrong item type).

◆ get_item_end()

int get_item_end	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

Finish reading an item. The pointer in the I/O buffer is at the end of the item after this call, if succesful.

Parameters

iobuf	I/O buffer descriptor.
item_header	Header of item last read.

Returns: 0 (ok), -1 (error)

◆ get_long()

long get_long ( IO_BUFFER * iobuf )

Read a four byte integer with little-endian or big-endian byte order from memory. Should be machine independent (see put_short()).

◆ get_long_string()

int get_long_string	(	char *	s,
		int	nmax,
		IO_BUFFER *	iobuf
	)

Get a long string of ASCII characters with leading count of bytes from an I/O buffer. Strings can be up to 2^31-1 bytes long (assuming you have so much memory).

To work properly with strings longer than 32k, a machine with sizeof(int) > 2 is actually required.

NOTE: the nmax count does account also for the trailing zero byte which will be appended.

◆ get_real()

double get_real ( IO_BUFFER * iobuf )

Parameters

iobuf The I/O buffer descriptor;

Returns: The floating point number.

◆ get_scount()

intmax_t get_scount ( IO_BUFFER * iobuf )

Get a signed integer of unspecified length from an I/O buffer where it is encoded in a way similar to the UTF-8 character encoding. Even though the scheme in principle allows for arbitrary length data, the current implementation is limited for data of up to 64 bits. On systems with intmax_t shorter than 64 bits, the result could be clipped unnoticed.

◆ get_short()

int get_short ( IO_BUFFER * iobuf )

Get a two-byte integer with least significant byte first. Should be machine-independent (see put_short()).

◆ get_string()

int get_string	(	char *	s,
		int	nmax,
		IO_BUFFER *	iobuf
	)

Get a string of ASCII characters with leading count of bytes (stored with 16 bits) from an I/O buffer.

NOTE: the nmax count does now account for the trailing zero byte which will be appended. This was different in an earlier version of this function where one additional byte had to be available for the trailing zero byte.

◆ get_uint16()

uint16_t get_uint16 ( IO_BUFFER * iobuf )

Get one unsigned short (16-bit unsigned int) from an I/O buffer. The function should be used where sign propagation is of concern.

Parameters

iobuf The output buffer descriptor.

Returns: The value obtained from the I/O buffer.

◆ get_uint32()

uint32_t get_uint32 ( IO_BUFFER * iobuf )

Read a four byte integer with little-endian or big-endian byte order from memory. Should be machine independent (see put_short()).

◆ get_var_string()

int get_var_string	(	char *	s,
		int	nmax,
		IO_BUFFER *	iobuf
	)

Get a string of ASCII characters with leading count of bytes (stored with variable length) from an I/O buffer.

NOTE: the nmax count does also account for the trailing zero byte which will be appended.

◆ get_vector_of_byte()

void get_vector_of_byte	(	BYTE *	vec,
		int	num,
		IO_BUFFER *	iobuf
	)

Parameters

vec	– Byte data vector.
num	– Number of bytes to get.
iobuf	– I/O buffer descriptor.

Returns: (none)

◆ get_vector_of_uint16()

void get_vector_of_uint16	(	uint16_t *	uval,
		int	num,
		IO_BUFFER *	iobuf
	)

Get a vector of unsigned shorts from an I/O buffer with least significant byte first. The values are in the range 0 to 65535. The function should be used where sign propagation is of concern.

Parameters

uval	The vector where the values should be loaded.
num	The number of elements to load.
iobuf	The output buffer descriptor.

Returns: (none)

◆ get_vector_of_uint16_scount_differential()

void get_vector_of_uint16_scount_differential	(	uint16_t *	vec,
		int	num,
		IO_BUFFER *	iobuf
	)

For optimization reasons it is assumed that the data has been written in a consistent way and is complete. Only minimal tests for remaining data in the buffer are made - while the slower generic version would check for each extracted number.

◆ get_vector_of_uint32_scount_differential()

void get_vector_of_uint32_scount_differential	(	uint32_t *	vec,
		int	num,
		IO_BUFFER *	iobuf
	)

For optimization reasons it is assumed that the data has been written in a consistent way and is complete. Only minimal tests for remaining data in the buffer are made - while the slower generic version would check for each extracted number.

◆ list_io_blocks()

int list_io_blocks	(	IO_BUFFER *	iobuf,
		int	verbosity
	)

List type, version, ident, and length) of the top item of all I/O blocks in input file onto standard output.

Parameters

iobuf	The I/O buffer descriptor.
verbosity	Try showing type name at >=1, description at >=2.

Returns: 0 (O.k.), -1 (error)

◆ list_sub_items()

int list_sub_items	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header,
		int	maxlevel,
		int	verbosity
	)

Display the contents (item types, versions, idents and lengths) of sub-items on standard output.

Parameters

iobuf	I/O buffer descriptor.
item_header	Header of the item from which to show contents.
maxlevel	The maximum nesting depth to show contents (counted from the top-level item on).
verbosity	Try showing type name at >=1, description at >=2.

Returns: 0 (ok), -1 (error)

◆ next_subitem_ident()

long next_subitem_ident ( IO_BUFFER * iobuf )

Parameters

iobuf The input buffer descriptor.

Returns: >= 0 (O.k.), -1 (error), -2 (end-of-buffer).

◆ next_subitem_length()

long next_subitem_length ( IO_BUFFER * iobuf )

Parameters

iobuf The input buffer descriptor.

Returns: >= 0 (O.k.), -1 (error), -2 (end-of-buffer).

◆ next_subitem_type()

int next_subitem_type ( IO_BUFFER * iobuf )

Parameters

iobuf The input buffer descriptor.

Returns: >= 0 (O.k.), -1 (error), -2 (end-of-buffer).

◆ put_count()

void put_count	(	uintmax_t	n,
		IO_BUFFER *	iobuf
	)

Put an unsigned integer of unspecified length in a way similar to the UTF-8 character encoding to an I/O buffer. The byte order resulting in the buffer is independent of the host byte order or the byte order in action for the I/O buffer, starting with as many leading bits in the first byte as extension bytes needed after the first byte. While the scheme in principle allows for values of arbitrary length, the implementation is limited to 64 bits.

Parameters

n	The number to be saved. Even on systems with 64-bit integers, this must not exceed 2**32-1 with the current implementation.
iobuf	The output buffer descriptor.

Returns: (none)

◆ put_count16()

void put_count16	(	uint16_t	n,
		IO_BUFFER *	iobuf
	)

Returns: (none)

◆ put_count32()

void put_count32	(	uint32_t	n,
		IO_BUFFER *	iobuf
	)

Returns: (none)

◆ put_double()

void put_double	(	double	dnum,
		IO_BUFFER *	iobuf
	)

Put a 'double' (floating point) number in a specific but (almost) machine-independent format into an I/O buffer. This implementation requires the machine to use IEEE double-precision floating point numbers. Only byte order conversion is done.

Parameters

dnum	The number to be put into the I/O buffer.
iobuf	The I/O buffer descriptor.

Returns: (none)

◆ put_int32()

void put_int32	(	int32_t	num,
		IO_BUFFER *	iobuf
	)

Write a four-byte integer with least significant bytes first. Should be machine independent (see put_short()).

◆ put_item_begin()

int put_item_begin	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

When putting another item to the output buffer which may be either a top item or a sub-item, put_item_begin() initializes the buffer (for a top item) and puts the item header on the buffer.

Parameters

iobuf	The output buffer descriptor.
item_header	The item header descriptor.

Returns: 0 (O.k.) or -1 (error)

◆ put_item_begin_with_flags()

int put_item_begin_with_flags	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header,
		int	user_flag,
		int	extended
	)

This is identical to put_item_begin() except for taking a third and fourth argument, a user flag to be included in the header data, and a flag indicating that the header extension should be used. In put_item_begin() these flags are forced to 0 (false) for backwards compatibility.

Parameters

iobuf	The output buffer descriptor.
item_header	The item header descriptor.
flag	The user flag (0 or 1).

Returns: 0 (O.k.) or -1 (error)

◆ put_item_end()

int put_item_end	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

When finished with putting an item to the output buffer, check for errors and do housekeeping.

Parameters

iobuf	The output buffer descriptor.
item_header	The item header descriptor.

Returns: 0 (O.k.) or -1 (error)

◆ put_long()

void put_long	(	long	num,
		IO_BUFFER *	iobuf
	)

Write a four-byte integer with least significant bytes first. Should be machine independent (see put_short()).

◆ put_long_string()

int put_long_string	(	const char *	s,
		IO_BUFFER *	iobuf
	)

Put a long string of ASCII characters with leading count of bytes into an I/O buffer. This is expected to work properly for strings of more than 32k only on machines with sizeof(int) > 2 because 16-bit machines may not be able to represent lengths of long strings (as obtained with strlen).

Parameters

s	The null-terminated ASCII string.
iobuf	The I/O buffer descriptor.

Returns: Length of string

◆ put_real()

void put_real	(	double	dnum,
		IO_BUFFER *	iobuf
	)

Put a 'double' (floating point) number in a specific but (almost) machine-independent format into an I/O buffer. Not the full precision of a 'double' is saved but a 32 bit IEEE floating point number is written (with the same byte ordering as long integers). On machines with other floating point format than IEEE the input number is converted to a IEEE number first. An optimized (machine- specific) version should compute the output data by shift and add operations rather than by log(), divide, and multiply operations on such non-IEEE-format machines (implemented for VAX only).

Parameters

dnum	The number to be put into the I/O buffer.
iobuf	The I/O buffer descriptor.

Returns: (none)

◆ put_scount()

void put_scount	(	intmax_t	n,
		IO_BUFFER *	iobuf
	)

Put a signed integer of unspecified length in a way similar to the UTF-8 character encoding to an I/O buffer. The byte order resulting in the buffer is independent of the host byte order or the byte order in action for the I/O buffer, starting with as many leading bits in the first byte as extension bytes needed after the first byte. While the scheme in principle allows for values of arbitrary length, the implementation is limited to 32 bits. To allow an efficient representation of negative numbers, the sign bit is stored in the least significant bit. Portability of data across machines with different intmax_t sizes and the need to represent also the most negative number (-(2^31), -(2^63), or -(2^127), depending on CPU type and compiler) is achieved by putting the number's modulus minus 1 into the higher bits.

Parameters

n	The number to be saved. It can be in the range from -(2^63) to 2^63-1 on systems with 64 bit integers (intrinsic or through the compiler) and from -(2^31) to 2^31-1 on pure 32 bit systems.
iobuf	The output buffer descriptor.

Returns: (none)

◆ put_scount16()

void put_scount16	(	int16_t	n,
		IO_BUFFER *	iobuf
	)

Apart from efficiency, the data can be read with identical results through get_scount16 or get_scount.

Returns: (none)

◆ put_scount32()

void put_scount32	(	int32_t	n,
		IO_BUFFER *	iobuf
	)

Apart from efficiency, the data can be read with identical results through get_scount32 or get_scount.

Returns: (none)

◆ put_short()

void put_short	(	int	num,
		IO_BUFFER *	iobuf
	)

Put a two-byte integer on an I/O buffer with least significant byte first. Should be machine independent as long as 'short' and 'unsigned short' are 16-bit integers, the two's complement is used for negative numbers, and the '>>' operator does a logical shift with unsigned short. Although the 'num' argument is a 4-byte integer on most machines, the value shoud be in the range -32768 to 32767.

Parameters

num	The number to be saved. Should fit into a short integer and will be truncated otherwise.
iobuf	The output buffer descriptor.

Returns: (none)

◆ put_string()

int put_string	(	const char *	s,
		IO_BUFFER *	iobuf
	)

Put a string of ASCII characters with leading count of bytes (stored with 16 bits) into an I/O buffer.

Parameters

s	The null-terminated ASCII string.
iobuf	The I/O buffer descriptor.

Returns: Length of string

◆ put_uint32()

void put_uint32	(	uint32_t	num,
		IO_BUFFER *	iobuf
	)

Write a four-byte integer with least significant bytes first. Should be machine independent (see put_short()).

◆ put_var_string()

int put_var_string	(	const char *	s,
		IO_BUFFER *	iobuf
	)

Put a string of ASCII characters with leading count of bytes (stored with variable length) into an I/O buffer. Note that storing strings of 32k or more length will not work on systems with sizeof(int)==2.

Parameters

s	The null-terminated ASCII string.
iobuf	The I/O buffer descriptor.

Returns: Length of string

◆ put_vector_of_byte()

void put_vector_of_byte	(	const BYTE *	vec,
		int	num,
		IO_BUFFER *	iobuf
	)

Parameters

vec	Byte data vector.
num	Number of bytes to be put.
iobuf	I/O buffer descriptor.

Returns: (none)

◆ put_vector_of_double()

void put_vector_of_double	(	const double *	dvec,
		int	num,
		IO_BUFFER *	iobuf
	)

Put a vector of 'double' floating point numbers as IEEE 'double' numbers into an I/O buffer.

◆ put_vector_of_int()

void put_vector_of_int	(	const int *	vec,
		int	num,
		IO_BUFFER *	iobuf
	)

Put a vector of integers (with actual values in the range -32768 to 32767) into an I/O buffer. This may be relaced by a more efficient but machine-dependent version later.

◆ put_vector_of_short()

void put_vector_of_short	(	const short *	vec,
		int	num,
		IO_BUFFER *	iobuf
	)

Put a vector of 2-byte integers on an I/O buffer. This may be relaced by a more efficient but machine-dependent version later. May be called by a number of elements equal to 0. In this case, nothing is done.

◆ put_vector_of_uint16()

void put_vector_of_uint16	(	const uint16_t *	uval,
		int	num,
		IO_BUFFER *	iobuf
	)

Put a vector of unsigned shorts into an I/O buffer with least significant byte first. The values are in the range 0 to 65535. The function should be used where sign propagation is of concern.

Parameters

uval	The vector of values to be saved.
num	The number of elements to save.
iobuf	The output buffer descriptor.

Returns: (none)

◆ read_io_block()

int read_io_block	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

This function is called for reading data after an I/O data block has been found (with find_io_block) on input. The type of I/O (raw, buffered, or user-defined) depends on the settings of the I/O block.

Parameters

iobuf	The I/O buffer descriptor.
item_header	The item header descriptor.

Returns: 0 (O.k.), -1 (error), -2 (end-of-file), -3 (block skipped because it is too large)

◆ remove_item()

int remove_item	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

If writing an item has already started and then some condition was found to remove the item again, this is the function for it. The item to be removed should be the last one written, since anything following it will be forgotten too.

Parameters

iobuf	I/O buffer descriptor.
item_header	Header of item to be removed.

Returns: 0 (ok), -1 (error)

◆ reset_io_block()

int reset_io_block ( IO_BUFFER * iobuf )

Parameters

iobuf The I/O buffer descriptor.

Returns: 0 (O.k.), -1 (error)

◆ rewind_item()

int rewind_item	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

When reading from an I/O buffer, go back to the beginning of the data area of an item. This is typically used when searching for different types of sub-blocks but processing should not depend on the relative order of them.

Parameters

iobuf	I/O buffer descriptor.
item_header	Header of item last read.

Returns: 0 (ok), -1 (error)

◆ search_sub_item()

int search_sub_item	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header,
		IO_ITEM_HEADER *	sub_item_header
	)

Search for an item of a specified type, starting at the current position in the I/O buffer. After successful action the buffer data pointer points to the beginning of the header of the first item of that type. If no such item is found, it points right after the end of the item of the next higher level.

Parameters

iobuf	The I/O buffer descriptor.
item_header	The header of the item within which we search.
sub_item_header	To be filled with what we found.

Returns: 0 (O.k., sub-item was found), -1 (error), -2 (no such sub-item), -3 (cannot skip sub-items),

◆ set_eventio_registry_hook()

void set_eventio_registry_hook ( EVREGSEARCH fptr )

◆ skip_io_block()

int skip_io_block	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

Skip the data of an I/O block from the input (after the block's header was read). This is the alternative to read_io_block() after having found an I/O block with find_io_block but realizing that this is a type of block you don't know how to read or simply not interested in. The type of I/O (raw, buffered, or user-defined) depends on the settings of the I/O block.

Parameters

iobuf	The I/O buffer descriptor.
item_header	The item header descriptor.

Returns: 0 (O.k.), -1 (error) or -2 (end-of-file)

◆ skip_subitem()

int skip_subitem ( IO_BUFFER * iobuf )

Parameters

iobuf I/O buffer descriptor.

Returns: 0 (ok), -1 (error)

◆ unget_item()

int unget_item	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

When reading from an I/O buffer, go back to the beginning of an item (more precisely: its header) currently being read.

Parameters

iobuf	I/O buffer descriptor.
item_header	Header of item last read.

Returns: 0 (ok), -1 (error)

◆ unput_item()

int unput_item	(	IO_BUFFER *	iobuf,
		IO_ITEM_HEADER *	item_header
	)

When writing to an I/O buffer, revert anything yet written at the present level. If the buffer was extended, the last length is kept.

Parameters

iobuf	I/O buffer descriptor.
item_header	Header of item last read.

Returns: 0 (ok), -1 (error)

◆ write_io_block()

int write_io_block ( IO_BUFFER * iobuf )

The complete I/O block is written to the output destination, which can be raw I/O (through write), buffered I/O (through fwrite) or user-defined I/O (through a user funtion). All items must have been closed before.

Parameters

iobuf The I/O buffer descriptor.

Returns: 0 (O.k.), -1 (error), -2 (item has no data)

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ put_byte

Function Documentation

◆ allocate_io_buffer()

◆ append_io_block_as_item()

◆ copy_item_to_io_block()

◆ dbl_to_sfloat()

◆ eventio_registered_typename()

◆ extend_io_buffer()

◆ find_io_block()

◆ fltp_to_sfloat()

◆ free_io_buffer()

◆ get_count()

◆ get_count16()

◆ get_count32()

◆ get_double()

◆ get_int32()

◆ get_item_begin()

◆ get_item_end()

◆ get_long()

◆ get_long_string()

◆ get_real()

◆ get_scount()

◆ get_short()

◆ get_string()

◆ get_uint16()

◆ get_uint32()

◆ get_var_string()

◆ get_vector_of_byte()

◆ get_vector_of_uint16()

◆ get_vector_of_uint16_scount_differential()

◆ get_vector_of_uint32_scount_differential()

◆ list_io_blocks()

◆ list_sub_items()

◆ next_subitem_ident()

◆ next_subitem_length()

◆ next_subitem_type()

◆ put_count()

◆ put_count16()

◆ put_count32()

◆ put_double()

◆ put_int32()

◆ put_item_begin()

◆ put_item_begin_with_flags()

◆ put_item_end()

◆ put_long()

◆ put_long_string()

◆ put_real()

◆ put_scount()

◆ put_scount16()

◆ put_scount32()

◆ put_short()

◆ put_string()

◆ put_uint32()

◆ put_var_string()

◆ put_vector_of_byte()

◆ put_vector_of_double()

◆ put_vector_of_int()

◆ put_vector_of_short()

◆ put_vector_of_uint16()

◆ read_io_block()

◆ remove_item()

◆ reset_io_block()

◆ rewind_item()

◆ search_sub_item()

◆ set_eventio_registry_hook()

◆ skip_io_block()

◆ skip_subitem()

◆ unget_item()

◆ unput_item()

◆ write_io_block()