Detailed Description

Provides ESIO's C-based public API following the library's usage concepts.

All methods in this header invoke ESIO's error handling mechanisms on failure unless otherwise indicated.

Typedefs
typedef struct esio_handle_s *	esio_handle
	An opaque type following ESIO's handle concept.

Functions
Initializing and finalizing a state handle
See handles for the associated semantics.
esio_handle	esio_handle_initialize (MPI_Comm comm)
	Initialize a handle against the given MPI communicator.

int	esio_handle_comm_size (const esio_handle h, int *size)
	Retrieve the size of the MPI communicator over which the handle collectively operates.

int	esio_handle_comm_rank (const esio_handle h, int *rank)
	Retrieve the rank of the local MPI process as seen by the MPI communicator over which the handle collectively operates.

int	esio_handle_finalize (esio_handle h)
	Finalize a handle.

Opening and closing files
See file concepts for more details.
int	esio_file_create (esio_handle h, const char *file, int overwrite)
	Create a new file or overwrite an existing one.

int	esio_file_open (esio_handle h, const char *file, int readwrite)
	Open an existing file.

int	esio_file_clone (esio_handle h, const char srcfile, const char dstfile, int overwrite)
	Create and open a new file by cloning the contents of an existing file.

char *	esio_file_path (const esio_handle h)
	Get the canonical path to the currently open file.

int	esio_file_flush (esio_handle h)
	Flush buffers associated with any currently open file.

int	esio_file_close (esio_handle h)
	Close any currently open file.

int	esio_file_close_restart (esio_handle h, const char *restart_template, int retain_count)
	Close the currently open file and rename it to match the path given in `restart_template`.

Manipulating string-valued attributes
int	esio_string_set (const esio_handle h, const char location, const char name, const char *value)
	Set a string-valued attribute.

char *	esio_string_get (const esio_handle h, const char location, const char name)
	Get a string-valued attribute.

Manipulating scalar-valued attributes
See attribute concepts for more details. Additionally, the C++-only functions `esio_attribute_write()` and `esio_attribute_read()` provide overloaded, type-safe versions of these methods.
int	esio_attribute_write_double (const esio_handle h, const char location, const char name, const double *value)
	Write a scalar-valued `double` attribute.

int	esio_attribute_write_float (const esio_handle h, const char location, const char name, const float *value)
	Write a scalar-valued `float` attribute.

int	esio_attribute_write_int (const esio_handle h, const char location, const char name, const int *value)
	Write an scalar-valued `int` attribute.

int	esio_attribute_read_double (const esio_handle h, const char location, const char name, double *value)
	Read a scalar-valued `double` attribute.

int	esio_attribute_read_float (const esio_handle h, const char location, const char name, float *value)
	Read a scalar-valued `float` attribute.

int	esio_attribute_read_int (const esio_handle h, const char location, const char name, int *value)
	Read a scalar-valued `int` attribute.

Manipulating vector-valued attributes
See attributes concepts for more details. Additionally, the C++-only functions `esio_attribute_writev()` and `esio_attribute_readv()` provide overloaded, type-safe versions of these methods.
int	esio_attribute_writev_double (const esio_handle h, const char location, const char name, const double *value, int ncomponents)
	Write a vector-valued `double` attribute.

int	esio_attribute_writev_float (const esio_handle h, const char location, const char name, const float *value, int ncomponents)
	Write a vector-valued `float` attribute.

int	esio_attribute_writev_int (const esio_handle h, const char location, const char name, const int *value, int ncomponents)
	Write a vector-valued `int` attribute.

int	esio_attribute_readv_double (const esio_handle h, const char location, const char name, double *value, int ncomponents)
	Read a vector-valued `double` attribute.

int	esio_attribute_readv_float (const esio_handle h, const char location, const char name, float *value, int ncomponents)
	Read a vector-valued `float` attribute.

int	esio_attribute_readv_int (const esio_handle h, const char location, const char name, int *value, int ncomponents)
	Read a vector-valued `int` attribute.

int	esio_attribute_sizev (const esio_handle h, const char location, const char name, int *ncomponents)
	Query the number of components in a numeric attribute.

Manipulating decompositions for line, plane, and field operations.
int	esio_line_establish (esio_handle h, int aglobal, int astart, int alocal)
	Establish the parallel decomposition to use for subsequent line operations.

int	esio_plane_establish (esio_handle h, int bglobal, int bstart, int blocal, int aglobal, int astart, int alocal)
	Establish the parallel decomposition to use for subsequent plane operations.

int	esio_field_establish (esio_handle h, int cglobal, int cstart, int clocal, int bglobal, int bstart, int blocal, int aglobal, int astart, int alocal)
	Establish the parallel decomposition to use for subsequent field operations.

int	esio_line_established (esio_handle h, int aglobal, int astart, int *alocal)
	Retrieve any parallel decomposition previously established for line operations.

int	esio_plane_established (esio_handle h, int bglobal, int bstart, int blocal, int aglobal, int astart, int alocal)
	Retrieve any parallel decomposition previously established for plane operations.

int	esio_field_established (esio_handle h, int cglobal, int cstart, int clocal, int bglobal, int bstart, int blocal, int aglobal, int astart, int *alocal)
	Retrieve any parallel decomposition previously established for field operations.

