Helper routines for general and parallel I/O. More...

#include <sc_containers.h>

Include dependency graph for sc_io.h:

Data Structures
struct	sc_io_sink
	A generic data sink. More...

struct	sc_io_source
	A generic data source. More...

Macros
#define	SC_CHECK_MPI_VERBOSE(errcode, user_msg)
	Examine the MPI return value and print an error if there is one. More...

#define	sc_mpi_read sc_io_read
	For backwards compatibility.

#define	sc_mpi_write sc_io_write
	For backwards compatibility.

Typedefs
typedef struct sc_io_sink	sc_io_sink_t
	A generic data sink.

typedef struct sc_io_source	sc_io_source_t
	A generic data source.

Enumerations
enum	sc_io_error_t { SC_IO_ERROR_NONE , SC_IO_ERROR_FATAL = -1 , SC_IO_ERROR_AGAIN = -2 }
	Error values for io. More...

enum	sc_io_mode_t { SC_IO_MODE_WRITE , SC_IO_MODE_APPEND , SC_IO_MODE_LAST }
	The I/O mode for writing using sc_io_sink. More...

enum	sc_io_encode_t { SC_IO_ENCODE_NONE , SC_IO_ENCODE_LAST }
	Enum to specify encoding for sc_io_sink and sc_io_source. More...

enum	sc_io_type_t { SC_IO_TYPE_BUFFER , SC_IO_TYPE_FILENAME , SC_IO_TYPE_FILEFILE , SC_IO_TYPE_LAST }
	The type of I/O operation sc_io_sink and sc_io_source. More...

enum	sc_io_open_mode_t { SC_IO_READ , SC_IO_WRITE_CREATE , SC_IO_WRITE_APPEND }
	Open modes for sc_io_open. More...

Functions
sc_io_sink_t *	sc_io_sink_new (int iotype, int iomode, int ioencode,...)
	Create a generic data sink. More...

int	sc_io_sink_destroy (sc_io_sink_t *sink)
	Free data sink. More...

int	sc_io_sink_destroy_null (sc_io_sink_t **sink)
	Free data sink and NULL the pointer to it. More...

int	sc_io_sink_write (sc_io_sink_t sink, const void data, size_t bytes_avail)
	Write data to a sink. More...

int	sc_io_sink_complete (sc_io_sink_t sink, size_t bytes_in, size_t *bytes_out)
	Flush all buffered output data to sink. More...

int	sc_io_sink_align (sc_io_sink_t *sink, size_t bytes_align)
	Align sink to a byte boundary by writing zeros. More...

sc_io_source_t *	sc_io_source_new (int iotype, int ioencode,...)
	Create a generic data source. More...

int	sc_io_source_destroy (sc_io_source_t *source)
	Free data source. More...

int	sc_io_source_destroy_null (sc_io_source_t **source)
	Free data source and NULL the pointer to it. More...

int	sc_io_source_read (sc_io_source_t source, void data, size_t bytes_avail, size_t *bytes_out)
	Read data from a source. More...

int	sc_io_source_complete (sc_io_source_t source, size_t bytes_in, size_t *bytes_out)
	Determine whether all data buffered from source has been returned by read. More...

int	sc_io_source_align (sc_io_source_t *source, size_t bytes_align)
	Align source to a byte boundary by skipping. More...

int	sc_io_source_activate_mirror (sc_io_source_t *source)
	Activate a buffer that mirrors (i.e., stores) the data that was read. More...

int	sc_io_source_read_mirror (sc_io_source_t source, void data, size_t bytes_avail, size_t *bytes_out)
	Read data from the source's mirror. More...

int	sc_io_file_save (const char filename, sc_array_t buffer)
	Save a buffer to a file in one call. More...

int	sc_io_file_load (const char filename, sc_array_t buffer)
	Read a file into a buffer in one call. More...

void	sc_io_encode (sc_array_t data, sc_array_t out)
	Encode a block of arbitrary data with the default sc_io format. More...

void	sc_io_encode_zlib (sc_array_t data, sc_array_t out, int zlib_compression_level, int line_break_character)
	Encode a block of arbitrary data, compressed, into an ASCII string. More...

int	sc_io_decode_info (sc_array_t data, size_t original_size, char format_char, void re)
	Decode length and format of original input from encoded data. More...

