Tribblix: manual page: fex_set

FEX_SET_LOG(3M) Mathematical Library Functions FEX_SET_LOG(3M)

NAME

fex_set_log, fex_get_log, fex_set_log_depth, fex_get_log_depth,
fex_log_entry - log retrospective diagnostics for floating point
exceptions

SYNOPSIS

c99 [ flag... ] file... -lm [ library... ]
#include <fenv.h>

int fex_set_log(FILE *fp);

FILE *fex_get_log(void);

int fex_set_log_depth(int depth);

int fex_get_log_depth(void);

void fex_log_entry(const char *msg);

DESCRIPTION

The fex_set_log() function enables logging of retrospective
diagnostic messages regarding floating point exceptions to the file
specified by fp. If fp is NULL, logging is disabled. When a program
starts, logging is initially disabled.

The occurrence of any of the twelve exceptions listed in
fex_set_handling(3M) constitutes an event that can be logged. To
prevent the log from becoming exorbitantly 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
FEX_NONSTOP handling mode is in effect for some exception, only those
occurrences of that exception that set its previously 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 operation exceptions
share the same flag, however, of those types for which FEX_NONSTOP
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 fex_set_handling() 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 fex_get_log() function returns the current log file.

The fex_set_log_depth() function sets the maximum depth of the stack
trace recorded with each exception to depth stack frames. The
default depth is 100.

The fex_get_log_depth() function returns the current maximum stack
trace depth.

The fex_log_entry() 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 exceptions, 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
fex_log_entry().

RETURN VALUES

The fex_set_log() function returns a non-zero value if logging is
enabled or disabled accordingly and returns 0 otherwise. The
fex_set_log_depth() 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).

#include <fenv.h>

int
main() {
double x;
/*
* enable logging of retrospective diagnostics
*/
(void) fex_set_log(stdout);
/*
* establish default handling for overflows
*/
(void) fex_set_handling(FEX_OVERFLOW, FEX_NONSTOP, NULL);
/*
* 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 __base_conversion_set_exceptio
n, nonstop mode
0xef71cacc __base_conversion_set_exception
0xef721820 _decimal_to_double
0xef75aba8 number
0xef75a94c __doscan_u
0xef75ecf8 sscanf
0x00010f20 main

Recompiling the program or running it on another system can produce
different text addresses from those shown above.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:

+----------------------------------------------------------+
|ATTRIBUTE TYPE ATTRIBUTE VALUE |
|Availability SUNWlibms, SUNWlmxs |
|Interface Stability Stable |
|MT-Level MT-Safe (see NOTES) |
+----------------------------------------------------------+

NOTES

All threads in a process share the same log file. Each call to
fex_set_log() 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 relinquished once the log entry is written. If the
file descriptors cannot be allocated, symbol 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 fex_set_handling(), when a handling function
installed in FEX_CUSTOM 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 June 20, 2021 FEX_SET_LOG(3M)