Mathematical Library Functions fexsetlog(3M)
NAME
fexsetlog, fexgetlog, fexsetlogdepth,
fexgetlogdepth, fexlogentry - log retrospective diag-
nostics for floating point exceptions
SYNOPSIS
c99 [ flag... ] file... -lm [ library... ]
#include
int fexsetlog(FILE *fp);
FILE *fexgetlog(void);
int fexsetlogdepth(int depth);
int fexgetlogdepth(void);
void fexlogentry(const char *msg);
DESCRIPTION
The fexsetlog() function enables logging of retrospective
diagnostic messages regarding floating point exceptions to
the file specified by fp. If fp is NUL, logging is dis-
abled. When a program starts, logging is initially dis-
abled.
The occurrence of any of the twelve exceptions listed in
fexsethandling(3M) constitutes an event that can be
logged. To prevent the log from becoming exhorbitantly
long, the logging mechanism eliminates redundant entries by
two methods. First, each exception is associated with a
site in the program. The site is identified by the address
of the instruction that caused the exception together with a
stack trace. Only the first exception of a given type to
occur at a given site will be logged. Second, when
FEXNONSTOP handling mode is in effect for some exception,
only those occurrences of that exception that set its previ-
ously clear flag are logged. Clearing a flag using
feclearexcept() allows the next occurrence of the exception
to be logged provided it does not occur at a site at which
it was previously logged.
Each of the different types of invalid operation exceptions
can be logged at the same site. Because all invalid opera-
tion exceptions share the same flag, however, of those types
SunOS 5.11 Last change: 12 Jul 2006 1
Mathematical Library Functions fexsetlog(3M)
for which FEXNONSTOP mode is in effect, only the first
exception to set the flag will be logged. When the invalid
operation exception is raised by a call to feraiseexcept(3M)
or feupdateenv(3M), which type of invalid operation is
logged depends on the implementation.
If an exception results in the creation of a log entry, the
entry is created at the time the exception occurs and before
any exception handling actions selected with
fexsethandling() are taken. In particular, the log entry
is available even if the program terminates as a result of
the exception. The log entry shows the type of exception,
the address of the instruction that caused it, how it will
be handled, and the stack trace. If symbols are available,
the address of the excepting instruction and the addresses
in the stack trace are followed by the names of the
corresponding symbols.
The fexgetlog() function returns the current log file.
The fexsetlogdepth() sets the maximum depth of the stack
trace recorded with each exception to depth stack frames.
The default depth is 100.
Thefexgetlogdepth() function returns the current maximum
stack trace depth.
The fexlogentry() function adds a user-supplied entry to
the log. The entry includes the string pointed to by msg
and the stack trace. Like entries for floating point excep-
tions, redundant user-supplied entries are eliminated: only
the first user-supplied entry with a given msg to be
requested from a given site will be logged. For the purpose
of a user-supplied entry, the site is defined only by the
stack trace, which begins with the function that called
fexlogentry().
RETURN VALUES
The fexsetlog() function returns a non-zero value if log-
ging is enabled or disabled accordingly and returns 0 other-
wise. The fexsetlogdepth() returns a non-zero value if
the requested stack trace depth is established (regardless
of whether logging is enabled) and returns 0 otherwise.
EXAMPLES
The following example demonstrates the output generated when
a floating point overflow occurs in sscanf(3C).
SunOS 5.11 Last change: 12 Jul 2006 2
Mathematical Library Functions fexsetlog(3M)
#include
int
main() {
double x;
/*
* enable logging of retrospective diagnostics
*/
(void) fexsetlog(stdout);
/*
* establish default handling for overflows
*/
(void) fexsethandling(FEXOVERFLOW, FEXNONSTOP, NUL);
/*
* trigger an overflow in sscanf
*/
(void) sscanf("1.0e]400", "%lf", &x);
return 0;
}
The output from the preceding program reads:
Floating point overflow at 0xef71cac4 baseconversionsetexceptio
n, nonstop mode
0xef71cacc baseconversionsetexception
0xef721820 decimaltodouble
0xef75aba8 number
0xef75a94c doscanu
0xef75ecf8 sscanf
0x00010f20 main
Recompiling the program or running it on another system can
produce different text addresses from those shown above.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 12 Jul 2006 3
Mathematical Library Functions fexsetlog(3M)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWlibms, SUNWlmxs
Interface Stability Stable
MT-Level MT-Safe (see NOTES)
SEE ALSO
feclearexcept(3M), fegetenv(3M), feraiseexcept(3M),
feupdateenv(3M), fexsethandling(3M), attributes(5)
Numerical Computation Guide
NOTES
All threads in a process share the same log file. Each call
to fexsetlog() preempts the previous one.
In addition to the log file itself, two additional file
descriptors are used during the creation of a log entry in
order to obtain symbol names from the executable and any
shared objects it uses. These file descriptors are relin-
quished once the log entry is written. If the file descrip-
tors cannot be allocated, symbols names are omitted from the
stack trace.
The functions described on this page automatically install
and deinstall SIGFPE handlers and set and clear the trap
enable mode bits in the floating point status register as
needed. If a program uses these functions and attempts to
install a SIGFPE handler or control the trap enable mode
bits independently, the resulting behavior is not defined.
As described in fexsethandling(), when a handling function
installed in FEXCUSTOM mode is invoked, all exception traps
are disabled (and will not be reenabled while SIGFPE is
blocked). Thus, retrospective diagnostic messages are not
logged for exceptions that occur within such a handler.
SunOS 5.11 Last change: 12 Jul 2006 4
|
