bool	gwyfile_write_file (GwyfileObject object, const char filename, GwyfileError **error)
	Writes a GWY file to a named file. More...

GwyfileObject *	gwyfile_read_file (const char filename, GwyfileError *error)
	Reads a GWY file from a named file and returns its top-level object. More...

bool	gwyfile_fwrite (GwyfileObject object, FILE stream, GwyfileError **error)
	Writes a GWY file to a stdio stream. More...

GwyfileObject *	gwyfile_fread (FILE stream, size_t max_size, GwyfileError *error)
	Reads a GWY file from a stdio stream and returns the top-level object. More...

bool	gwyfile_write_wfile (GwyfileObject object, const wchar_t filename, GwyfileError **error)
	Writes a GWY file to a named file (wide-character variant). More...

GwyfileObject *	gwyfile_read_wfile (const wchar_t filename, GwyfileError *error)
	Reads a GWY file from a named file and returns its top-level object (wide-character variant). More...

Detailed Description

Function Documentation

◆ gwyfile_fread()

GwyfileObject* gwyfile_fread	(	FILE *	stream,
		size_t	max_size,
		GwyfileError **	error
	)

Reads a GWY file from a stdio stream and returns the top-level object.

This function differs from gwyfile_object_fread() only by reading and checking the magic file header that preceeds the top-level object in a GWY file.

The stream does not have to be seekable. This makes the function useful for reading GWY files from pipes and the standard input. Otherwise it is usually easier to use gwyfile_read_file().

On success, the position indicator in stream will be pointed after the end of the top-level object.

On failure, the position indicator state in stream is undefined.

The maximum number of bytes to read is given by max_size which is of type size_t, however, be aware that sizes in GWY files are only 32bit. So any value that does not fit into a 32bit integer means the same as SIZE_MAX.

If reading more than max_size bytes would be required to reconstruct the top-level object, the function fails with GWYFILE_ERROR_TRUNCATED error in the GWYFILE_ERROR_DOMAIN_DATA domain.

Parameters

stream	C stdio stream to read the GWY file from.
max_size	Maximum number of bytes to read. Pass `SIZE_MAX` for unconstrained reading.
error	Location for the error (or `NULL`).

Returns: The reconstructed top-level data object, or NULL if the reading or reconstruction fails.

Examples: checkgeneric.c, readgeneric.c, and readgwy.c.

◆ gwyfile_fwrite()

bool gwyfile_fwrite	(	GwyfileObject *	object,
		FILE *	stream,
		GwyfileError **	error
	)

Writes a GWY file to a stdio stream.

This function differs from gwyfile_object_fwrite() only by adding the magic file header that preceeds the top-level object in a GWY file.

The stream does not have to be seekable. This makes the function useful for writing GWY files to pipes and the standard output. Otherwise it is usually easier to use gwyfile_write_file().

Parameters

object	The top-level GWY file data object for the file. Normally it is a GwyContainer.
stream	C stdio stream to write the GWY file to.
error	Location for the error (or `NULL`).

Returns: true if the writing succeeded.

◆ gwyfile_read_file()

GwyfileObject* gwyfile_read_file	(	const char *	filename,
		GwyfileError **	error
	)

Reads a GWY file from a named file and returns its top-level object.

This function handles opening and closing of the file for you, otherwise it is very similar to gwyfile_fread().

The file name is passed to the system fopen() function as given. You may want to consider using gwyfile_read_wfile() or opening the file yourself and using gwyfile_fread() in MS Windows.

Parameters

filename	Name of the file to write the GWY file to.
error	Location for the error (or `NULL`).

Returns: The reconstructed top-level data object, or NULL if the reading or reconstruction fails.

Examples: checkgeneric.c, readgeneric.c, and readgwy.c.

◆ gwyfile_read_wfile()

GwyfileObject* gwyfile_read_wfile	(	const wchar_t *	filename,
		GwyfileError **	error
	)

Reads a GWY file from a named file and returns its top-level object (wide-character variant).

Note: This function is available only in MS Windows.

This function is completely identical to gwyfile_read_file() aside from using _wfopen() to open the file instead of fopen(). There is no difference in handling of the file data itself.

Parameters

filename	Name of the file to write the GWY file to.
error	Location for the error (or `NULL`).

Returns: The reconstructed top-level data object, or NULL if the reading or reconstruction fails.

◆ gwyfile_write_file()

bool gwyfile_write_file	(	GwyfileObject *	object,
		const char *	filename,
		GwyfileError **	error
	)

Writes a GWY file to a named file.

The file will be overwritten if it exists.

This function handles opening and closing of the file for you, otherwise it is very similar to gwyfile_fwrite().

If an I/O error occurs during writing the partially written file is kept, i.e. it is not removed.

The file name is passed to the system fopen() function as given. You may want to consider using gwyfile_read_wfile() or opening the file yourself and using gwyfile_fread() in MS Windows.

Parameters

object	The top-level GWY file data object for the file. Normally it is a GwyContainer.
filename	Name of the file to write the GWY file to.
error	Location for the error (or `NULL`).

Returns: true if the writing succeeded.

◆ gwyfile_write_wfile()

bool gwyfile_write_wfile	(	GwyfileObject *	object,
		const wchar_t *	filename,
		GwyfileError **	error
	)

Writes a GWY file to a named file (wide-character variant).

Note: This function is available only in MS Windows.

This function is completely identical to gwyfile_write_file() aside from using _wfopen() to open the file instead of fopen(). There is no difference in handling of the file data itself.

Parameters

object	The top-level GWY file data object for the file. Normally it is a GwyContainer.
filename	Name of the file to write the GWY file to.
error	Location for the error (or `NULL`).

Returns: true if the writing succeeded.