SYNOPSIS

DESCRIPTION

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

ERROR RETURNS

voidAG_SetError (const char *fmt, ...)

voidAG_SetErrorV (const char *code, const char *msg)

const char *AG_GetError (void)

voidAG_FatalError (const char *fmt, ...)

voidAG_FatalErrorV (const char *code, const char *message)

voidAG_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

voidAG_Verbose (const char *fmt, ...)

voidAG_Debug (AG_Object *obj, const char *fmt, ...)

voidAG_SetVerboseCallback (int (*fn)(const char *msg))

voidAG_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)

voidAG_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).