int	sc_io_decode (sc_array_t data, sc_array_t out, size_t max_original_size, void *re)
	Decode a block of base 64 encoded compressed data. More...

int	sc_vtk_write_binary (FILE vtkfile, char numeric_data, size_t byte_length)
	This function writes numeric binary data in VTK base64 encoding. More...

int	sc_vtk_write_compressed (FILE vtkfile, char numeric_data, size_t byte_length)
	This function writes numeric binary data in VTK compressed format. More...

FILE *	sc_fopen (const char filename, const char mode, const char *errmsg)
	Wrapper for fopen(3). More...

void	sc_fwrite (const void ptr, size_t size, size_t nmemb, FILE file, const char *errmsg)
	Write memory content to a file. More...

void	sc_fread (void ptr, size_t size, size_t nmemb, FILE file, const char *errmsg)
	Read file content into memory. More...

void	sc_fflush_fsync_fclose (FILE *file)
	Best effort to flush a file's data to disc and close it. More...

int	sc_io_open (sc_MPI_Comm mpicomm, const char filename, sc_io_open_mode_t amode, sc_MPI_Info mpiinfo, sc_MPI_File mpifile)
	Opens a MPI file or without MPI a file context. More...

void	sc_io_read (sc_MPI_File mpifile, void ptr, size_t zcount, sc_MPI_Datatype t, const char errmsg)
	Read MPI file content into memory. More...

int	sc_io_read_at (sc_MPI_File mpifile, sc_MPI_Offset offset, void ptr, int count, sc_MPI_Datatype t, int ocount)
	Read MPI file content into memory for an explicit offset. More...

int	sc_io_read_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset, void ptr, int count, sc_MPI_Datatype t, int ocount)
	Read MPI file content collectively into memory for an explicit offset. More...

void	sc_io_write (sc_MPI_File mpifile, const void ptr, size_t zcount, sc_MPI_Datatype t, const char errmsg)
	Write memory content to an MPI file. More...

int	sc_io_write_at (sc_MPI_File mpifile, sc_MPI_Offset offset, const void ptr, int count, sc_MPI_Datatype t, int ocount)
	Write MPI file content into memory for an explicit offset. More...

int	sc_io_write_at_all (sc_MPI_File mpifile, sc_MPI_Offset offset, const void ptr, int count, sc_MPI_Datatype t, int ocount)
	Write MPI file content collectively into memory for an explicit offset. More...

int	sc_io_close (sc_MPI_File *file)
	Close collectively a sc_MPI_File. More...

Detailed Description

Helper routines for general and parallel I/O.

This file provides various sets of functions related to write and read data as well es to encode and decode it to certain formats.

To abstract transparent writing/reading into/from files or buffers, we provide functions centered around sc_io_sink_new and sc_io_source_new.
To abstract parallel file I/O in a way that works both with and without MPI support, we provide sc_io_open, sc_io_write and friends.
To write to the VTK binary compressed format, we provide suitable functions to base64 encode and zlib-compress as required; see sc_vtk_write_binary and sc_vtk_write_compressed.
To support self-contained ASCII-armored compression, we provide the functions sc_io_encode, sc_io_decode_info and sc_io_decode. They losslessly transform a block of arbitrary data into a compressed and base64-encoded format and back that is unambiguously defined and human-friendly.

Macro Definition Documentation

◆ SC_CHECK_MPI_VERBOSE

#define SC_CHECK_MPI_VERBOSE	(	errcode,
		user_msg
	)

Value:

  do {            \
  char sc_msg[sc_MPI_MAX_ERROR_STRING];                        \
  int sc_msglen;                                               \
  if ((errcode) != sc_MPI_SUCCESS) {                           \
    sc_MPI_Error_string (errcode, sc_msg, &sc_msglen);         \
    SC_LERRORF ("%s at %s:%d: %s\n",                           \
                (user_msg), __FILE__, __LINE__, sc_msg);       \
  }} while (0)

Examine the MPI return value and print an error if there is one.

The message passed is appended to MPI, file and line information.

Enumeration Type Documentation

◆ sc_io_encode_t

enum sc_io_encode_t

Enum to specify encoding for sc_io_sink and sc_io_source.

Enumerator
SC_IO_ENCODE_NONE	No encoding.
SC_IO_ENCODE_LAST	Invalid entry to close list.

◆ sc_io_error_t

