Error reporting¶

error codes¶

The error code should be seen as an error class that describes roughly the type of error encountered. Depending on their context, some layer can handle a specific error reported by their callee (maybe raised in much lower layer). It will thus use the code to filter the error it handle and propagate to the upper layers the others.

mmlib defines a number of error in addition to the usual one defined in errno.h by the system to address the case not covered by the system error. In the following table, you will find the list of typical error that you will most likely use (or receive)

EINVAL:: Invalid argument. This is used to indicate various kinds of problems with passing the wrong argument to a library function.
ENOSYS:: Function not implemented. This indicates that the function called is not implemented at all, either in the C library, in the operating system or in a library (typically you try to access a set of functionality that are disabled by a compilation flag). When you get this error, you can be sure that this particular function will always fail with ENOSYS unless you install a new version of the operating system.
ENOTSUP:: Not supported. A function returns this error when certain parameter values are valid, but the functionality they request is not available. This can mean that the function does not implement a particular command or option value or flag bit at all. For functions that operate on some object given in a parameter, such as a file descriptor or a port, it might instead mean that only that specific object (file descriptor, port, etc.) is unable to support the other parameters given; different file descriptors might support different ranges of parameter values. If the entire function is not available at all in the implementation, it returns ENOSYS instead.
ETIMEDOUT:: An operation with a specified timeout received no response during the timeout period.
EPIPE:: Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a SIGPIPE signal; this signal terminates the program if not handled or blocked. Thus, your program will never actually see EPIPE unless it has handled or blocked SIGPIPE.
ENOENT:: No such file or directory. This is a “file doesn’t exist” error for ordinary files that are referenced in contexts where they are expected to already exist.
EACCES:: Permission denied; the file permissions do not allow the attempted operation.
ERANGE:: Insufficient storage was supplied to contain the data.
EBUSY:: Resource busy; a resource that can’t be shared is already in use.
EIO:: Input/output error; usually used for physical read or write errors.
MM_EDISCONNECTED:: Hardware is disconnected or turned off
MM_ENOTFOUND:: An entity that are requested cannot be found.
MM_EBADFMT:: The format of a file or data is not the one expected.
MM_NONAME:: The specified hostname cannot be resolved

mm_raise_error¶

#include <mmerrno.h>

mm_raise_error(errnum, …)¶

set and log an error

Parameters:	errnum – error class number ellipsis (ellipsis) – variable arguments

Description¶

mm_raise_error() takes an extensible number of arguments (printf-like) and usually receives one string describing the issue.

Set the state of an error in the running thread. If errnum is 0, the thread error state will kept untouched.

Although this can be used like a function, this is a macro which will enrich the error state with the origin of the error (module, function, source code file and line number).

This must be called the closest place where the error is detected. Ie, if you call a function that sets an error, you should not raise an error yourself, because your callee has failed and done so already, the only thing that might be done in this case would be adding a log line (if necessary). On the other side, if you call function from third party, the error state will of course not be set, it will then be your responsibility once you detect the third-party call has failed to set the error state using mm_raise_error().

Return¶

always -1.

mm_raise_error_with_extid¶

#include <mmerrno.h>

mm_raise_error_with_extid(errnum, extid, …)¶

set and log an error with an extended error id

Parameters:	errnum – error class number extid – extended error id (identifier of a specific error case) ellipsis (ellipsis) – variable arguments

Description¶

Same as with mm_raise_error(), this accepts an extensible number of arguments.

Same as mm_raise_error() with an extended error id set to extid. If extid is NULL, the effect is exactly the same as calling mm_raise_error().

An extended error id is a string identifier that is meant to inform the layer that interact with the enduser (like therapist) about the reason of the error. With this identifier, the UI layer can display a error message that makes sense to the end user. Example, the cameralink camera can detect a HW problem due to ESD. When this happens, the acquisition driver will set an hardware error class (like MM_ECAMERROR) with an extid set to “clcam-esd-detected”. The UI of the final product will recognise the extended identifier and display to the appropriate message (with the right language) that make sense in the context of the usage of the product and maybe what the enduser has to do.

Return¶

always -1.

mm_strerror¶

#include <mmerrno.h>

const char* mm_strerror(int errnum)¶

Get description for error code

Parameters:	errnum (int) – error to describe

Description¶

This function maps the error number in errnum to a locale-dependent error message string and return a pointer to it.

mm_strerror() function is not be thread-safe. The application must not modify the string returned. The returned string pointer might be invalidated or the string content might be overwritten by a subsequent call to mm_strerror(), strerror(), or by subsequent call to strerror_l() in the same thread.

Return¶

pointer to the generated message string.

mm_strerror_r¶

#include <mmerrno.h>

int mm_strerror_r(int errnum, char * buf, size_t buflen)¶

Get description for error code (reentrant)

Parameters:	errnum (int) – error to describe buf (char ) – buffer to which the description should be written buflen* (size_t) – buffer size of `buf`

Return¶

0 is in case of success, -1 otherwise.

mm_error_set_flags¶

#include <mmerrno.h>

int mm_error_set_flags(int flags, int mask)¶

set the error reporting behavior

Parameters:	flags (int) – the flags to add mask (int) – mask applied on the flags

Description¶

This function allows to modify the behavior when an error is raised with mm_raise_error() and similar function. Normally when an error is raised, the usual behavior is to set the error and its details in a thread local variable (error state) and to log it. The aspect of this behavior can be modified depending on mask which must be an OR-combination of the following flags :

MM_ERROR_IGNORE: error are silently ignored… Thread error state will not be changed and no log will be produced.
MM_ERROR_NOLOG: log will not be produced when an error is raised.

The aspect of the error raising behavior is controlled by the flags set in flags combined with mask. In other words, the aspect of behavior mentioned in the previous list is modified if the corresponding bit is set in mask and the alternate behavior is respectively used or not depending on the corresponding bit is set or not in flags. If a bit is unset in mask, the same behavior is kept as before the call to mm_error_set_flags(). MM_ERROR_ALL_ALTERNATE is defined to modify all possible behavior aspect.

The return variable can be used to restore the previous state.

For example use previous = mm_error_set_flags(MM_ERROR_SET, MM_ERROR_NOLOG) to stop logging errors. The previous variable will contain the original flag variable state, which can then be restored using mm_error_set_flags(previous, MM_ERROR_NOLOG).

Return¶

the previous state flags

mm_raise_error_vfull¶

#include <mmerrno.h>

int mm_raise_error_vfull(int errnum, const char* module, const char* func, const char* srcfile, int srcline, const char* extid, const char* desc_fmt, va_list args)¶

set and log an error using a va_list

Parameters:

errnum (int) – error class number
module (const char*) – module name
func (const char*) – function name at the origin of the error
srcfile (const char*) – filename of source code at the origin of the error
srcline (int) – line number of file at the origin of the error
extid (const char*) – extended error id (identifier of a specific error case)
desc_fmt (const char*) – description intended for developer (vprintf-like extensible)
args (va_list) – va_list of arguments for desc

Description¶

Exactly the same as mm_raise_error_full() but using a va_list to pass argument to the format passed in desc.

Return¶

always -1.

mm_raise_error_full¶

#include <mmerrno.h>

int mm_raise_error_full(int errnum, const char* module, const char* func, const char* srcfile, int srcline, const char* extid, const char* desc_fmt, ...)¶

set and log an error (function backend)

Parameters:

errnum (int) – error class number
module (const char*) – module name
func (const char*) – function name at the origin of the error
srcfile (const char*) – filename of source code at the origin of the error
srcline (int) – line number of file at the origin of the error
extid (const char*) – extended error id (identifier of a specific error case)
desc_fmt (const char*) – description intended for developer (printf-like extensible)
ellipsis (ellipsis) – variable arguments

Description¶

This function is the actual function invoked by the mm_raise_error() and mm_raise_error_with_extid() macros. You are advised to use the macros instead unless you want to build your own wrapper.

Return¶

always -1.

mm_raise_from_errno_full¶

#include <mmerrno.h>

int mm_raise_from_errno_full(const char* module, const char* func, const char* srcfile, int srcline, const char* extid, const char* desc_fmt, ...)¶

set and log an error (function backend)

Parameters:

module (const char*) – module name
func (const char*) – function name at the origin of the error
srcfile (const char*) – filename of source code at the origin of the error
srcline (int) – line number of file at the origin of the error
extid (const char*) – extended error id (identifier of a specific error case)
desc_fmt (const char*) – description intended for developer (printf-like extensible)
ellipsis (ellipsis) – variable arguments

Description¶

This function is the actual function invoked by the mm_raise_from_errno() macro. You are advised to use the macros instead unless you want to build your own wrapper.

Return¶

always -1.

mm_save_errorstate¶

#include <mmerrno.h>

int mm_save_errorstate(struct mm_error_state* state)¶

Save the error state on an opaque data holder

Parameters:	state (struct mm_error_state*) – data holder of the error state

Description¶

Use this function to save the current error state to data holder pointed by state. The content of state may be copied around even between threads and different processes.

Return¶

0 (cannot fail)

The reciprocal of this function is mm_set_errorstate().

mm_set_errorstate¶

#include <mmerrno.h>

int mm_set_errorstate(const struct mm_error_state* state)¶

Save the error state of the calling thread

Parameters:	state (const struct mm_error_state*) – pointer to the data holding of the error state

Description¶

Use this function to restore the error state of the calling thread from the information pointed by state. Combined with mm_save_errorstate(), you may :

handle an error from a called function and recover the error state before the failed function
copy the error state of a failed function whose call may have been offloaded to a different thread or even different process

The reciprocal of this function is mm_save_errorstate().

Return¶

0 (cannot fail)

mm_print_lasterror¶

#include <mmerrno.h>

void mm_print_lasterror(const char* info, ...)¶

display last error info on standard output

Parameters:	info (const char) – string describing the context where the error has been encountered. It can be enriched by variable argument in the printf-like style. It may be NULL, in such a case, only the error state is described. ellipsis* (ellipsis) – variable arguments

mm_get_lasterror_number¶

#include <mmerrno.h>

int mm_get_lasterror_number(void)¶

get error number of last error in the thread

Parameters:	void – no arguments

Return¶

the error number (0 if no error has been set in the thread)

mm_get_lasterror_desc¶

#include <mmerrno.h>

const char* mm_get_lasterror_desc(void)¶

get error description of last error in thread

Parameters:	void – no arguments

Return¶

the error description (“” if no error)

mm_get_lasterror_location¶

#include <mmerrno.h>

const char* mm_get_lasterror_location(void)¶

get file location of last error in the thread

Parameters:	void – no arguments

Return¶

the file location that is at the origin of the error in the format “filename:linenum” (“” if no error)

mm_get_lasterror_extid¶

#include <mmerrno.h>

const char* mm_get_lasterror_extid(void)¶

get error extended id of last error in the thread

Parameters:	void – no arguments

Description¶

This function provides the extended id of the last error set in the calling thread. The extended id is a string identifier destinated for the UI layer of the software stack to identify a error specific situation(See explanation in mm_raise_error_with_extid()).

Please note that not all error report are supposed to report an error extended id (they actually should be a minority). If none has been provided when the last error has been set, the extid provided by this function will be NULL.

Return¶

the error extended id if one has been set by the last error, NULL otherwise.

mm_get_lasterror_module¶

#include <mmerrno.h>

const char* mm_get_lasterror_module(void)¶

module at the source the last error in the thread

Parameters:	void – no arguments

Return¶

the module name that is at the origin of the error (“” if no error)

Error reporting¶

error codes¶

mm_raise_error¶

Description¶

Return¶

mm_raise_error_with_extid¶

Description¶

Return¶

See also¶

mm_strerror¶

Description¶

Return¶

See also¶

mm_strerror_r¶

Return¶

mm_error_set_flags¶

Description¶

Return¶

See also¶

mm_raise_error_vfull¶

Description¶

Return¶

See also¶

mm_raise_error_full¶

Description¶

Return¶

See also¶

mm_raise_from_errno_full¶

Description¶

Return¶

See also¶

mm_save_errorstate¶

Description¶

Return¶

mm_set_errorstate¶

Description¶

Return¶

See also¶

mm_print_lasterror¶

mm_get_lasterror_number¶

Return¶

mm_get_lasterror_desc¶

Return¶

mm_get_lasterror_location¶

Return¶

mm_get_lasterror_extid¶

Description¶

Return¶

See also¶

mm_get_lasterror_module¶

Return¶