NAME

AG_Error — agar error handling

SYNOPSIS

#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_SetErrorS(const char *msg);

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

const char *
AG_GetError(void);

void
AG_FatalError(const char *msg);

void
AG_FatalErrorF(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 error message from the printf(3) style format string fmt. AG_SetErrorS() sets the error message from the string msg.

AG_SetErrorV() is a macro which sets the error message to either msg if Agar was built with AG_VERBOSITY or the shortened code code if Agar was built without AG_VERBOSITY.

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

Note: If Agar was compiled with THREADS support then the error code and error message are both 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_Debug2(AG_Object *obj, const char *fmt, ...);

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

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

The AG_Verbose() routine prints a message on the error console if agVerbose is non-zero.

The AG_Debug() routine outputs text to the debugging console if agDebugLvl is >= 1. AG_Debug2() outputs text to the debugging console if agDebugLvl is >= 2. If obj is not NULL then the name (or pointer address) of obj is prepended to the message.

The AG_SetVerboseCallback() and AG_SetDebugCallback() routines arrange for fn 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 size);

void *
AG_TryMalloc(AG_Size size);

void *
AG_Realloc(void *ptr, AG_Size size);

void *
AG_TryRealloc(void *ptr, AG_Size size);

void
AG_Free(void *ptr);

The AG_Malloc() function calls malloc(3) to allocate size bytes of uninitialized memory for general-purpose storage of data and objects. If insufficient memory is available, AG_Malloc() raises a fatal error.

The AG_TryMalloc() function calls malloc(3) to allocate size bytes of uninitialized memory for general-purpose storage of data / objects. If insufficient memory is available, AG_TryMalloc() sets the error message to "Out of memory" (E0) and returns NULL.

The AG_Realloc() function calls realloc(3) to change the size of the allocated memory area referenced by ptr from its current size to a new size in bytes. On success, it returns a pointer to the newly reallocated memory area (which may be different than ptr). If insufficient memory is available, AG_Realloc() raises a fatal error.

The AG_TryRealloc() function calls realloc(3) to change the size of the allocated memory area referenced by ptr from its current size to a new size in bytes. On success, it returns a pointer to the newly reallocated memory area (which may be different than ptr). If insufficient memory is available, AG_TryRealloc() sets the error message to "Out of memory" (E0) and returns NULL.

Passing a ptr of NULL to AG_Realloc() or AG_TryRealloc() is equivalent to calling AG_Malloc() or AG_TryMalloc().

AG_Free() causes the allocated memory referenced by ptr to be released (made available for future allocations) by calling free(3). If ptr is NULL then AG_Free() is a no-op.

EXAMPLES

The following code print a message on the debugging console:

AG_Verbose("This is a global debugging message\n");

Debug messages may contain ANSI SGR sequences:

AG_Verbose("This message contains "
           AGSI_RED AGSI_ITALIC "ANSI" AGSI_RST "\n");

AG_Verbose("This message uses an "
           AGSI_COURIER "alternate font" AGSI_RST "\n");

The following code prints a debugging message in relation to an AG_Object(3) in particular:

AG_Debug(myObject,
    "Hello! This is a contextual debugging message. "
    "My flags = 0x%x\n", myObject->flags);

The following code illustrates the use of AG_SetError() by a function, and the use of AG_GetError() by its caller:

int
SomeOperation(int x)
{
	if (x > 10) {
		AG_SetError("x is too large (%d > 10)", x);
		return (-1);
	}
	return (0);
}

if (SomeOperation(x) != 0)
	AG_Verbose("Failed: %s\n", AG_GetError());

The following code allocates, reallocates and frees memory:

void *buffer, *bufferNew;

/* Allocate 4K of memory. Fatal if allocation fails. */
buffer = AG_Malloc(4096);

/* Allocate 4K of memory. Print a message if allocation fails. */
if ((buffer = AG_TryMalloc(4096)) == NULL)
	AG_Verbose("Allocation failed\n");

/* Grow the buffer to 8K. Fatal if reallocation fails. */
buffer = AG_Realloc(buffer, 8192);

/* Grow the buffer to 8K. Print a message if reallocation fails. */
if ((bufferNew = AG_TryRealloc(buffer, 8192)) == NULL) {
	AG_Verbose("Allocation failed\n");
}
buffer = bufferNew;

/* Release the allocated memory. */
AG_Free(buffer);

HISTORY

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