pfNotify(3pf) OpenGL Performer 3.2.2 libpr Reference Pages pfNotify(3pf)NAME
pfNotify, pfNotifyLevel, pfGetNotifyLevel, pfNotifyHandler,
pfGetNotifyHandler, pfDefaultNotifyHandler, pfNotifyLock, pfNotifyUnlock
- Control error handling, signal errors or log messages
FUNCTION SPECIFICATION
#include <Performer/pr.h>
void pfNotify(int severity, int error, char *format, ...);
void pfNotifyLevel(int severity);
int pfGetNotifyLevel(void);
void pfNotifyHandler(pfNotifyFuncType handler);
pfNotifyFuncType pfGetNotifyHandler(void);
void pfDefaultNotifyHandler(pfNotifyData *data);
void pfNotifyLock(void);
void pfNotifyUnlock(void);
typedef struct
{
int severity;
int pferrno;
char *emsg;
} pfNotifyData;
typedef void (*pfNotifyFuncType)(pfNotifyData*);
DESCRIPTION
These functions provide a general purpose error message and notification
handling facility for applications using OpenGL Performer. This facility
is used internally by OpenGL Performer for error, warning, and status
notifications and can be used by user developed programs as well.
pfNotifyHandler sets handler as the user error handling routine. All
errors, warnings and notices will call handler with a pointer to a
pfNotifyData structure that describes the error or message. The default
notification handler pfDefaultNotifyHandler prints out a message to
stderr of the form:
<PID> PF <LEVEL>/<PFERROR>(<ERRNO>) <MESSAGE>
where PID is the process id of the process that encountered the error
Page 1
pfNotify(3pf) OpenGL Performer 3.2.2 libpr Reference Pages pfNotify(3pf)
(PID is only emitted when the notification threshold is >= PFNFY_DEBUG),
LEVEL is a string indicating the severity of the error, PFERROR is the
type of error detected, ERRNO is the value of the system global errno
(see perror(3C)), and MESSAGE is the formatted error message given
pfNotify. The default handler zeros the system global errno. If PFERROR
is PFNFY_MORE, the message is considered to be a continuation of the
previous message and the print format is:
PF <MESSAGE>
The companion function pfGetNotifyHandler returns the address of the
installed handler function. It is possible to inquire this address and
provide it to user installed handlers in order to chain multiple
notification handlers to any desired level.
The functions pfNotifyLock and pfNotifyUnlock provide access to the lock
used by pfDefaultNotifyHandler. This can be used to atomically print
messages to stderr that won't get scrambled with the output from
pfDefaultNotifyHandler (or other routines that use this lock) in other
processes.
pfNotifyLevel sets the threshold for notification. A notification must
have a level less than or equal to the threshold for the default handler
to print a message. The notification handler itself is invoked
regardless of the notification level. The levels are in decreasing
severity:
PFNFY_ALWAYS
PFNFY_FATAL
PFNFY_WARN
PFNFY_NOTICE
PFNFY_INFO
PFNFY_DEBUG
PFNFY_FP_DEBUG.
The default notification threshold is PFNFY_NOTICE.
Call pfGetNotifyLevel to query the current notification level. The
meaning of these notification levels is as follows:
Error Level Description
___________________________________________________________________
PFNFY_ALWAYS Always print regardless of notify level
PFNFY_FATAL Fatal error, the dying gasp of a doomed process
PFNFY_WARN Serious warning, rarely used for frame-time errors
PFNFY_NOTICE Warning, may be used for frame time errors
PFNFY_INFO Information on progress as well as errors
PFNFY_DEBUG Debug information of significant verbosity
|
Page 2
pfNotify(3pf) OpenGL Performer 3.2.2 libpr Reference Pages pfNotify(3pf)
PFNFY_FP_DEBUG Debug information and floating point exceptions
|
Setting the notification level to PFNFY_FP_DEBUG also enables floating
point exceptions for overflow, underflow and invalid operations.
Normally, these floating point errors are handled through kernel
exceptions or by the floating point hardware, and may be nearly invisible
to an application except from the performance degradation, sometimes very
significant, which they can cause. When enabled, pfNotify events are
generated for the floating point exceptions mentioned above and messages
displayed or passed to the user supplied pfNotify handler.
The environment variable PFNFYLEVEL can be set to override the value
specified in pfNotifyLevel. If the notification level is set via
PFNFYLEVEL it can not be changed by an application.
A notification level of PFNFY_FATAL causes the program to exit after
notification; less severe levels do not.
pfNotify generates an error message. severity must be one of the above
listed constants. error may be any integer value, however, OpenGL
Performer uses the following values internally:
PFNFY_USAGE
PFNFY_RESOURCE
PFNFY_SYSERR
PFNFY_ASSERT
PFNFY_PRINT
PFNFY_INTERNAL
PFNFY_FP_OVERFLOW
PFNFY_FP_DIVZERO
PFNFY_FP_INVALID
PFNFY_FP_UNDERFLOW
PFNFY_MORE does a continuation of the previous message.
The severity must be less than or equal to the severity set in
pfNotifyLevel for the error message to be output.
NOTES
Notification level is managed on a per process basis. Processes forked
off after pfNotifyLevel is called inherit the specified level.
BUGS
Enabling floating point exceptions may cause the values returned from
exceptions to be different than the system defaults. After an _INVALID
operation, all subsequent exceptions will generate incorrect return
values.
SEE ALSO
errno, handle_sigfpes, perror
Page 3
