share/man/man3m/fex_set_log.3m

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH fex_set_log 3M "12 Jul 2006" "SunOS 5.11" "Mathematical Library Functions"
   7 .SH NAME
   8 fex_set_log, fex_get_log, fex_set_log_depth, fex_get_log_depth, fex_log_entry
   9 \- log retrospective diagnostics for floating point exceptions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 c99 [ \fIflag\fR... ] \fIfile\fR... -lm [ \fIlibrary\fR... ]
  14 #include <fenv.h>
  15
  16 \fBint\fR \fBfex_set_log\fR(\fBFILE *\fR\fIfp\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBFILE *\fR\fBfex_get_log\fR(\fBvoid\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBfex_set_log_depth\fR(\fBint\fR \fIdepth\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBfex_get_log_depth\fR(\fBvoid\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBvoid\fR \fBfex_log_entry\fR(\fBconst char *\fR\fImsg\fR);
  37 .fi
  38
  39 .SH DESCRIPTION
  40 .sp
  41 .LP
  42 The \fBfex_set_log()\fR function enables logging of retrospective diagnostic
  43 messages regarding floating point exceptions to the file specified by \fIfp\fR.
  44 If \fIfp\fR is \fINULL\fR, logging is disabled.  When a program starts, logging
  45 is initially disabled.
  46 .sp
  47 .LP
  48 The occurrence of any of the twelve exceptions listed in
  49 \fBfex_set_handling\fR(3M) constitutes an event that can be logged.  To prevent
  50 the log from becoming exhorbitantly long, the logging mechanism eliminates
  51 redundant entries by two methods.  First, each exception is associated with a
  52 \fIsite\fR in the program.  The site is identified by the address of the
  53 instruction that caused the exception together with a stack trace.  Only the
  54 first exception of a given type to occur at a given site will be logged.
  55 Second, when \fBFEX_NONSTOP\fR handling mode is in effect for some exception,
  56 only those occurrences of that exception that set its previously clear flag are
  57 logged.  Clearing a flag using \fBfeclearexcept()\fR allows the next occurrence
  58 of the exception to be logged provided it does not occur at a site at which it
  59 was previously logged.
  60 .sp
  61 .LP
  62 Each of the different types of invalid operation exceptions can be logged at
  63 the same site.  Because all invalid operation exceptions share the same flag,
  64 however, of those types for which \fBFEX_NONSTOP\fR mode is in effect, only the
  65 first exception to set the flag will be logged.  When the invalid operation
  66 exception is raised by a call to \fBferaiseexcept\fR(3M) or
  67 \fBfeupdateenv\fR(3M), which type of invalid operation is logged depends on the
  68 implementation.
  69 .sp
  70 .LP
  71 If an exception results in the creation of a log entry, the entry is created at
  72 the time the exception occurs and before any exception handling actions
  73 selected with \fBfex_set_handling()\fR are taken.  In particular, the log entry
  74 is available even if the program terminates as a result of the exception.  The
  75 log entry shows the type of exception, the address of the instruction that
  76 caused it, how it will be handled, and the stack trace. If symbols are
  77 available, the address of the excepting instruction and the addresses in the
  78 stack trace are followed by the names of the corresponding symbols.
  79 .sp
  80 .LP
  81 The \fBfex_get_log()\fR function returns the current log file.
  82 .sp
  83 .LP
  84 The \fBfex_set_log_depth()\fR sets the maximum depth of the stack trace
  85 recorded with each exception to \fIdepth\fR stack frames.  The default depth is
  86 100.
  87 .sp
  88 .LP
  89 The\fBfex_get_log_depth()\fR function returns the current maximum stack trace
  90 depth.
  91 .sp
  92 .LP
  93 The \fBfex_log_entry()\fR function adds a user-supplied entry to the log.  The
  94 entry includes the string pointed to by \fImsg\fR and the stack trace.  Like
  95 entries for floating point exceptions, redundant user-supplied entries are
  96 eliminated: only the first user-supplied entry with a given \fImsg\fR to be
  97 requested from a given site will be logged.  For the purpose of a user-supplied
  98 entry, the site is defined only by the stack trace, which begins with the
  99 function that called \fBfex_log_entry()\fR.
 100 .SH RETURN VALUES
 101 .sp
 102 .LP
 103 The \fBfex_set_log()\fR function returns a non-zero value if logging is enabled
 104 or disabled accordingly and returns 0 otherwise.  The \fBfex_set_log_depth()\fR
 105 returns a non-zero value if the requested stack trace depth is established
 106 (regardless of whether logging is enabled) and returns 0 otherwise.
 107 .SH EXAMPLES
 108 .sp
 109 .LP
 110 The following example demonstrates the output generated when a floating point
 111 overflow occurs in \fBsscanf\fR(3C).
 112 .sp
 113 .in +2
 114 .nf
 115 #include <fenv.h>
 116
 117 int
 118 main() {
 119         double x;
 120 /*
 121  * enable logging of retrospective diagnostics
 122  */
 123         (void) fex_set_log(stdout);
 124 /*
 125  * establish default handling for overflows
 126  */
 127         (void) fex_set_handling(FEX_OVERFLOW, FEX_NONSTOP, NULL);
 128 /*
 129  * trigger an overflow in sscanf
 130  */
 131         (void) sscanf("1.0e+400", "%lf", &x);
 132         return 0;
 133 }
 134 .fi
 135 .in -2
 136
 137 .sp
 138 .LP
 139 The output from the preceding program reads:
 140 .sp
 141 .in +2
 142 .nf
 143 Floating point overflow at 0xef71cac4 __base_conversion_set_exceptio
 144 n, nonstop mode
 145    0xef71cacc  __base_conversion_set_exception
 146    0xef721820  _decimal_to_double
 147    0xef75aba8  number
 148    0xef75a94c  __doscan_u
 149    0xef75ecf8  sscanf
 150    0x00010f20  main
 151 .fi
 152 .in -2
 153
 154 .sp
 155 .LP
 156 Recompiling the program or running it on another system can produce different
 157 text addresses from those shown above.
 158 .SH ATTRIBUTES
 159 .sp
 160 .LP
 161 See \fBattributes\fR(5) for descriptions of the following attributes:
 162 .sp
 163
 164 .sp
 165 .TS
 166 tab(\a) box;
 167 lw(2.75i) lw(2.75i)
 168 lw(2.75i) lw(2.75i)
 169 .
 170 ATTRIBUTE TYPE\aATTRIBUTE VALUE
 171 Availability\aSUNWlibms, SUNWlmxs
 172 Interface Stability\aStable
 173 MT-Level\aMT-Safe (see NOTES)
 174 .TE
 175
 176 .SH SEE ALSO
 177 .sp
 178 .LP
 179 \fBfeclearexcept\fR(3M), \fBfegetenv\fR(3M), \fBferaiseexcept\fR(3M),
 180 \fBfeupdateenv\fR(3M), \fBfex_set_handling\fR(3M), \fBattributes\fR(5)
 181 .sp
 182 .LP
 183 \fINumerical Computation Guide\fR
 184 .SH NOTES
 185 .sp
 186 .LP
 187 All threads in a process share the same log file.  Each call to
 188 \fBfex_set_log()\fR preempts the previous one.
 189 .sp
 190 .LP
 191 In addition to the log file itself, two additional file descriptors are used
 192 during the creation of a log entry in order to obtain symbol names from the
 193 executable and any shared objects it uses.  These file descriptors are
 194 relinquished once the log entry is written.  If the file descriptors cannot be
 195 allocated, symbols names are omitted from the stack trace.
 196 .sp
 197 .LP
 198 The functions described on this page automatically install and deinstall
 199 \fBSIGFPE\fR handlers and set and clear the trap enable mode bits in the
 200 floating point status register as needed.  If a program uses these functions
 201 and attempts to install a \fBSIGFPE\fR handler or control the trap enable mode
 202 bits independently, the resulting behavior is not defined.
 203 .sp
 204 .LP
 205 As described in \fBfex_set_handling()\fR, when a handling function installed in
 206 \fBFEX_CUSTOM\fR mode is invoked, all exception traps are disabled (and will
 207 not be reenabled while \fBSIGFPE\fR is blocked).  Thus, retrospective
 208 diagnostic messages are not logged for exceptions that occur within such a
 209 handler.