FreeBSD Manual Pages
AG_ERROR(3) Library Functions Manual 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 er- ror 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 unini- tialized memory for general-purpose storage of data and objects. If insuf- ficient 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 in- sufficient 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 allo- cated 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 avail- able, AG_Realloc() raises a fatal error. The AG_TryRealloc() function calls realloc(3) to change the size of the al- located 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 avail- able, 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_Ob- ject(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. Agar 1.7 February 17, 2023 AG_ERROR(3)
NAME | SYNOPSIS | DESCRIPTION | ERROR RETURNS | DEBUG ROUTINES | ERROR WRAPPERS | EXAMPLES | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Error&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>