enum sc_io_error_t

Error values for io.

Enumerator

SC_IO_ERROR_NONE

The value of zero means no error.

SC_IO_ERROR_FATAL

The io object is now dysfunctional.

SC_IO_ERROR_AGAIN

Another io operation may resolve it.

The function just returned was a noop.

◆ sc_io_mode_t

enum sc_io_mode_t

The I/O mode for writing using sc_io_sink.

Enumerator
SC_IO_MODE_WRITE	Semantics as "w" in fopen.
SC_IO_MODE_APPEND	Semantics as "a" in fopen.
SC_IO_MODE_LAST	Invalid entry to close list.

◆ sc_io_open_mode_t

enum sc_io_open_mode_t

Open modes for sc_io_open.

Enumerator
SC_IO_READ	open a file in read-only mode
SC_IO_WRITE_CREATE	open a file in write-only mode; if the file exists, the file will be truncated to length zero and then overwritten
SC_IO_WRITE_APPEND	append to an already existing file

◆ sc_io_type_t

enum sc_io_type_t

The type of I/O operation sc_io_sink and sc_io_source.

Enumerator
SC_IO_TYPE_BUFFER	Write to a buffer.
SC_IO_TYPE_FILENAME	Write to a file to be opened.
SC_IO_TYPE_FILEFILE	Write to an already opened file.
SC_IO_TYPE_LAST	Invalid entry to close list.

Function Documentation

◆ sc_fflush_fsync_fclose()

void sc_fflush_fsync_fclose ( FILE * file )

Best effort to flush a file's data to disc and close it.

Parameters

[in,out] file File open for writing.

◆ sc_fopen()

FILE* sc_fopen	(	const char *	filename,
		const char *	mode,
		const char *	errmsg
	)

Wrapper for fopen(3).

We provide an additional argument that contains the error message.

◆ sc_fread()

void sc_fread	(	void *	ptr,
		size_t	size,
		size_t	nmemb,
		FILE *	file,
		const char *	errmsg
	)

Read file content into memory.

Parameters

[out]	ptr	Data array to read from disk.
[in]	size	Size of one array member.
[in]	nmemb	Number of array members.
[in,out]	file	File pointer, must be opened for reading.
[in]	errmsg	Error message passed to SC_CHECK_ABORT.

Note: This function aborts on file errors.

◆ sc_fwrite()

void sc_fwrite	(	const void *	ptr,
		size_t	size,
		size_t	nmemb,
		FILE *	file,
		const char *	errmsg
	)

Write memory content to a file.

Parameters

[in]	ptr	Data array to write to disk.
[in]	size	Size of one array member.
[in]	nmemb	Number of array members.
[in,out]	file	File pointer, must be opened for writing.
[in]	errmsg	Error message passed to SC_CHECK_ABORT.

Note: This function aborts on file errors.

◆ sc_io_close()

int sc_io_close ( sc_MPI_File * file )

Close collectively a sc_MPI_File.

Parameters

[in] file MPI file object that is closed.

Returns: A sc_MPI_ERR_* as defined in sc_mpi.h. The error code can be passed to sc_MPI_Error_string.

◆ sc_io_decode()

int sc_io_decode	(	sc_array_t *	data,
		sc_array_t *	out,
		size_t	max_original_size,
		void *	re
	)

Decode a block of base 64 encoded compressed data.

The base 64 data must contain two arbitrary bytes after every 76 code characters and also at the end of the last line if it is short, and then a final NUL character. This function does not require zlib but benefits for speed.

This is a two-stage process: we decode the input from base 64 first. Then we extract the 8-byte big-endian original data size, the character 'z', and execute a zlib decompression on the remaining decoded data. This function detects malformed input by erroring out.

If we should add another format in the future, the format character may be something else than 'z', as permitted by our specification. To this end, we reserve the characters A-C and d-z indefinitely.

Any error condition is indicated by a negative return value. Possible causes for error are:

the input data string is not NUL-terminated
the first 12 characters of input do not decode properly
the input data is corrupt for decoding or decompression
the output data array has non-unit element size and the length of the output data is not divisible by the size
the output data would exceed the specified threshold
the output array is a view of insufficient length

We also error out if the data requires a compression dictionary, which would be a violation of above encode format specification.

The corresponding encode function is sc_io_encode. When passing an array as output, we resize it properly. This function cannot crash unless out of memory.