Manipulating distributed, one-dimensional, scalar-valued data
See line concepts for more details. Additionally, the C++-only functions `esio_line_write()` and `esio_line_read()` provide overloaded, type-safe versions of these methods.
int	esio_line_write_double (const esio_handle h, const char name, const double line, int astride, const char *comment)
	Write a scalar-valued `double` line.

int	esio_line_write_float (const esio_handle h, const char name, const float line, int astride, const char *comment)
	Write a scalar-valued `float` line.

int	esio_line_write_int (const esio_handle h, const char name, const int line, int astride, const char *comment)
	Write a scalar-valued `int` line.

int	esio_line_read_double (const esio_handle h, const char name, double line, int astride)
	Read a scalar-valued `double` line.

int	esio_line_read_float (const esio_handle h, const char name, float line, int astride)
	Read a scalar-valued `float` line.

int	esio_line_read_int (const esio_handle h, const char name, int line, int astride)
	Read a scalar-valued `int` line.

int	esio_line_size (const esio_handle h, const char name, int aglobal)
	Query the global number of scalars within a line.

Manipulating distributed, one-dimensional, vector-valued data
See line concepts for more details. Additionally, the C++-only functions `esio_line_writev()` and `esio_line_readv()` provide overloaded, type-safe versions of these methods.
int	esio_line_writev_double (const esio_handle h, const char name, const double line, int astride, int ncomponents, const char *comment)
	Write a vector-valued `double` line.

int	esio_line_writev_float (const esio_handle h, const char name, const float line, int astride, int ncomponents, const char *comment)
	Write a vector-valued `float` line.

int	esio_line_writev_int (const esio_handle h, const char name, const int line, int astride, int ncomponents, const char *comment)
	Write a vector-valued `int` line.

int	esio_line_readv_double (const esio_handle h, const char name, double line, int astride, int ncomponents)
	Read a vector-valued `double` line.

int	esio_line_readv_float (const esio_handle h, const char name, float line, int astride, int ncomponents)
	Read a vector-valued `float` line.

int	esio_line_readv_int (const esio_handle h, const char name, int line, int astride, int ncomponents)
	Read a vector-valued `int` line.

int	esio_line_sizev (const esio_handle h, const char name, int aglobal, int *ncomponents)
	Query the global number of vectors and components within a line.

Manipulating distributed, two-dimensional, scalar-valued data
See plane concepts for more details. Additionally, the C++-only functions `esio_plane_write()` and `esio_plane_read()` provide overloaded, type-safe versions of these methods.
int	esio_plane_write_double (const esio_handle h, const char name, const double plane, int bstride, int astride, const char *comment)
	Write a scalar-valued `double` plane.

int	esio_plane_write_float (const esio_handle h, const char name, const float plane, int bstride, int astride, const char *comment)
	Write a scalar-valued `float` plane.

int	esio_plane_write_int (const esio_handle h, const char name, const int plane, int bstride, int astride, const char *comment)
	Write a scalar-valued `int` plane.

int	esio_plane_read_double (const esio_handle h, const char name, double plane, int bstride, int astride)
	Read a scalar-valued `double` plane.

int	esio_plane_read_float (const esio_handle h, const char name, float plane, int bstride, int astride)
	Read a scalar-valued `float` plane.

int	esio_plane_read_int (const esio_handle h, const char name, int plane, int bstride, int astride)
	Read a scalar-valued `int` plane.

int	esio_plane_size (const esio_handle h, const char name, int bglobal, int *aglobal)
	Query the global number of scalars within a plane.

Manipulating distributed, two-dimensional, vector-valued data
See plane concepts for more details. Additionally, the C++-only functions `esio_plane_writev()` and `esio_plane_readv()` provide overloaded, type-safe versions of these methods.
int	esio_plane_writev_double (const esio_handle h, const char name, const double plane, int bstride, int astride, int ncomponents, const char *comment)
	Write a vector-valued `double` plane.

int	esio_plane_writev_float (const esio_handle h, const char name, const float plane, int bstride, int astride, int ncomponents, const char *comment)
	Write a vector-valued `float` plane.

int	esio_plane_writev_int (const esio_handle h, const char name, const int plane, int bstride, int astride, int ncomponents, const char *comment)
	Write a vector-valued `int` plane.

int	esio_plane_readv_double (const esio_handle h, const char name, double plane, int bstride, int astride, int ncomponents)
	Read a vector-valued `double` plane.

int	esio_plane_readv_float (const esio_handle h, const char name, float plane, int bstride, int astride, int ncomponents)
	Read a vector-valued `float` plane.

int	esio_plane_readv_int (const esio_handle h, const char name, int plane, int bstride, int astride, int ncomponents)
	Read a vector-valued `int` plane.

int	esio_plane_sizev (const esio_handle h, const char name, int bglobal, int aglobal, int ncomponents)
	Query the global number of vectors and components within a plane.

Manipulating distributed, three-dimensional, scalar-valued data
See field concepts for more details. Additionally, the C++-only functions `esio_field_write()` and `esio_field_read()` provide overloaded, type-safe versions of these methods.
int	esio_field_write_double (const esio_handle h, const char name, const double field, int cstride, int bstride, int astride, const char *comment)
	Write a scalar-valued `double` field.

int	esio_field_write_float (const esio_handle h, const char name, const float field, int cstride, int bstride, int astride, const char *comment)
	Write a scalar-valued `float` field.

int	esio_field_write_int (const esio_handle h, const char name, const int field, int cstride, int bstride, int astride, const char *comment)
	Write a scalar-valued `int` field.

int	esio_field_read_double (const esio_handle h, const char name, double field, int cstride, int bstride, int astride)
	Read a scalar-valued `double` field.

int	esio_field_read_float (const esio_handle h, const char name, float field, int cstride, int bstride, int astride)
	Read a scalar-valued `float` field.

int	esio_field_read_int (const esio_handle h, const char name, int field, int cstride, int bstride, int astride)
	Read a scalar-valued `int` field.

int	esio_field_size (const esio_handle h, const char name, int cglobal, int bglobal, int aglobal)
	Query the global number of scalars within a field.

Manipulating distributed, three-dimensional, vector-valued data
See field concepts for more details. Additionally, the C++-only functions `esio_field_writev()` and `esio_field_readv()` provide overloaded, type-safe versions of these methods.
int	esio_field_writev_double (const esio_handle h, const char name, const double field, int cstride, int bstride, int astride, int ncomponents, const char *comment)
	Write a vector-valued `double` field.

int	esio_field_writev_float (const esio_handle h, const char name, const float field, int cstride, int bstride, int astride, int ncomponents, const char *comment)
	Write a vector-valued `float` field.

int	esio_field_writev_int (const esio_handle h, const char name, const int field, int cstride, int bstride, int astride, int ncomponents, const char *comment)
	Write a vector-valued `int` field.

int	esio_field_readv_double (const esio_handle h, const char name, double field, int cstride, int bstride, int astride, int ncomponents)
	Read a vector-valued `double` field.

int	esio_field_readv_float (const esio_handle h, const char name, float field, int cstride, int bstride, int astride, int ncomponents)
	Read a vector-valued `float` field.

int	esio_field_readv_int (const esio_handle h, const char name, int field, int cstride, int bstride, int astride, int ncomponents)
	Read a vector-valued `int` field.

int	esio_field_sizev (const esio_handle h, const char name, int cglobal, int bglobal, int aglobal, int *ncomponents)
	Query the global number of vectors and components within a field.

Querying and controlling field layout
See layout concepts for more details.
int	esio_field_layout_count (void)
	Query the number of layouts available within ESIO.

int	esio_field_layout_get (const esio_handle h)
	Get the default layout associated with the given handle.

int	esio_field_layout_set (esio_handle h, int layout_index)
	Set the default layout associated with the given handle.

Typedef Documentation

typedef struct esio_handle_s* esio_handle

An opaque type following ESIO's handle concept.

Function Documentation

int esio_attribute_read_double	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		double *	value
	)

Read a scalar-valued double attribute.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer to contain the read value.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_read_float	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		float *	value
	)

Read a scalar-valued float attribute.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer to contain the read value.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_read_int	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		int *	value
	)

Read a scalar-valued int attribute.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer to contain the read value.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_readv_double	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		double *	value,
		int	ncomponents
	)

Read a vector-valued double attribute.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer to contain the read value.
ncomponents	Number of vector components.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_readv_float	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		float *	value,
		int	ncomponents
	)

Read a vector-valued float attribute.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer to contain the read value.
ncomponents	Number of vector components.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_readv_int	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		int *	value,
		int	ncomponents
	)

Read a vector-valued int attribute.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer to contain the read value.
ncomponents	Number of vector components.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_sizev	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		int *	ncomponents
	)

Query the number of components in a numeric attribute.

Scalar-valued attributes have *ncomponents == 1. Querying a non-existent location or name will return ESIO_NOTFOUND, will not modify ncomponents, and will not trigger ESIO's standard error handling mechanisms.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
ncomponents	Buffer to contain the number of components.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_write_double	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		const double *	value
	)

Write a scalar-valued double attribute.

Any existing attribute value will be overwritten.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer containing the scalar to write.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_write_float	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		const float *	value
	)

Write a scalar-valued float attribute.

Any existing attribute value will be overwritten.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer containing the scalar to write.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_write_int	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		const int *	value
	)

Write an scalar-valued int attribute.

Any existing attribute value will be overwritten.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer containing the scalar to write.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_writev_double	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		const double *	value,
		int	ncomponents
	)

Write a vector-valued double attribute.

Any existing attribute value will be overwritten.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer containing the scalar to write.
ncomponents	Number of vector components.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_writev_float	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		const float *	value,
		int	ncomponents
	)

Write a vector-valued float attribute.

Any existing attribute value will be overwritten.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer containing the scalar to write.
ncomponents	Number of vector components.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_attribute_writev_int	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		const int *	value,
		int	ncomponents
	)

Write a vector-valued int attribute.

Any existing attribute value will be overwritten.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Buffer containing the scalar to write.
ncomponents	Number of vector components.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_establish	(	esio_handle	h,
		int	cglobal,
		int	cstart,
		int	clocal,
		int	bglobal,
		int	bstart,
		int	blocal,
		int	aglobal,
		int	astart,
		int	alocal
	)

Establish the parallel decomposition to use for subsequent field operations.

Global starting offsets are zero-indexed.

Parameters

h	Handle to use.
cglobal	Global number of scalars in the "C" slowest direction.
cstart	Global starting "C" offset.
clocal	Number of scalars in "C" this MPI rank should handle.
bglobal	Global number of scalars in the "B" direction.
bstart	Global starting "B" offset.
blocal	Number of scalars in "B" this MPI rank should handle.
aglobal	Global number of scalars in the fastest "A" direction.
astart	Global starting "A" offset.
alocal	Number of scalars in "A" this MPI rank should handle.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

