1fex_set_log(3M) Mathematical Library Functions fex_set_log(3M)
2
6 fex_set_log, fex_get_log, fex_set_log_depth, fex_get_log_depth,
7 fex_log_entry - log retrospective diagnostics for floating point excep‐
8 tions
9
11 c99 [ flag... ] file... -lm [ library... ]
12 #include <fenv.h>
13 int fex_set_log(FILE *fp);
15 FILE *fex_get_log(void);
18 int fex_set_log_depth(int depth);
21 int fex_get_log_depth(void);
24 void fex_log_entry(const char *msg);
27
30 The fex_set_log() function enables logging of retrospective diagnostic
31 messages regarding floating point exceptions to the file specified by
32 fp. If fp is NULL, logging is disabled. When a program starts, log‐
33 ging is initially disabled.
34 The occurrence of any of the twelve exceptions listed in fex_set_han‐
37 dling(3M) constitutes an event that can be logged. To prevent the log
38 from becoming exhorbitantly long, the logging mechanism eliminates
39 redundant entries by two methods. First, each exception is associated
40 with a site in the program. The site is identified by the address of
41 the instruction that caused the exception together with a stack trace.
42 Only the first exception of a given type to occur at a given site will
43 be logged. Second, when FEX_NONSTOP handling mode is in effect for
44 some exception, only those occurrences of that exception that set its
45 previously clear flag are logged. Clearing a flag using feclearex‐
46 cept() allows the next occurrence of the exception to be logged pro‐
47 vided it does not occur at a site at which it was previously logged.
48 Each of the different types of invalid operation exceptions can be
51 logged at the same site. Because all invalid operation exceptions
52 share the same flag, however, of those types for which FEX_NONSTOP mode
53 is in effect, only the first exception to set the flag will be logged.
54 When the invalid operation exception is raised by a call to feraiseex‐
55 cept(3M) or feupdateenv(3M), which type of invalid operation is logged
56 depends on the implementation.
57 If an exception results in the creation of a log entry, the entry is
60 created at the time the exception occurs and before any exception han‐
61 dling actions selected with fex_set_handling() are taken. In particu‐
62 lar, the log entry is available even if the program terminates as a
63 result of the exception. The log entry shows the type of exception,
64 the address of the instruction that caused it, how it will be handled,
65 and the stack trace. If symbols are available, the address of the
66 excepting instruction and the addresses in the stack trace are followed
67 by the names of the corresponding symbols.
68 The fex_get_log() function returns the current log file.
71 The fex_set_log_depth() sets the maximum depth of the stack trace
74 recorded with each exception to depth stack frames. The default depth
75 is 100.
76 Thefex_get_log_depth() function returns the current maximum stack trace
79 depth.
80 The fex_log_entry() function adds a user-supplied entry to the log.
83 The entry includes the string pointed to by msg and the stack trace.
84 Like entries for floating point exceptions, redundant user-supplied
85 entries are eliminated: only the first user-supplied entry with a given
86 msg to be requested from a given site will be logged. For the purpose
87 of a user-supplied entry, the site is defined only by the stack trace,
88 which begins with the function that called fex_log_entry().
89
91 The fex_set_log() function returns a non-zero value if logging is
92 enabled or disabled accordingly and returns 0 otherwise. The
93 fex_set_log_depth() returns a non-zero value if the requested stack
94 trace depth is established (regardless of whether logging is enabled)
95 and returns 0 otherwise.
96
98 The following example demonstrates the output generated when a floating
99 point overflow occurs in sscanf(3C).
100 #include <fenv.h>
102 int
104 main() {
105 double x;
106 /*
107 * enable logging of retrospective diagnostics
108 */
109 (void) fex_set_log(stdout);
110 /*
111 * establish default handling for overflows
112 */
113 (void) fex_set_handling(FEX_OVERFLOW, FEX_NONSTOP, NULL);
114 /*
115 * trigger an overflow in sscanf
116 */
117 (void) sscanf("1.0e+400", "%lf", &x);
118 return 0;
119 }
120 The output from the preceding program reads:
124 Floating point overflow at 0xef71cac4 __base_conversion_set_exceptio
126 n, nonstop mode
127 0xef71cacc __base_conversion_set_exception
128 0xef721820 _decimal_to_double
129 0xef75aba8 number
130 0xef75a94c __doscan_u
131 0xef75ecf8 sscanf
132 0x00010f20 main
133 Recompiling the program or running it on another system can produce
137 different text addresses from those shown above.
138
140 See attributes(5) for descriptions of the following attributes:
141 ┌───────────────────────────────────────────────────────────┐
146 │ATTRIBUTE TYPE ATTRIBUTE VALUE │
147 │Availability SUNWlibms, SUNWlmxs │
148 │Interface Stability Stable │
149 │MT-Level MT-Safe (see NOTES) │
150 └───────────────────────────────────────────────────────────┘
151
153 feclearexcept(3M), fegetenv(3M), feraiseexcept(3M), feupdateenv(3M),
154 fex_set_handling(3M), attributes(5)
155 Numerical Computation Guide
158
160 All threads in a process share the same log file. Each call to
161 fex_set_log() preempts the previous one.
162 In addition to the log file itself, two additional file descriptors are
165 used during the creation of a log entry in order to obtain symbol names
166 from the executable and any shared objects it uses. These file
167 descriptors are relinquished once the log entry is written. If the
168 file descriptors cannot be allocated, symbols names are omitted from
169 the stack trace.
170 The functions described on this page automatically install and dein‐
173 stall SIGFPE handlers and set and clear the trap enable mode bits in
174 the floating point status register as needed. If a program uses these
175 functions and attempts to install a SIGFPE handler or control the trap
176 enable mode bits independently, the resulting behavior is not defined.
177 As described in fex_set_handling(), when a handling function installed
180 in FEX_CUSTOM mode is invoked, all exception traps are disabled (and
181 will not be reenabled while SIGFPE is blocked). Thus, retrospective
182 diagnostic messages are not logged for exceptions that occur within
183 such a handler.
184SunOS 5.11 12 Jul 2006 fex_set_log(3M)