Parameters

[in,out]	data	If out is NULL, we work in place. In that case, output is written into this array after a suitable resize. Either way, we expect a NUL-terminated base 64 encoded string on input that has in turn been obtained by zlib compression. It must be in the exact format produced by sc_io_encode; please see documentation. The element size of the input array must be 1.
[in,out]	out	If not NULL, a valid array (may be a view). If NULL, the input array becomes the output. If the output array is a view and the output data larger than its view size, we error out. We expect commensurable element and data size and resize the output to fit exactly, which restores the original input passed to encoding. An output view array of matching size may be constructed using sc_io_decode_info.
[in]	max_original_size	If nonzero, this is the maximal data size that we will accept after uncompression. If exceeded, return a negative value.
[in,out]	re	Provided for error reporting, presently must be NULL.

Returns: 0 on success, negative on malformed input data or insufficient output space.

◆ sc_io_decode_info()

int sc_io_decode_info	(	sc_array_t *	data,
		size_t *	original_size,
		char *	format_char,
		void *	re
	)

Decode length and format of original input from encoded data.

We expect at least 12 bytes of the format produced by sc_io_encode. No matter how much data has been encoded by it, this much is available. We decode the original data size and the character indicating the format.

This function does not require zlib. It works with any well-defined data.

Note that this function is not required before sc_io_decode. Calling this function on any result produced by sc_io_encode will succeed and report a legal format. This function cannot crash.

Parameters

[in]	data	This must be an array with element size 1. If it contains less than 12 code bytes we error out. It its first 12 bytes do not base 64 decode to 9 bytes we error out. We generally ignore the remaining data.
[out]	original_size	If not NULL and we do not error out, set to the original size as encoded in the data.
[out]	format_char	If not NULL and we do not error out, the ninth character of decoded data indicating the format.
[in,out]	re	Provided for error reporting, presently must be NULL.

Returns: 0 on success, negative value on error.

◆ sc_io_encode()

void sc_io_encode	(	sc_array_t *	data,
		sc_array_t *	out
	)

Encode a block of arbitrary data with the default sc_io format.

The corresponding decoder function is sc_io_decode. This function cannot crash unless out of memory.

Currently this function calls sc_io_encode_zlib with compression level Z_BEST_COMPRESSION (subject to change). Without zlib configured that function works uncompressed.

The encoding method and input data size can be retrieved, optionally, from the encoded data by sc_io_decode_info. This function decodes the method as a character, which is 'z' for sc_io_encode_zlib. We reserve the characters A-C, d-z indefinitely.

Parameters

[in,out]	data	If out is NULL, we work in place. In this case, the array must on input have an element size of 1 byte, which is preserved. After reading all data from this array, it assumes the identity of the out argument below. Otherwise, this is a read-only argument that may have arbitrary element size. On input, all data in the array is used.
[in,out]	out	If not NULL, a valid array of element size 1. It must be resizable (not a view). We resize the array to the output data, which always includes a final terminating zero.

◆ sc_io_encode_zlib()

void sc_io_encode_zlib	(	sc_array_t *	data,
		sc_array_t *	out,
		int	zlib_compression_level,
		int	line_break_character
	)

Encode a block of arbitrary data, compressed, into an ASCII string.

This is a two-stage process: zlib compress and then encode to base 64. The output is a NUL-terminated string of printable characters.

We first compress the data into the zlib deflate format (RFC 1951). The compressor must use no preset dictionary (this is the default). If zlib is detected on configuration, we compress with the given level. If zlib is not detected, we write data equivalent to Z_NO_COMPRESSION. The status of zlib detection can be queried at compile time using #ifdef SC_HAVE_ZLIB or at run time using sc_have_zlib. Both types of result are readable by a standard zlib uncompress call.

Secondly, we process the input data size as an 8-byte big-endian number, then the letter 'z', and then the zlib compressed data, concatenated, with a base 64 encoder. We break lines after 76 code characters. Each line break consists of two configurable but arbitrary bytes. The line breaks are considered part of the output data specification. The last line is terminated with the same line break and then a NUL.

This routine can work in place or write to an output array. The corresponding decoder function is sc_io_decode. This function cannot crash unless out of memory.

Parameters

