Agar

Agar 1.7 Manual

(Printable Version)
AG_Debug(3)

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_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.

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

SEE ALSO


HISTORY

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