'\" t .\" @(#)fex_set_log.3m 1.5 00/01/01 SMI .TH fex_set_log 3M "01/01/00" .SH 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 .SH SYNOPSIS .LP .B cc .RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|." .B -R/opt/SUNWspro/lib -L/opt/SUNWspro/lib -lm9x .RI "[ " "library" " \|.\|.\|. ]" .LP .B #include .LP .BI "int fex_set_log(FILE *" fp ); .LP .BI "FILE *fex_get_log(void);" .LP .BI "int fex_set_log_depth(int " depth ); .LP .BI "int fex_get_log_depth(void);" .LP .BI "void fex_log_entry(const char *" msg ); .SH DESCRIPTION .IX "fex_set_log function" "" "\fLfex_set_log()\fP function" .IX "fex_get_log function" "" "\fLfex_get_log()\fP function" .IX "fex_set_log_depth function" "" "\fLfex_set_log_depth()\fP function" .IX "fex_get_log_depth function" "" "\fLfex_get_log_depth()\fP function" .IX "fex_log_entry function" "" "\fLfex_log_entry()\fP function" .LP \f3fex_set_log(\f2fp\f3)\f1 enables logging of retrospective diagnostic messages regarding floating point exceptions to the file specified by \f2fp\f1. If \f2fp\f1 is \s-1NULL\s0, logging is disabled. When a program starts, logging is initially disabled. .LP The occurrence of any of the twelve exceptions listed in \f3fex_set_handling\f1(3M) constitutes an event that may 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 \f2site\f1 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 \s-1FEX_NONSTOP\s0 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 \f3feclearexcept(\|)\f1 allows the next occurrence of the exception to be logged provided it does not occur at a site at which it was previously logged.) .LP Note that each of the different types of invalid operation exceptions may be logged at the same site. Because all invalid operation exceptions share the same flag, however, of those types for which \s-1FEX_NONSTOP\s0 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 \f3feraiseexcept(\|)\f1 or \f3feupdateenv(\|)\f1, which type of invalid operation is logged depends on the implementation.) .LP 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 via \f3fex_set_handling\f1(3M) 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. .LP \f3fex_get_log(\|)\f1 returns the current log file. .LP \f3fex_set_log_depth(\f2depth\f3)\f1 sets the maximum depth of the stack trace recorded with each exception to \f2depth\f1 stack frames. The default depth is 100. .LP \f3fex_get_log_depth(\|)\f1 returns the current maximum stack trace depth. .LP \f3fex_log_entry(\f2msg\f3)\f1 adds a user-supplied entry to the log. The entry includes the string pointed to by \f2msg\f1 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 \f2msg\f1 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 \f3fex_log_entry(\|)\f1.) .SH "RETURN VALUES" \f3fex_set_log\f1 returns a nonzero value if logging is enabled or disabled accordingly and returns zero otherwise. \f3fex_set_log_depth\f1 returns a nonzero value if the requested stack trace depth is established (regardless of whether logging is enabled) and returns zero otherwise. .SH EXAMPLE The following example shows the output generated when a floating point overflow occurs in \f3sscanf(\|)\f1. .LP .RS .nf .vs 11p .ft B .ne 19 #include 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; } .vs .fi .RE .LP The output from the preceding program reads: .LP .RS .nf .vs 11p .ft B .ne 7 Floating point overflow at 0xef71cac4 __base_conversion_set_exception, nonstop mode 0xef71cacc __base_conversion_set_exception 0xef721820 _decimal_to_double 0xef75aba8 number 0xef75a94c __doscan_u 0xef75ecf8 sscanf 0x00010f20 main .vs .fi .RE .LP (Recompiling the program or running it on another system may produce different text addresses from those shown above.) .SH ATTRIBUTES See .BR attributes (5) for descriptions of the following attributes: .sp .ne 10 .TS box; cbp-1 | cbp-1 l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE = Availability SPROm9xs Interface Stability Stable MT-Level MT-Safe (see Notes) .TE .SH "SEE ALSO" .BR feclearexcept (3M), .BR fegetenv (3M), .BR fex_set_handling (3M), .BR ieee_retrospective (3M), .BR attributes (5) .LP .I Numerical Computation Guide .SH NOTES All threads in a process share the same log file. Each call to \f3fex_set_log(\|)\f1 preempts the previous one. .LP 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, symbols names are omitted from the stack trace. .LP The functions described on this page automatically install and deinstall \s-1SIGFPE\s0 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 \s-1SIGFPE\s0 handler or control the trap enable mode bits independently, the resulting behavior is not defined. .LP As described in \f3fex_set_handling\f1(3M), when a handling function installed in \s-1FEX_CUSTOM\s0 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. .LP As shown in the synopsis, the recommended way to link with libm9x using \f3cc\f1 is to specify .LP .RS .BI -R install-path "/lib -L" install-path "/lib -lm9x" .RE .LP on the command line, where \f2install-path\f1 refers to the location in which the compilers are installed (/opt/SUNWspro by default). See the \f2Numerical Computation Guide\f1 for additional information about linking with libm9x.