[in,out]	data	If out is NULL, we work in place. In this case, the array must on input have an element size of 1 byte, which is preserved. After reading all data from this array, it assumes the identity of the out argument below. Otherwise, this is a read-only argument that may have arbitrary element size. On input, all data in the array is used.
[in,out]	out	If not NULL, a valid array of element size 1. It must be resizable (not a view). We resize the array to the output data, which always includes a final terminating zero.
[in]	zlib_compression_level	Compression level between 0 (no compression) and 9 (best compression). The value -1 indicates some default level.
[in]	line_break_character	This character is arbitrary and specifies the first of two line break bytes. The second byte is always ' '.

◆ sc_io_file_load()

int sc_io_file_load	(	const char *	filename,
		sc_array_t *	buffer
	)

Read a file into a buffer in one call.

This function performs error checking and always returns cleanly.

Parameters

[in]	filename	Name of the file to load.
[in,out]	buffer	On input, an array (not a view) of element size 1 and arbitrary contents. On output and success, the complete file contents. On error, contents are undefined.

Returns: 0 on success, -1 on error.

◆ sc_io_file_save()

int sc_io_file_save	(	const char *	filename,
		sc_array_t *	buffer
	)

Save a buffer to a file in one call.

This function performs error checking and always returns cleanly.

Parameters

[in]	filename	Name of the file to save.
[in]	buffer	An array of element size 1 and arbitrary contents, which are written to the file.

Returns: 0 on success, -1 on error.

◆ sc_io_open()

int sc_io_open	(	sc_MPI_Comm	mpicomm,
		const char *	filename,
		sc_io_open_mode_t	amode,
		sc_MPI_Info	mpiinfo,
		sc_MPI_File *	mpifile
	)

Opens a MPI file or without MPI a file context.

Parameters

[in]	mpicomm	MPI communicator
[in]	filename	The path to the file that we want to open.
[in]	amode	An access mode.
[in]	mpiinfo	The MPI info
[out]	mpifile	The MPI file that is opened. This can be a an actual MPI IO file or an internal file conntext to preserve some IO functionalities without MPI IO and to have working code without MPI at all. This output variable is only filled if the return value of the function is sc_MPI_SUCCESS.

Returns: A sc_MPI_ERR_* as defined in sc_mpi.h. The error code can be passed to sc_MPI_Error_string. If the return value is not sc_MPI_SUCCESS, mpifile is not filled.

Note: This function does not exactly follow the MPI_File semantic in the sense that it truncates files to the length zero before overwriting them.

◆ sc_io_read()

void sc_io_read	(	sc_MPI_File	mpifile,
		void *	ptr,
		size_t	zcount,
		sc_MPI_Datatype	t,
		const char *	errmsg
	)

Read MPI file content into memory.

Parameters

[in,out]	mpifile	MPI file object opened for reading.
[out]	ptr	Data array to read in from disk.
[in]	zcount	Number of array members.
[in]	t	The MPI type for each array member.
[in]	errmsg	Error message passed to SC_CHECK_ABORT.

Note: This function aborts on MPI file and count errors. This function does not use the calling convention and error handling as the other sc_io MPI file functions to ensure backwards compatibility.; This function aborts if MPI I/O is not enabled.

◆ sc_io_read_at()

int sc_io_read_at	(	sc_MPI_File	mpifile,
		sc_MPI_Offset	offset,
		void *	ptr,
		int	count,
		sc_MPI_Datatype	t,
		int *	ocount
	)

Read MPI file content into memory for an explicit offset.

This function does not update the file pointer of the MPI file. Contrary to sc_io_read, it does not abort on read errors.

Parameters

[in,out]	mpifile	MPI file object opened for reading.
[in]	offset	Starting offset in counts of the type t.
[in]	ptr	Data array to read from disk.
[in]	count	Number of array members.
[in]	t	The MPI type for each array member.
[out]	ocount	The number of read elements of type t.

Returns: A sc_MPI_ERR_* as defined in sc_mpi.h. The error code can be passed to sc_MPI_Error_string.

◆ sc_io_read_at_all()

int sc_io_read_at_all	(	sc_MPI_File	mpifile,
		sc_MPI_Offset	offset,
		void *	ptr,
		int	count,
		sc_MPI_Datatype	t,
		int *	ocount
	)

Read MPI file content collectively into memory for an explicit offset.

This function does not update the file pointer of the MPI file.

Parameters