See Also: Field concepts for more details.

int esio_field_established	(	esio_handle	h,
		int *	cglobal,
		int *	cstart,
		int *	clocal,
		int *	bglobal,
		int *	bstart,
		int *	blocal,
		int *	aglobal,
		int *	astart,
		int *	alocal
	)

Retrieve any parallel decomposition previously established for field operations.

NULL arguments will be ignored.

Global starting offsets are zero-indexed.

Parameters

h	Handle to use.
cglobal	Global number of scalars in the "C" slowest direction.
cstart	Global starting "C" offset.
clocal	Number of scalars in "C" this MPI rank should handle.
bglobal	Global number of scalars in the "B" direction.
bstart	Global starting "B" offset.
blocal	Number of scalars in "B" this MPI rank should handle.
aglobal	Global number of scalars in the fastest "A" direction.
astart	Global starting "A" offset.
alocal	Number of scalars in "A" this MPI rank should handle.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

See Also: Field concepts for more details.

int esio_field_layout_count ( void )

Query the number of layouts available within ESIO.

This is the maximum layout_index + 1.

Returns: The number of layouts available within ESIO.

int esio_field_layout_get ( const esio_handle h )

Get the default layout associated with the given handle.

This layout will be used when writing any new fields.

Parameters

h	Handle to use.

Returns: A layout_index value suitable for use with esio_field_layout_set(). On error, zero is returned.

int esio_field_layout_set	(	esio_handle	h,
		int	layout_index
	)

Set the default layout associated with the given handle.

The supplied layout will be used when writing any new fields.

Parameters

h	Handle to use.
layout_index	Layout index to set in the range `[0,` esio_field_layout_count()`)`.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_read_double	(	const esio_handle	h,
		const char *	name,
		double *	field,
		int	cstride,
		int	bstride,
		int	astride
	)

Read a scalar-valued double field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer to contain the read scalars.
cstride	Stride between adjacent scalars in "C" within buffer `field`.
bstride	Stride between adjacent scalars in "B" within buffer `field`.
astride	Stride between adjacent scalars in "A" within buffer `field`.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_read_float	(	const esio_handle	h,
		const char *	name,
		float *	field,
		int	cstride,
		int	bstride,
		int	astride
	)

Read a scalar-valued float field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer to contain the read scalars.
cstride	Stride between adjacent scalars in "C" within buffer `field`.
bstride	Stride between adjacent scalars in "B" within buffer `field`.
astride	Stride between adjacent scalars in "A" within buffer `field`.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_read_int	(	const esio_handle	h,
		const char *	name,
		int *	field,
		int	cstride,
		int	bstride,
		int	astride
	)

Read a scalar-valued int field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer to contain the read scalars.
cstride	Stride between adjacent scalars in "C" within buffer `field`.
bstride	Stride between adjacent scalars in "B" within buffer `field`.
astride	Stride between adjacent scalars in "A" within buffer `field`.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_readv_double	(	const esio_handle	h,
		const char *	name,
		double *	field,
		int	cstride,
		int	bstride,
		int	astride,
		int	ncomponents
	)

Read a vector-valued double field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer to contain the read vectors.
cstride	Stride between adjacent vectors in "C" within buffer `field`.
bstride	Stride between adjacent vectors in "B" within buffer `field`.
astride	Stride between adjacent vectors in "A" within buffer `field`.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_readv_float	(	const esio_handle	h,
		const char *	name,
		float *	field,
		int	cstride,
		int	bstride,
		int	astride,
		int	ncomponents
	)

Read a vector-valued float field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer to contain the read vectors.
cstride	Stride between adjacent vectors in "C" within buffer `field`.
bstride	Stride between adjacent vectors in "B" within buffer `field`.
astride	Stride between adjacent vectors in "A" within buffer `field`.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_readv_int	(	const esio_handle	h,
		const char *	name,
		int *	field,
		int	cstride,
		int	bstride,
		int	astride,
		int	ncomponents
	)

Read a vector-valued int field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer to contain the read vectors.
cstride	Stride between adjacent vectors in "C" within buffer `field`.
bstride	Stride between adjacent vectors in "B" within buffer `field`.
astride	Stride between adjacent vectors in "A" within buffer `field`.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_size	(	const esio_handle	h,
		const char *	name,
		int *	cglobal,
		int *	bglobal,
		int *	aglobal
	)

Query the global number of scalars within a field.

Querying a non-existent name will return ESIO_NOTFOUND, will not modify cglobal, bglobal, or aglobal, and will not trigger ESIO's standard error handling mechanisms.

Parameters

h	Handle to use.
name	Null-terminated field name.
cglobal	Buffer to contain the number of scalars in the slowest "C" direction.
bglobal	Buffer to contain the number of scalars in the "B" direction.
aglobal	Buffer to contain the number of scalars in the fastest "A" direction.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_sizev	(	const esio_handle	h,
		const char *	name,
		int *	cglobal,
		int *	bglobal,
		int *	aglobal,
		int *	ncomponents
	)

Query the global number of vectors and components within a field.

Scalar-valued fields have *ncomponents == 1. Querying a non-existent name will return ESIO_NOTFOUND, will not modify cglobal, bglocal, aglobal, or ncomponents, and will not trigger ESIO's standard error handling mechanisms.

Parameters

