Manual Pages for UNIX Operating System command usage for man fex_get_log

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 diag-
     nostics for floating point exceptions

SYNOPSIS
     c99 [ flag... ] file... -lm [ library... ]
     #include 

     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  dis-
     abled.   When  a  program  starts, logging is initially dis-
     abled.


     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  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
     FEX_NONSTOP  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                    fex_set_log(3M)



     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() sets the maximum depth of the  stack
     trace  recorded  with  each exception to depth stack frames.
     The default depth is 100.


     Thefex_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 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
     fex_log_entry().

RETURN VALUES
     The fex_set_log() function returns a non-zero value if  log-
     ging is enabled or disabled accordingly and returns 0 other-
     wise.  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).



SunOS 5.11          Last change: 12 Jul 2006                    2






Mathematical Library Functions                    fex_set_log(3M)



       #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;
       }



     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(5) for descriptions of the  following  attri-
     butes:














SunOS 5.11          Last change: 12 Jul 2006                    3






Mathematical Library Functions                    fex_set_log(3M)



     _____________________________________________________________
    | ATTRIBUTE TYPE                ATTRIBUTE VALUE              |
    | Availability                  system/library/math, SUNWlmxs|
    | Interface Stability           Committed                    |
    | MT-Level                      MT-Safe (see NOTES)          |
    |____________________________________________________________|


SEE ALSO
     feclearexcept(3M),     fegetenv(3M),      feraiseexcept(3M),
     feupdateenv(3M), fex_set_handling(3M), attributes(5)


     Numerical Computation Guide

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 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 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          Last change: 12 Jul 2006                    4