[in,out]	mpifile	MPI file object opened for reading.
[in]	offset	Starting offset in counts of the type t.
[in]	ptr	Data array to read from disk.
[in]	count	Number of array members.
[in]	t	The MPI type for each array member.
[out]	ocount	The number of read elements of type t.

Returns: A sc_MPI_ERR_* as defined in sc_mpi.h. The error code can be passed to sc_MPI_Error_string.

◆ sc_io_sink_align()

int sc_io_sink_align	(	sc_io_sink_t *	sink,
		size_t	bytes_align
	)

Align sink to a byte boundary by writing zeros.

Parameters

[in,out]	sink	The sink object to align.
[in]	bytes_align	Byte boundary.

Returns: 0 on success, nonzero on error.

◆ sc_io_sink_complete()

int sc_io_sink_complete	(	sc_io_sink_t *	sink,
		size_t *	bytes_in,
		size_t *	bytes_out
	)

Flush all buffered output data to sink.

This function may return SC_IO_ERROR_AGAIN if another write is required. Currently this may happen if BUFFER requires an integer multiple of bytes. If successful, the updated value of bytes read and written is returned in bytes_in/out, and the sink status is reset as if the sink had just been created. In particular, the bytes counters are reset to zero. The internal state of the sink is not changed otherwise. It is legal to continue writing to the sink hereafter. The sink actions taken depend on its type. BUFFER, FILEFILE: none. FILENAME: call fclose on sink->file.

Parameters

[in,out]	sink	The sink object to write to.
[in,out]	bytes_in	Bytes received since the last new or complete call. May be NULL.
[in,out]	bytes_out	Bytes written since the last new or complete call. May be NULL.

Returns: 0 if completed, nonzero on error.

◆ sc_io_sink_destroy()

int sc_io_sink_destroy ( sc_io_sink_t * sink )

Free data sink.

Calls sc_io_sink_complete and discards the final counts. Errors from complete lead to SC_IO_ERROR_FATAL returned from this function. Call sc_io_sink_complete yourself if bytes_out is of interest.

Parameters

[in,out] sink The sink object to complete and free.

Returns: 0 on success, nonzero on error.

◆ sc_io_sink_destroy_null()

int sc_io_sink_destroy_null ( sc_io_sink_t ** sink )

Free data sink and NULL the pointer to it.

Except for the handling of the pointer argument, the behavior is the same as for sc_io_sink_destroy.

Parameters

[in,out] sink Non-NULL pointer to sink pointer. The sink pointer may be NULL, in which case this function does nothing successfully, or a valid sc_io_sink, which is passed to sc_io_sink_destroy, and the sink pointer is set to NULL afterwards.

Returns: 0 on success, nonzero on error.

◆ sc_io_sink_new()

sc_io_sink_t* sc_io_sink_new	(	int	iotype,
		int	iomode,
		int	ioencode,
			...
	)

Create a generic data sink.

Parameters

[in]	iotype	Type must be a value from sc_io_type_t. Depending on iotype, varargs must follow: BUFFER: sc_array_t * (existing array). FILENAME: const char * (name of file to open). FILEFILE: FILE * (file open for writing). These buffers are only borrowed by the sink.
[in]	iomode	Mode must be a value from sc_io_mode_t. For type FILEFILE, data is always appended.
[in]	ioencode	Must be a value from sc_io_encode_t.

Returns: Newly allocated sink, or NULL on error.

◆ sc_io_sink_write()

int sc_io_sink_write	(	sc_io_sink_t *	sink,
		const void *	data,
		size_t	bytes_avail
	)

Write data to a sink.

Data may be buffered and sunk in a later call. The internal counters sink->bytes_in and sink->bytes_out are updated.

Parameters

[in,out]	sink	The sink object to write to.
[in]	data	Data passed into sink must be non-NULL.
[in]	bytes_avail	Number of data bytes passed in.

Returns: 0 on success, nonzero on error.

◆ sc_io_source_activate_mirror()

int sc_io_source_activate_mirror ( sc_io_source_t * source )

Activate a buffer that mirrors (i.e., stores) the data that was read.

Parameters

[in,out] source The source object to activate mirror in.

Returns: 0 on success, nonzero on error.

◆ sc_io_source_align()

int sc_io_source_align	(	sc_io_source_t *	source,
		size_t	bytes_align
	)

Align source to a byte boundary by skipping.