h	Handle to use.
name	Null-terminated field name.
cglobal	Buffer to contain the number of vectors in the slowest "C" direction.
bglobal	Buffer to contain the number of vectors in the "B" direction.
aglobal	Buffer to contain the number of vectors in the fastest "A" direction.
ncomponents	Buffer to contain the number of component in each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_write_double	(	const esio_handle	h,
		const char *	name,
		const double *	field,
		int	cstride,
		int	bstride,
		int	astride,
		const char *	comment
	)

Write a scalar-valued double field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer containing the scalars to write.
cstride	Stride between adjacent scalars in "C" within buffer `field`.
bstride	Stride between adjacent scalars in "B" within buffer `field`.
astride	Stride between adjacent scalars in "A" within buffer `field`.
comment	Comment to associate with the field. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_write_float	(	const esio_handle	h,
		const char *	name,
		const float *	field,
		int	cstride,
		int	bstride,
		int	astride,
		const char *	comment
	)

Write a scalar-valued float field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer containing the scalars to write.
cstride	Stride between adjacent scalars in "C" within buffer `field`.
bstride	Stride between adjacent scalars in "B" within buffer `field`.
astride	Stride between adjacent scalars in "A" within buffer `field`.
comment	Comment to associate with the field. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_write_int	(	const esio_handle	h,
		const char *	name,
		const int *	field,
		int	cstride,
		int	bstride,
		int	astride,
		const char *	comment
	)

