#include <stdarg.h>
#include <stdio.h>
#include "gromacs/utility/basedefinitions.h"

Include dependency graph for fatalerror.h:

This graph shows which files directly or indirectly include this file:

Description

Declares fatal error handling and debugging routines for C code.

Macros
#define	where() _where(__FILE__, __LINE__)
	Prints filename and line to stdlog. More...

#define	FARGS 0, __FILE__, __LINE__
	Helper macro to pass first three parameters to gmx_fatal(). More...

#define	gmx_error(key, msg) _gmx_error(key, msg, __FILE__, __LINE__)
	Alternative fatal error routine with canned messages. More...

#define	range_check_mesg(n, n_min, n_max, str) _range_check(n, n_min, n_max, str,#n, __FILE__, __LINE__)
	Checks that a variable is within a range. More...

#define	range_check(n, n_min, n_max) _range_check(n, n_min, n_max, NULL,#n, __FILE__, __LINE__)
	Checks that a variable is within a range. More...

Fatal error routines for certain types of errors
These wrap gmx_error() and provide the `key` parameter as one of the recognized strings.
#define	gmx_call(msg) gmx_error("call", msg)

#define	gmx_comm(msg) gmx_error("comm", msg)

#define	gmx_file(msg) gmx_error("file", msg)

#define	gmx_impl(msg) gmx_error("impl", msg)

#define	gmx_incons(msg) gmx_error("incons", msg)

#define	gmx_input(msg) gmx_error("input", msg)

#define	gmx_mem(msg) gmx_error("mem", msg)

#define	gmx_open(fn) gmx_error("open", fn)

Typedefs
typedef void(*	gmx_error_handler_t )(const char title, const char msg, const char *file, int line)
	Function pointer type for fatal error handler callback. More...

Enumerations
enum	ExitType { ExitType_CleanExit, ExitType_Abort, ExitType_NonMasterAbort }
	Identifies the state of the program on a fatal error. More...

Functions
void	gmx_init_debug (const int dbglevel, const char *dbgfile)
	Initializes debugging variables. More...

gmx_bool	bDebugMode (void)
	Returns TRUE when the program was started in debug mode.

void	_where (const char *file, int line)
	Implementation for where(). More...

void	gmx_fatal_set_log_file (FILE *fp)
	Sets the log file for printing error messages. More...

void	gmx_set_error_handler (gmx_error_handler_t func)
	Sets an error handler for gmx_fatal() and other fatal error routines. More...

void	gmx_exit_on_fatal_error (enum ExitType exitType, int returnValue)
	Helper function to terminate the program on a fatal error. More...

void	gmx_fatal_mpi_va (int fatal_errno, const char file, int line, gmx_bool bMaster, gmx_bool bFinalize, const char fmt, va_list ap)
	Low-level fatal error reporting routine for collective MPI errors. More...

void	gmx_fatal (int fatal_errno, const char file, int line, const char fmt,...)
	Fatal error reporting routine for GROMACS. More...

void	_gmx_error (const char key, const char msg, const char *file, int line)
	Implementation for gmx_error(). More...

void	_range_check (int n, int n_min, int n_max, const char warn_str, const char var, const char *file, int line)
	Implementation for range_check() and range_check_mesg(). More...

void	gmx_warning (const char *fmt,...)
	Prints a warning message to stderr. More...

Variables
FILE *	debug
	Debug log file. More...

gmx_bool	gmx_debug_at
	Whether extra debugging is enabled. More...

Macro Definition Documentation

#define FARGS 0, __FILE__, __LINE__

Helper macro to pass first three parameters to gmx_fatal().

#define gmx_error	(	key,
		msg
	)	_gmx_error(key, msg, __FILE__, __LINE__)

Alternative fatal error routine with canned messages.

This works as gmx_fatal(), except that a generic error message is added based on a string key, and printf-style formatting is not supported. Should not typically be called directly, but through gmx_call() etc.

