usr/src/man/man3m/feupdateenv.3m

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
  44 .\" Portions Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
  45 .\"
  46 .TH FEUPDATEENV 3M "Jul 12, 2006" "SunOS 5.11" "Mathematical Library Functions"
  47 .SH NAME
  48 feupdateenv \- update floating-point environment
  49 .SH SYNOPSIS
  50 .LP
  51 .nf
  52 c99 [ \fIflag\fR... ] \fIfile\fR... \fB-lm\fR [ \fIlibrary\fR... ]
  53 #include <fenv.h>
  54
  55 \fBint\fR \fBfeupdateenv\fR(\fBconst fenv_t *\fR\fIenvp\fR);
  56 .fi
  57
  58 .SH DESCRIPTION
  59 .sp
  60 .LP
  61 The \fBfeupdateenv()\fR function attempts to save the currently raised
  62 floating-point exceptions in its automatic storage, attempts to install the
  63 floating-point environment represented by the object pointed to by \fIenvp\fR,
  64 and then attempts to raise the saved floating-point exceptions. The \fIenvp\fR
  65 argument points to an object set by a call to \fBfegetenv\fR(3M) or
  66 \fBfeholdexcept\fR(3M), or equals a floating-point environment macro.
  67 .SH RETURN VALUES
  68 .sp
  69 .LP
  70 The \fBfeupdateenv()\fR function returns 0 if and only if all the required
  71 actions were successfully carried out.
  72 .SH ERRORS
  73 .sp
  74 .LP
  75 No errors are defined.
  76 .SH EXAMPLES
  77 .sp
  78 .LP
  79 The following example demonstrates sample code to hide spurious underflow
  80 floating-point exceptions:
  81 .LP
  82 \fBExample 1 \fRHide spurious underflow floating-point exceptions.
  83 .sp
  84 .in +2
  85 .nf
  86 #include <fenv.h>
  87 double f(double x)
  88 {
  89 #   pragma STDC FENV_ACCESS ON
  90     double result;
  91     fenv_t save_env;
  92     feholdexcept(&save_env);
  93     // compute result
  94     if (/* test spurious underflow */)
  95     feclearexcept(FE_UNDERFLOW);
  96     feupdateenv(&save_env);
  97     return result;
  98 }
  99 .fi
 100 .in -2
 101
 102 .SH ATTRIBUTES
 103 .sp
 104 .LP
 105 See \fBattributes\fR(5) for descriptions of the following attributes:
 106 .sp
 107
 108 .sp
 109 .TS
 110 tab(    ) box;
 111 cw(2.75i) |cw(2.75i)
 112 lw(2.75i) |lw(2.75i)
 113 .
 114 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 115 _
 116 Interface Stability     Standard
 117 _
 118 MT-Level        MT-Safe
 119 .TE
 120
 121 .SH SEE ALSO
 122 .sp
 123 .LP
 124 \fBfegetenv\fR(3M), \fBfeholdexcept\fR(3M), \fBfenv.h\fR(3HEAD),
 125 \fBattributes\fR(5), \fBstandards\fR(5)
 126 .SH NOTES
 127 .sp
 128 .LP
 129 In a multithreaded program, the \fBfeupdateenv()\fR function affects the
 130 floating point environment only for the calling thread.
 131 .sp
 132 .LP
 133 When the \fBFEX_CUSTOM\fR handling mode is in effect for an exception, raising
 134 that exception using \fBfeupdateenv()\fR causes the handling function to be
 135 invoked. The handling function can then modify the exception flags to be set as
 136 described in \fBfex_set_handling\fR(3M).  Any result value the handler supplies
 137 will be ignored.
 138 .sp
 139 .LP
 140 The \fBfeupdateenv()\fR function automatically installs and deinstalls
 141 \fBSIGFPE\fR handlers and sets and clears the trap enable mode bits in the
 142 floating point status register as needed. If a program uses these functions and
 143 attempts to install a \fBSIGFPE\fR handler or control the trap enable mode bits
 144 independently, the resulting behavior is not defined.
 145 .sp
 146 .LP
 147 As described in \fBfex_set_handling\fR(3M), when a handling function installed
 148 in \fBFEX_CUSTOM\fR mode is invoked, all exception traps are disabled (and will
 149 not be reenabled while \fBSIGFPE\fR is blocked). Thus, attempting to change the
 150 environment from within a handler by calling \fBfesetenv\fR(3M) or
 151 \fBfeupdateenv\fR might not produce the expected results.