<-- Back to AG_Intro.3

SYNOPSIS

#define _USE_AGAR_STD /* If macros without AG_ prefix are desired */
#include <agar/core.h>

DESCRIPTION

This manual page describes the error handling system which is used by all Agar libraries, and available to applications as well.

ERROR RETURNS

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

void AG_SetErrorV (const char *code, const char *msg)

const char * AG_GetError (void)

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

void AG_FatalErrorV (const char *code, const char *message)

void AG_SetFatalCallback (void (*callback)(const char *msg))

const char * AG_Strerror (int errno)

AG_SetError() sets the global error message text from the given printf(3) like format string. The AG_SetErrorV() variant is a macro which expands to msg if Agar was built with AG_VERBOSITY, otherwise it expands to the shortened code code.

AG_GetError() returns the error message string last set by AG_SetError().

Note: If Agar was compiled with THREADS support then the error message text buffer is contained in thread-local storage.

The AG_FatalError() function outputs the given error message to the user and causes abnormal termination of the program. The AG_FatalErrorV() variant is a macro which expands to msg if Agar was built with AG_VERBOSITY, otherwise it expands to the shortened code code.

AG_SetFatalCallback() function sets a user provided callback to be called by AG_FatalError() instead of simply terminating the process. The callback is expected to do program-specific cleanup and then terminate the program itself. An error message is passed to the callback via the msg argument.

The AG_Strerror() function returns an error message for the given platform-specific error code (e.g., on POSIX platforms, the argument should be a valid errno(2) value).

DEBUG ROUTINES

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

void AG_Debug (AG_Object *obj, const char *fmt, ...)

void AG_SetVerboseCallback (int (*fn)(const char *msg))

void AG_SetDebugCallback (int (*fn)(const char *msg))

These functions output a string to the debugging console used by the application (usually stdio(3)).

AG_Verbose() outputs a string if the global agVerbose variable is set.

The AG_Debug() function outputs a string on the debugging console of obj, assuming the object either has the AG_OBJECT_DEBUG flag set, or the global agDebugLvl is >= 1. The name of the object is included in the message string. The obj parameter can be NULL in which case the message is output on the debug console when agDebugLvl is >= 1.

AG_SetVerboseCallback() and AG_SetDebugCallback() arrange for the specified function to be invoked by AG_Verbose() and AG_Debug(). If the callback routine returns 1, the message will not be printed.

ERROR WRAPPERS

void * AG_Malloc (AG_Size len)

void * AG_TryMalloc (AG_Size len)

void * AG_Realloc (void *p, AG_Size len)

void * AG_TryRealloc (void *p, AG_Size len)

void AG_Free (void *p)

The AG_Malloc() function calls malloc(3) and raises a fatal error if the memory cannot be allocated. The AG_TryMalloc() variant also calls malloc(3), but sets the standard error message and returns NULL if the memory cannot be allocated.

AG_Realloc() calls realloc(3) and raises a fatal error if the memory cannot be allocated. The AG_TryRealloc() variant sets the standard error message and returns NULL if the memory cannot be reallocated. If p is NULL, AG_Realloc() and AG_TryRealloc() simply invoke malloc(3).

AG_Free() calls free(3). If p is NULL, it is a no-op.

HISTORY

The AG_Error interface first appeared in Agar 1.0. AG_SetErrorV() and AG_FatalErrorV() appeared in Agar 1.6.0.