Parameters

[in,out]	source	The source object to align.
[in]	bytes_align	Byte boundary.

Returns: 0 on success, nonzero on error.

◆ sc_io_source_complete()

int sc_io_source_complete	(	sc_io_source_t *	source,
		size_t *	bytes_in,
		size_t *	bytes_out
	)

Determine whether all data buffered from source has been returned by read.

If it returns SC_IO_ERROR_AGAIN, another sc_io_source_read is required. If the call returns no error, the internal counters source->bytes_in and source->bytes_out are returned to the caller if requested, and reset to 0. The internal state of the source is not changed otherwise. It is legal to continue reading from the source hereafter.

Parameters

[in,out]	source	The source object to read from.
[in,out]	bytes_in	If not NULL and true is returned, the total size of the data sourced.
[in,out]	bytes_out	If not NULL and true is returned, total bytes passed out by source_read.

Returns: SC_IO_ERROR_AGAIN if buffered data remaining. Otherwise return ERROR_NONE and reset counters.

◆ sc_io_source_destroy()

int sc_io_source_destroy ( sc_io_source_t * source )

Free data source.

Calls sc_io_source_complete and requires it to return no error. This is to avoid discarding buffered data that has not been passed to read.

Parameters

[in,out] source The source object to free.

Returns: 0 on success. Nonzero if an error is encountered or is_complete returns one.

◆ sc_io_source_destroy_null()

int sc_io_source_destroy_null ( sc_io_source_t ** source )

Free data source and NULL the pointer to it.

Except for the handling of the pointer argument, the behavior is the same as for sc_io_source_destroy.

Parameters

[in,out] source Non-NULL pointer to source pointer. The source pointer may be NULL, in which case this function does nothing successfully, or a valid sc_io_source, which is passed to sc_io_source_destroy, and the source pointer is set to NULL afterwards.

Returns: 0 on success, nonzero on error.

◆ sc_io_source_new()

sc_io_source_t* sc_io_source_new	(	int	iotype,
		int	ioencode,
			...
	)

Create a generic data source.

Parameters

[in]	iotype	Type must be a value from sc_io_type_t. Depending on iotype, varargs must follow: BUFFER: sc_array_t * (existing array). FILENAME: const char * (name of file to open). FILEFILE: FILE * (file open for reading).
[in]	ioencode	Encoding value from sc_io_encode_t.

Returns: Newly allocated source, or NULL on error.

◆ sc_io_source_read()

int sc_io_source_read	(	sc_io_source_t *	source,
		void *	data,
		size_t	bytes_avail,
		size_t *	bytes_out
	)

Read data from a source.

The internal counters source->bytes_in and source->bytes_out are updated. Data is read until the data buffer has not enough room anymore, or source becomes empty. It is possible that data already read internally remains in the source object for the next call. Call sc_io_source_complete and check its return value to find out. Returns an error if bytes_out is NULL and less than bytes_avail are read.

Parameters

[in,out]	source	The source object to read from.
[in]	data	Data buffer for reading from source. If NULL the output data will be ignored and we seek forward in the input.
[in]	bytes_avail	Number of bytes available in data buffer.
[in,out]	bytes_out	If not NULL, byte count read into data buffer. Otherwise, requires to read exactly bytes_avail. If this condition is not met, return an error.

Returns: 0 on success, nonzero on error.

◆ sc_io_source_read_mirror()

int sc_io_source_read_mirror	(	sc_io_source_t *	source,
		void *	data,
		size_t	bytes_avail,
		size_t *	bytes_out
	)

Read data from the source's mirror.

Same behaviour as sc_io_source_read.

Parameters

[in,out]	source	The source object to read mirror data from.
[in]	data	Data buffer for reading from source's mirror. If NULL the output data will be thrown away.
[in]	bytes_avail	Number of bytes available in data buffer.
[in,out]	bytes_out	If not NULL, byte count read into data buffer. Otherwise, requires to read exactly bytes_avail.

Returns: 0 on success, nonzero on error.

◆ sc_io_write()

void sc_io_write	(	sc_MPI_File	mpifile,
		const void *	ptr,
		size_t	zcount,
		sc_MPI_Datatype	t,
		const char *	errmsg
	)

Write memory content to an MPI file.

Parameters

[in,out]	mpifile	MPI file object opened for writing.
[in]	ptr	Data array to write to disk.
[in]	zcount	Number of array members.
[in]	t	The MPI type for each array member.
[in]	errmsg	Error message passed to SC_CHECK_ABORT.

Note: This function aborts on MPI file and count errors. This function does not use the calling convention and error handling as the other sc_io MPI file functions to ensure backwards compatibility.; This function aborts if MPI I/O is not enabled.

◆ sc_io_write_at()

int sc_io_write_at	(	sc_MPI_File	mpifile,
		sc_MPI_Offset	offset,
		const void *	ptr,
		int	count,
		sc_MPI_Datatype	t,
		int *	ocount
	)

Write MPI file content into memory for an explicit offset.

This function does not update the file pointer that is part of mpifile. Contrary to sc_io_write, it does not abort on read errors.

Parameters

[in,out]	mpifile	MPI file object opened for reading.
[in]	offset	Starting offset in etype, where the etype is given by the type t.
[in]	ptr	Data array to write to disk.
[in]	count	Number of array members.
[in]	t	The MPI type for each array member.
[out]	ocount	The number of written elements of type t.

Returns: A sc_MPI_ERR_* as defined in sc_mpi.h. The error code can be passed to sc_MPI_Error_string.

◆ sc_io_write_at_all()

int sc_io_write_at_all	(	sc_MPI_File	mpifile,
		sc_MPI_Offset	offset,
		const void *	ptr,
		int	count,
		sc_MPI_Datatype	t,
		int *	ocount
	)

Write MPI file content collectively into memory for an explicit offset.

This function does not update the file pointer that is part of mpifile.

Parameters

[in,out]	mpifile	MPI file object opened for reading.
[in]	offset	Starting offset in etype, where the etype is given by the type t.
[in]	ptr	Data array to write to disk.
[in]	count	Number of array members.
[in]	t	The MPI type for each array member.
[out]	ocount	The number of written elements of type t.

Returns: A sc_MPI_ERR_* as defined in sc_mpi.h. The error code can be passed to sc_MPI_Error_string.

◆ sc_vtk_write_binary()

int sc_vtk_write_binary	(	FILE *	vtkfile,
		char *	numeric_data,
		size_t	byte_length
	)

This function writes numeric binary data in VTK base64 encoding.

Parameters

vtkfile	Stream opened for writing.
numeric_data	A pointer to a numeric data array.
byte_length	The length of the data array in bytes.

Returns: Returns 0 on success, -1 on file error.

◆ sc_vtk_write_compressed()

int sc_vtk_write_compressed	(	FILE *	vtkfile,
		char *	numeric_data,
		size_t	byte_length
	)

This function writes numeric binary data in VTK compressed format.

Parameters

vtkfile	Stream opened for writing.
numeric_data	A pointer to a numeric data array.
byte_length	The length of the data array in bytes.

Returns: Returns 0 on success, -1 on file error.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SC_CHECK_MPI_VERBOSE

Enumeration Type Documentation

◆ sc_io_encode_t

◆ sc_io_error_t

◆ sc_io_mode_t

◆ sc_io_open_mode_t

◆ sc_io_type_t

Function Documentation

◆ sc_fflush_fsync_fclose()

◆ sc_fopen()

◆ sc_fread()

◆ sc_fwrite()

◆ sc_io_close()

◆ sc_io_decode()

◆ sc_io_decode_info()

◆ sc_io_encode()

◆ sc_io_encode_zlib()

◆ sc_io_file_load()

◆ sc_io_file_save()

◆ sc_io_open()

◆ sc_io_read()

◆ sc_io_read_at()

◆ sc_io_read_at_all()

◆ sc_io_sink_align()

◆ sc_io_sink_complete()

◆ sc_io_sink_destroy()

◆ sc_io_sink_destroy_null()

◆ sc_io_sink_new()

◆ sc_io_sink_write()

◆ sc_io_source_activate_mirror()

◆ sc_io_source_align()

◆ sc_io_source_complete()

◆ sc_io_source_destroy()

◆ sc_io_source_destroy_null()

◆ sc_io_source_new()

◆ sc_io_source_read()

◆ sc_io_source_read_mirror()

◆ sc_io_write()

◆ sc_io_write_at()

◆ sc_io_write_at_all()

◆ sc_vtk_write_binary()

◆ sc_vtk_write_compressed()