Detailed Description

Errors can occur inside the MeatAxe library for many reasons:

insufficient system resources (memory, disk space),
device or operating system failure,
invalid parameters passed to a MeatAxe library function,
invalid usage of MeatAxe library functions, for example missing initialization, etc.

Note that invalid parameters are not always detected by the MeatAxe library. For example, most kernel functions such as FfAdd() do not check their arguments for the sake of performance. Thus, calling these function with invalid arguments may produce random results or even crash the program. However, most higher-level functions do some plausibility checks on their arguments before processing them.

When an error is detected, some variant of MtxError() is called, which extracts information on where and why the error occurred, and calls an error handler with that information. The default error handler just terminates the program with an appropriate error message. But code linked against libmtx.so can of course define a custom error handler.

In SharedMeatAxe 1.0, as opposed to MeatAxe 2.4.24, most higher level functions return a specific value in the case of an error, and they propagate these error values. It thus makes sense for a MeatAxe application to define a custom error handler that stores the information provided by MtxError(), and then check whether a called library function returns an error value; if it does, the application can deal with the error based on the data stored by the error handler.

How to use the error handling framework

Each source file which uses the MeatAxe error mechanism, i.e., MtxError() or any of the MTX_ERROR() macros, must also define one MtxFileInfo_t structure at file scope. This is most conveniently done by putting the MTX_DEFINE_FILE_INFO macro into the file.

Here is a short example:

#include "meataxe.h"
MTX_DEFINE_FILE_INFO
int divide(int a, int b)
{
    if (b == 0)
    {
      MTX_ERROR("Division by 0");
      return 0;
    }
    return a / b;
}

Note that you must not assume that MTX_ERROR terminates the program. Thus, if another function calls divide(a,b), which returns 0, then it is possible that an error has occurred. Hence, the callee needs to check whether there is an error or not, and eventually return its own error value.

See also: MtxError MtxErrorRecord_t MTX_DEFINE_FILE_INFO

Data Structures
struct	MtxFileInfo_t
	File information. More...

struct	MtxErrorRecord_t
	Run-time errors. More...

struct	msg_struct
	Internal data structure.

Macros
#define	MTX_ERR_NOMEM 1
	Not enough memory.

#define	MTX_ERR_GAME_OVER 2
	Time limit exceeded.

#define	MTX_ERR_DIV0 8
	Division by 0 or singular Matrix.

#define	MTX_ERR_FILEFMT 24
	Bad format.

#define	MTX_ERR_BADARG 31
	Bad argument.

#define	MTX_ERR_RANGE 33
	Out of range.

#define	MTX_ERR_NOTECH 34
	Matrix not in chelon form.

#define	MTX_ERR_NOTSQUARE 35
	Matrix not square.

#define	MTX_ERR_INCOMPAT 36
	Arguments are incompatible.

#define	MTX_ERR_BADUSAGE 41
	Bad command line.

#define	MTX_ERR_OPTION 42
	Bad usage of option.

#define	MTX_ERR_NARGS 43
	Bad number of arguments.

#define	MTX_ERR_NOTMATRIX 51
	Not a matrix.

#define	MTX_ERR_NOTPERM 53
	Not a permutation.

#define	MTX_DEFINE_FILE_INFO static MtxFileInfo_t Mtx_ThisFile = { __FILE__, NULL };
	This macro must be included in each source file that uses the MeatAxe error reporting mechanism. More...

Typedefs
typedef void	MtxErrorHandler_t(const MtxErrorRecord_t *)
	Error handlers. More...

Functions
MtxErrorHandler_t *	MtxSetErrorHandler (MtxErrorHandler_t *h)
	Define an error handler. More...

int	MtxError (MtxFileInfo_t fi, int line, const char text,...)
	Signal an error. More...

int	MtxFormatMessage (char buf, int bufsize, const char msg, va_list al)
	Format a message. More...

int	MtxPrintMessage (FILE f, const char fmt,...)
	Print a message. More...

Variables
int	MtxMessageLevel
	Message level. More...

int	MtxMessageLevel = 0
	Message level. More...

int	MtxErrNo = 0
	Last error code.

Macro Definition Documentation

MTX_DEFINE_FILE_INFO static MtxFileInfo_t Mtx_ThisFile = { __FILE__, NULL };

This macro must be included in each source file that uses the MeatAxe error reporting mechanism.

It defines a data structure of type MtxFileInfo_t that is used by the error reporting macros

See also: MtxError

Typedef Documentation

typedef void MtxErrorHandler_t(const MtxErrorRecord_t *)

Error handlers.

See also: MtxSetErrorHandler MtxErrorRecord_t

Function Documentation

int MtxError	(	MtxFileInfo_t *	fi,
		int	line,
		const char *	text,
			...
	)

Signal an error.

This function is used to report errors. The current error handler is executed- The default handler just writes an error message to the error log file (stderr by default) and terminates the program.

The error message, text, is formatted with MtxFormatMessage().

Parameters

fi	Pointer to a file information structure.
line	Line number where the error occurred.
text	Error description.
...	Optional arguments to be inserted into the error description.

Returns: The return value is always 0.

int MtxFormatMessage	(	char *	buf,
		int	bufsize,
		const char *	msg,
		va_list	al
	)

Format a message.

This function formats a message using a |printf|-like syntax. Only the follwing four format codes may be used within |msg|:

%d prints a signed decimal integer. The corresponding argument must be of type int.
%s prints a string. The corresponding argument must be a pointer to a null-terminated string.
%E takes an int argument, which must be one the MeatAxe error codes (MTX_ERR_xxxx) defined in "meataxe.h". It prints a description of the error.
%S prints the system error name corresponding to the current value of errno.

Parameters

buf	Buffer for the message.
bufsize	Size of buffer.
msg	The message text.
al	Optional arguments for the message (see description).

int MtxPrintMessage	(	FILE *	f,
		const char *	fmt,
			...
	)

Print a message.

This function writes a message to a file using a printf()-like syntax. See MtxFormatMessage() for details.

Parameters

f	File to write to.
fmt	Message to write
...	Optional arguments for the message.

MtxErrorHandler_t * MtxSetErrorHandler ( MtxErrorHandler_t * h )

Define an error handler.

This function defines an error handler that is called every time an error occurs inside libmtx.so.

Parameters

h	Pointer to the new error handler or NULL to restore the default handler.

Returns: Returns the previous error handler.

See also: MtxErrorRecord_t MtxErrorHandler_t

Variable Documentation

int MtxMessageLevel = 0

Message level.

This value determines which messages generated by MSG0()...MSG4() are actually output and which are suppressed.

int MtxMessageLevel

Message level.

This value determines which messages generated by MSG0()...MSG4() are actually output and which are suppressed.

Detailed Description

How to use the error handling framework

Data Structures

Macros

Typedefs

Functions

Variables

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation