Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_ERROR(3)		 BSD Library Functions Manual		   AG_ERROR(3)

NAME
     AG_Error -- agar error handling

SYNOPSIS
     #define _USE_AGAR_STD /* If macros	without	AG_ prefix are desired */
     #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, ...)

     const char	* AG_GetError(void)

     void AG_FatalError(const char *fmt, ...)

     void AG_SetFatalCallback(void (*callback)(const char *msg))

     const char	* AG_Strerror(int errno)

     The AG_SetError() function	sets the error message string using a
     printf(3) like format string.  AG_GetError() returns the error message
     string last set by	AG_SetError().	If Agar	was compiled with thread sup-
     port, the error message string is kept in thread-local storage, so	these
     functions are thread-safe.

     The AG_FatalError() function outputs the given error message to the user
     and causes	abnormal termination of	the program.

     AG_SetFatalCallback() function sets a user	provided callback to be	called
     by	AG_FatalError()	instead	of simply terminating the process. The call-
     back 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 plat-
     form-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 ap-
     plication (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 speci-
     fied function to be invoked by AG_Verbose() and AG_Debug().  If the call-
     back routine returns 1, the message will not be printed.

ERROR WRAPPERS
     void * AG_Malloc(size_t len)

     void * AG_TryMalloc(size_t	len)

     void * AG_Realloc(void *p,	size_t len)

     void * AG_TryRealloc(void *p, size_t 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 can-
     not 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.

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

HISTORY
     The AG_Error interface first appeared in Agar 1.0

BSD			       November	16, 2007			   BSD
NAME | SYNOPSIS | DESCRIPTION | ERROR RETURNS | DEBUG ROUTINES | ERROR WRAPPERS | 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+13.0-RELEASE+and+Ports>

home | help