Write a scalar-valued int field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer containing the scalars to write.
cstride	Stride between adjacent scalars in "C" within buffer `field`.
bstride	Stride between adjacent scalars in "B" within buffer `field`.
astride	Stride between adjacent scalars in "A" within buffer `field`.
comment	Comment to associate with the field. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_writev_double	(	const esio_handle	h,
		const char *	name,
		const double *	field,
		int	cstride,
		int	bstride,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued double field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer containing the vectors to write.
cstride	Stride between adjacent vectors in "C" within buffer `field`.
bstride	Stride between adjacent vectors in "B" within buffer `field`.
astride	Stride between adjacent vectors in "A" within buffer `field`.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_writev_float	(	const esio_handle	h,
		const char *	name,
		const float *	field,
		int	cstride,
		int	bstride,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued float field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer containing the vectors to write.
cstride	Stride between adjacent vectors in "C" within buffer `field`.
bstride	Stride between adjacent vectors in "B" within buffer `field`.
astride	Stride between adjacent vectors in "A" within buffer `field`.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_field_writev_int	(	const esio_handle	h,
		const char *	name,
		const int *	field,
		int	cstride,
		int	bstride,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued int field.

The parallel decomposition must have been set by a previous call to esio_field_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated field name.
field	Buffer containing the vectors to write.
cstride	Stride between adjacent vectors in "C" within buffer `field`.
bstride	Stride between adjacent vectors in "B" within buffer `field`.
astride	Stride between adjacent vectors in "A" within buffer `field`.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_file_clone	(	esio_handle	h,
		const char *	srcfile,
		const char *	dstfile,
		int	overwrite
	)

Create and open a new file by cloning the contents of an existing file.

Either or both of srcfile and dstfile may contain a leading URI scheme or host name (e.g. "ufs:", "machine.univ.edu:").

Parameters

h	Handle to use.
srcfile	Name of the existing file to be cloned.
dstfile	Name of the new file to be opened.
overwrite	If zero, fail if an existing file with name `dstfile` is detected. If nonzero, clobber any existing file.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_file_close ( esio_handle h )

Close any currently open file.

Closing a file automatically flushes all unwritten data.

Parameters

h	Handle to use.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_file_close_restart	(	esio_handle	h,
		const char *	restart_template,
		int	retain_count
	)

Close the currently open file and rename it to match the path given in restart_template.

Up to retain_count previous restart files will be retained and will automatically have their index numbers incremented. Index numbers are in the range [0, retain_count-1] (inclusive) with index 0 being the newest file.

The restart_template path can be an absolute or relative path where the final filename must contain a sequence of one or more consecutive hash signs ('#') which will be populated with restart index numbers. A sufficient number of leading zeros to accommodate retain_count - 1 separate restart files will always be present. Using additional hash signs will increase the number of leading zeros appearing in restart file names.

Warning: The currently open file path must not match restart_template, otherwise this method will fail with mysterious renaming errors.

Parameters

h	Handle to use.
restart_template	The restart template to use. See the information above for what constitutes a valid value. It may contain a leading URI scheme (e.g. "ufs:").
retain_count	The maximum number of old restart files to retain. Value must be strictly positive.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure. On failure the handle h will be in an undefined state and should be finalized using esio_handle_finalize(). Applications are advised to treat a failure within this method as unrecoverable.

int esio_file_create	(	esio_handle	h,
		const char *	file,
		int	overwrite
	)

Create a new file or overwrite an existing one.

Parameters

h	Handle to use.
file	Name of the file to open. It may contain a leading URI scheme or host name (e.g. "ufs:", "machine.univ.edu:").
overwrite	If zero, fail if an existing file is detected. If nonzero, clobber any existing file.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_file_flush ( esio_handle h )

Flush buffers associated with any currently open file.

Parameters

h	Handle to use.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_file_open	(	esio_handle	h,
		const char *	file,
		int	readwrite
	)

Open an existing file.

Parameters

h	Handle to use.
file	Name of the file to open. It may contain a leading URI scheme or host name (e.g. "ufs:", "machine.univ.edu:").
readwrite	If zero, open the file in read-only mode. If nonzero, open the file in read-write mode.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

char* esio_file_path ( const esio_handle h )

Get the canonical path to the currently open file.

The routine allocates sufficient storage to hold the string and returns it. The caller must free the memory to avoid resource leaks. If no file is currently open, the routine returns NULL. The returned value will not contain a MPI-IO scheme or host prefix (e.g. "ufs:", "machine.univ.edu:") if one was supplied when the file was opened.

Parameters

h	Handle to use.

Returns: A newly allocated buffer containing the null-terminated string on success. NULL on failure.

See Also: The MPI standard's advice to implementors discussion for MPI_FILE_OPEN regarding MPI-IO scheme prefixes and RFC 3986 section 3 for the recognized URI scheme syntax.

int esio_handle_comm_rank	(	const esio_handle	h,
		int *	rank
	)

Retrieve the rank of the local MPI process as seen by the MPI communicator over which the handle collectively operates.

This method may be invoked in a non-collective manner and has semantics identical to MPI_Comm_rank.

Parameters

h	Handle to use.
rank	On success, contains the MPI communicator rank.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_handle_comm_size	(	const esio_handle	h,
		int *	size
	)

Retrieve the size of the MPI communicator over which the handle collectively operates.

This method may be invoked in a non-collective manner and has semantics identical to MPI_Comm_size.

Parameters

h	Handle to use.
size	On success, contains the MPI communicator size.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_handle_finalize ( esio_handle h )

Finalize a handle.

Finalizing a handle automatically closes any associated file.

Parameters

h	Handle to finalize. May be `NULL`.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

esio_handle esio_handle_initialize ( MPI_Comm comm )

Initialize a handle against the given MPI communicator.

The handle must be finalized using esio_handle_finalize() to avoid resource leaks.

Parameters

comm	MPI communicator (e.g. `MPI_COMM_WORLD`) used to determine the parallel scope of the handle. All ESIO calls employing the handle must be made collectively on `comm`.

Returns: A new handle on success. Otherwise NULL.

int esio_line_establish	(	esio_handle	h,
		int	aglobal,
		int	astart,
		int	alocal
	)

Establish the parallel decomposition to use for subsequent line operations.

Parameters

h	Handle to use.
aglobal	Global number of values within the line.
astart	Global starting offset (zero-indexed) handled locally by this MPI rank.
alocal	Number of values this MPI rank should write.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

See Also: Line concepts for more details.

int esio_line_established	(	esio_handle	h,
		int *	aglobal,
		int *	astart,
		int *	alocal
	)

Retrieve any parallel decomposition previously established for line operations.

NULL arguments will be ignored.

Parameters

h	Handle to use.
aglobal	Global number of values within the line.
astart	Global starting offset (zero-indexed) handled locally by this MPI rank.
alocal	Number of values this MPI rank should write.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

See Also: Line concepts for more details.

int esio_line_read_double	(	const esio_handle	h,
		const char *	name,
		double *	line,
		int	astride
	)

Read a scalar-valued double line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer to contain the read scalars.
astride	Stride between adjacent values in buffer `line` measured in `sizeof(`scalar`)`. Supplying zero indicates contiguous data.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_read_float	(	const esio_handle	h,
		const char *	name,
		float *	line,
		int	astride
	)

Read a scalar-valued float line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer to contain the read scalars.
astride	Stride between adjacent values in buffer `line` measured in `sizeof(`scalar`)`. Supplying zero indicates contiguous data.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_read_int	(	const esio_handle	h,
		const char *	name,
		int *	line,
		int	astride
	)

Read a scalar-valued int line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer to contain the read scalars.
astride	Stride between adjacent values in buffer `line` measured in `sizeof(`scalar`)`. Supplying zero indicates contiguous data.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_readv_double	(	const esio_handle	h,
		const char *	name,
		double *	line,
		int	astride,
		int	ncomponents
	)

Read a vector-valued double line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer to contain the read vectors.
astride	Stride between adjacent vectors in buffer `line` measured in `sizeof(`scalar`)`. It must be an integer multiple of `ncomponents`. Supplying zero indicates contiguous data.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_readv_float	(	const esio_handle	h,
		const char *	name,
		float *	line,
		int	astride,
		int	ncomponents
	)

Read a vector-valued float line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer to contain the read vectors.
astride	Stride between adjacent vectors in buffer `line` measured in `sizeof(`scalar`)`. It must be an integer multiple of `ncomponents`. Supplying zero indicates contiguous data.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_readv_int	(	const esio_handle	h,
		const char *	name,
		int *	line,
		int	astride,
		int	ncomponents
	)

Read a vector-valued int line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer to contain the read vectors.
astride	Stride between adjacent vectors in buffer `line` measured in `sizeof(`scalar`)`. It must be an integer multiple of `ncomponents`. Supplying zero indicates contiguous data.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_size	(	const esio_handle	h,
		const char *	name,
		int *	aglobal
	)

Query the global number of scalars within a line.

Querying a non-existent name will return ESIO_NOTFOUND, will not modify aglobal, and will not trigger ESIO's standard error handling mechanisms.

Parameters

h	Handle to use.
name	Null-terminated attribute name.
aglobal	Buffer to contain the number of scalars within the line.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_sizev	(	const esio_handle	h,
		const char *	name,
		int *	aglobal,
		int *	ncomponents
	)

Query the global number of vectors and components within a line.

Scalar-valued lines have *ncomponents == 1. Querying a non-existent name will return ESIO_NOTFOUND, will not modify aglobal or ncomponents, and will not trigger ESIO's standard error handling mechanisms.

Parameters

h	Handle to use.
name	Null-terminated line name.
aglobal	Buffer to contain the number of vectors within the line.
ncomponents	Buffer to contain the number of component in each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_write_double	(	const esio_handle	h,
		const char *	name,
		const double *	line,
		int	astride,
		const char *	comment
	)

Write a scalar-valued double line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer containing the scalars to write.
astride	Stride between adjacent values in buffer `line` measured in `sizeof(`scalar`)`. Supplying zero indicates contiguous data.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_write_float	(	const esio_handle	h,
		const char *	name,
		const float *	line,
		int	astride,
		const char *	comment
	)

Write a scalar-valued float line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer containing the scalars to write.
astride	Stride between adjacent values in buffer `line` measured in `sizeof(`scalar`)`. Supplying zero indicates contiguous data.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_write_int	(	const esio_handle	h,
		const char *	name,
		const int *	line,
		int	astride,
		const char *	comment
	)

Write a scalar-valued int line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer containing the scalars to write.
astride	Stride between adjacent values in buffer `line` measured in `sizeof(`scalar`)`. Supplying zero indicates contiguous data.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_writev_double	(	const esio_handle	h,
		const char *	name,
		const double *	line,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued double line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer containing the vectors to write.
astride	Stride between adjacent vectors in buffer `line` measured in `sizeof(`scalar`)`. It must be an integer multiple of `ncomponents`. Supplying zero indicates contiguous data.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_writev_float	(	const esio_handle	h,
		const char *	name,
		const float *	line,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued float line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer containing the vectors to write.
astride	Stride between adjacent vectors in buffer `line` measured in `sizeof(`scalar`)`. It must be an integer multiple of `ncomponents`. Supplying zero indicates contiguous data.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_line_writev_int	(	const esio_handle	h,
		const char *	name,
		const int *	line,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued int line.

The parallel decomposition must have been set by a previous call to esio_line_establish().

Parameters

h	Handle to use.
name	Null-terminated attribute name.
line	Buffer containing the vectors to write.
astride	Stride between adjacent vectors in buffer `line` measured in `sizeof(`scalar`)`. It must be an integer multiple of `ncomponents`. Supplying zero indicates contiguous data.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the line. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_establish	(	esio_handle	h,
		int	bglobal,
		int	bstart,
		int	blocal,
		int	aglobal,
		int	astart,
		int	alocal
	)

Establish the parallel decomposition to use for subsequent plane operations.

Global starting offsets are zero-indexed.

Parameters

h	Handle to use.
bglobal	Global number of scalars in the slower "B" direction.
bstart	Global starting "B" offset.
blocal	Number of values in "B" this MPI rank should handle.
aglobal	Global number of scalars in the faster "A" direction.
astart	Global starting "A" offset.
alocal	Number of values in "A" this MPI rank should handle.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

See Also: Plane concepts for more details.

int esio_plane_established	(	esio_handle	h,
		int *	bglobal,
		int *	bstart,
		int *	blocal,
		int *	aglobal,
		int *	astart,
		int *	alocal
	)

Retrieve any parallel decomposition previously established for plane operations.

NULL arguments will be ignored.

Global starting offsets are zero-indexed.

Parameters

h	Handle to use.
bglobal	Global number of scalars in the slower "B" direction.
bstart	Global starting "B" offset.
blocal	Number of values in "B" this MPI rank should handle.
aglobal	Global number of scalars in the faster "A" direction.
astart	Global starting "A" offset.
alocal	Number of values in "A" this MPI rank should handle.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

See Also: Plane concepts for more details.

int esio_plane_read_double	(	const esio_handle	h,
		const char *	name,
		double *	plane,
		int	bstride,
		int	astride
	)

Read a scalar-valued double plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer to contain the read scalars.
bstride	Stride between adjacent scalars in "B" within buffer `plane`.
astride	Stride between adjacent scalars in "A" within buffer `plane`.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_read_float	(	const esio_handle	h,
		const char *	name,
		float *	plane,
		int	bstride,
		int	astride
	)

Read a scalar-valued float plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer to contain the read scalars.
bstride	Stride between adjacent scalars in "B" within buffer `plane`.
astride	Stride between adjacent scalars in "A" within buffer `plane`.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_read_int	(	const esio_handle	h,
		const char *	name,
		int *	plane,
		int	bstride,
		int	astride
	)

Read a scalar-valued int plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer to contain the read scalars.
bstride	Stride between adjacent scalars in "B" within buffer `plane`.
astride	Stride between adjacent scalars in "A" within buffer `plane`.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_readv_double	(	const esio_handle	h,
		const char *	name,
		double *	plane,
		int	bstride,
		int	astride,
		int	ncomponents
	)

Read a vector-valued double plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer to contain the read vectors.
bstride	Stride between adjacent vectors in "B" within buffer `plane`.
astride	Stride between adjacent vectors in "A" within buffer `plane`.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_readv_float	(	const esio_handle	h,
		const char *	name,
		float *	plane,
		int	bstride,
		int	astride,
		int	ncomponents
	)

Read a vector-valued float plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer to contain the read vectors.
bstride	Stride between adjacent vectors in "B" within buffer `plane`.
astride	Stride between adjacent vectors in "A" within buffer `plane`.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_readv_int	(	const esio_handle	h,
		const char *	name,
		int *	plane,
		int	bstride,
		int	astride,
		int	ncomponents
	)

Read a vector-valued int plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer to contain the read vectors.
bstride	Stride between adjacent vectors in "B" within buffer `plane`.
astride	Stride between adjacent vectors in "A" within buffer `plane`.
ncomponents	Number of scalar components within each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_size	(	const esio_handle	h,
		const char *	name,
		int *	bglobal,
		int *	aglobal
	)

Query the global number of scalars within a plane.

Querying a non-existent name will return ESIO_NOTFOUND, will not modify bglobal or aglobal, and will not trigger ESIO's standard error handling mechanisms.

Parameters

h	Handle to use.
name	Null-terminated plane name.
bglobal	Buffer to contain the number of scalars in the slower "B" direction.
aglobal	Buffer to contain the number of scalars in the faster "A" direction.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_sizev	(	const esio_handle	h,
		const char *	name,
		int *	bglobal,
		int *	aglobal,
		int *	ncomponents
	)

Query the global number of vectors and components within a plane.

Scalar-valued planes have *ncomponents == 1. Querying a non-existent name will return ESIO_NOTFOUND, will not modify bglobal, aglobal, or ncomponents, and will not trigger ESIO's standard error handling mechanisms.

Parameters

h	Handle to use.
name	Null-terminated plane name.
bglobal	Buffer to contain the number of vectors in the slower "B" direction.
aglobal	Buffer to contain the number of vectors in the faster "A" direction.
ncomponents	Buffer to contain the number of component in each vector.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_write_double	(	const esio_handle	h,
		const char *	name,
		const double *	plane,
		int	bstride,
		int	astride,
		const char *	comment
	)

Write a scalar-valued double plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer containing the scalars to write.
bstride	Stride between adjacent scalars in "B" within buffer `plane`.
astride	Stride between adjacent scalars in "A" within buffer `plane`.
comment	Comment to associate with the plane. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_write_float	(	const esio_handle	h,
		const char *	name,
		const float *	plane,
		int	bstride,
		int	astride,
		const char *	comment
	)

Write a scalar-valued float plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer containing the scalars to write.
bstride	Stride between adjacent scalars in "B" within buffer `plane`.
astride	Stride between adjacent scalars in "A" within buffer `plane`.
comment	Comment to associate with the plane. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_write_int	(	const esio_handle	h,
		const char *	name,
		const int *	plane,
		int	bstride,
		int	astride,
		const char *	comment
	)

Write a scalar-valued int plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer containing the scalars to write.
bstride	Stride between adjacent scalars in "B" within buffer `plane`.
astride	Stride between adjacent scalars in "A" within buffer `plane`.
comment	Comment to associate with the plane. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_writev_double	(	const esio_handle	h,
		const char *	name,
		const double *	plane,
		int	bstride,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued double plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer containing the vectors to write.
bstride	Stride between adjacent vectors in "B" within buffer `plane`.
astride	Stride between adjacent vectors in "A" within buffer `plane`.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the plane. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_writev_float	(	const esio_handle	h,
		const char *	name,
		const float *	plane,
		int	bstride,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued float plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer containing the vectors to write.
bstride	Stride between adjacent vectors in "B" within buffer `plane`.
astride	Stride between adjacent vectors in "A" within buffer `plane`.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the plane. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

int esio_plane_writev_int	(	const esio_handle	h,
		const char *	name,
		const int *	plane,
		int	bstride,
		int	astride,
		int	ncomponents,
		const char *	comment
	)

Write a vector-valued int plane.

The parallel decomposition must have been set by a previous call to esio_plane_establish(). All strides are measured in sizeof(scalar). Strides must be an integer multiple of ncomponents. Supplying zero for a stride indicates that direction is contiguous in memory.

Parameters

h	Handle to use.
name	Null-terminated plane name.
plane	Buffer containing the vectors to write.
bstride	Stride between adjacent vectors in "B" within buffer `plane`.
astride	Stride between adjacent vectors in "A" within buffer `plane`.
ncomponents	Number of scalar components within each vector.
comment	Comment to associate with the plane. Providing NULL or the empty string indicates that no comment should be written.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

char* esio_string_get	(	const esio_handle	h,
		const char *	location,
		const char *	name
	)

Get a string-valued attribute.

The routine allocates sufficient storage to hold the string and returns it. The caller must free the memory to avoid resource leaks. Querying a non-existent location or name will not invoke ESIO's standard error handling mechanisms.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.

Returns: A newly allocated buffer containing the null-terminated string on success. NULL on failure.

int esio_string_set	(	const esio_handle	h,
		const char *	location,
		const char *	name,
		const char *	value
	)

Set a string-valued attribute.

Any existing attribute will be overwritten.

Parameters

h	Handle to use.
location	Null-terminated attribute location. Must be either "/" to specify a file-level attribute or be the name of an existing line, plane, or field.
name	Null-terminated attribute name.
value	Null-terminated attribute value to set.

Returns: Either ESIO_SUCCESS (0) or one of esio_status on failure.

Detailed Description

Typedefs

Functions

Typedef Documentation

Function Documentation