#define range_check	(	n,
		n_min,
		n_max
	)	_range_check(n, n_min, n_max, NULL,#n, __FILE__, __LINE__)

Checks that a variable is within a range.

This works as range_check_mesg(), but with a default error message.

#define range_check_mesg	(	n,
		n_min,
		n_max,
		str
	)	_range_check(n, n_min, n_max, str,#n, __FILE__, __LINE__)

Checks that a variable is within a range.

If n is not in range [n_min, n_max), a fatal error is raised. n_min is inclusive, but n_max is not.

#define where ( ) _where(__FILE__, __LINE__)

Prints filename and line to stdlog.

Typedef Documentation

typedef void(* gmx_error_handler_t)(const char *title, const char *msg, const char *file, int line)

Function pointer type for fatal error handler callback.

Enumeration Type Documentation

enum ExitType

Identifies the state of the program on a fatal error.

Enumerator

ExitType_CleanExit

Clean exit is possible.

There should be no concurrently executing code that might be accessing global objects, and all MPI ranks should reach the same fatal error.

ExitType_Abort

Program needs to be aborted.

There are no preconditions for this state.

ExitType_NonMasterAbort

Program needs to be aborted, but some other rank is responsible of it.

There should be some other MPI rank that reaches the same fatal error, but uses ExitType_Abort. The other ranks can then use ExitType_NonMasterAbort to wait for that one rank to issue the abort.

Function Documentation

void _gmx_error	(	const char *	key,
		const char *	msg,
		const char *	file,
		int	line
	)

Implementation for gmx_error().

void _range_check	(	int	n,
		int	n_min,
		int	n_max,
		const char *	warn_str,
		const char *	var,
		const char *	file,
		int	line
	)

Implementation for range_check() and range_check_mesg().

warn_str can be NULL.

void _where	(	const char *	file,
		int	line
	)

Implementation for where().

void gmx_exit_on_fatal_error	(	enum ExitType	exitType,
		int	returnValue
	)

Helper function to terminate the program on a fatal error.

Parameters

[in]	exitType	Identifies the state of the program at the time of the call, determining how the program can be terminated.
[in]	returnValue	Exit code for the program, for cases where it can be used.

void gmx_fatal	(	int	fatal_errno,
		const char *	file,
		int	line,
		const char *	fmt,
			...
	)

Fatal error reporting routine for GROMACS.

This function prints a fatal error message with a header that contains the source file and line number of the call, followed by the string specified by fmt and supplied parameters. If fatal_errno is 0, only the message and arguments are printed. If fatal_errno is a legal system errno or -1, a perror()-like message is printed after the first message; if fatal_errno is -1, the last system errno will be used. The format of fmt uses printf()-like formatting.

In case all MPI processes want to stop with the same fatal error, use gmx_fatal_collective(), declared in network.h, to avoid having as many error messages as processes.

The first three parameters can be provided through FARGS:

gmx_fatal(FARGS, fmt, ...);

void gmx_fatal_mpi_va	(	int	fatal_errno,
		const char *	file,
		int	line,
		gmx_bool	bMaster,
		gmx_bool	bFinalize,
		const char *	fmt,
		va_list	ap
	)

Low-level fatal error reporting routine for collective MPI errors.

This function works as gmx_fatal(), but provides additional control for cases where it is known that the same error occurs on multiple MPI ranks. The error handler is called only if bMaster is TRUE, and MPI_Finalize() is called instead of MPI_Abort() in MPI-enabled GROMACS if bFinalize is TRUE.

This is used to implement gmx_fatal_collective() (which cannot be declared here, since it would bring with it mdrun-specific dependencies).

void gmx_fatal_set_log_file ( FILE * fp )

Sets the log file for printing error messages.

void gmx_init_debug	(	const int	dbglevel,
		const char *	dbgfile
	)

Initializes debugging variables.

This function is not threadsafe. It should be called as part of initializing GROMACS, before any other thread accesses the library. For command line programs, gmx::CommandLineModuleManager takes care of this if the user requests debugging.

void gmx_set_error_handler ( gmx_error_handler_t func )

Sets an error handler for gmx_fatal() and other fatal error routines.

The default handler prints the message. GROMACS will terminate the program after the error handler returns. To make gmx_fatal_collective() work, the error handler should not terminate the program, as it cannot know what is the desired way of termination. The message passed to the handler may be a multi-line string.

See Also: gmx_fatal()

void gmx_warning	(	const char *	fmt,
			...
	)

Prints a warning message to stderr.

The format of fmt uses printf()-like formatting. The message string should NOT start with "WARNING" and should NOT end with a newline.

Variable Documentation

FILE* debug

Debug log file.

Functions can write to this file for debug info. Before writing to it, it should be checked whether the file is not NULL:

if (debug)
{
    fprintf(debug, "%s", "Debug text");
}

gmx_bool gmx_debug_at

Whether extra debugging is enabled.

Description

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation