AG_ERROR(3)

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

SEE ALSO
AG_Intro(3), AG_Object(3), AG_Threads(3)

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.