Commit | Line | Data |
---|---|---|
ef8ea0f5 | 1 | From Prof. Kahan at UC at Berkeley |
ae59e04c CL |
2 | .\" Copyright (c) 1985, 1991 Regents of the University of California. |
3 | .\" All rights reserved. | |
f9628029 | 4 | .\" |
ae59e04c | 5 | .\" %sccs.include.redist.man% |
f9628029 | 6 | .\" |
ae59e04c CL |
7 | .\" @(#)ieee.3 6.3 (Berkeley) %G% |
8 | .\" | |
9 | .Dd | |
10 | .Dt IEEE 3 | |
11 | .Os BSD 4.3 | |
12 | .Sh NAME | |
13 | .Nm copysign , | |
14 | .Nm drem , | |
15 | .Nm finite , | |
16 | .Nm logb , | |
17 | .Nm scalb | |
18 | .Nm copysign , | |
19 | .Nm remainder, | |
20 | .Nd exponent manipulations | |
21 | .Sh SYNOPSIS | |
22 | .Fd #include <math.h> | |
23 | .Ft double | |
24 | .Fn copysign "double x" "double y" | |
25 | .Ft double | |
26 | .Fn drem "double x" "double y" | |
27 | .Ft int | |
28 | .Fn finite "double x" | |
29 | .Ft double | |
30 | .Fn logb "double x" | |
31 | .Ft double | |
32 | .Fn scalb "double x" "int n" | |
33 | .Sh DESCRIPTION | |
34 | These functions are required for, or recommended by the | |
35 | .Tn IEEE | |
36 | standard | |
cd30a7d2 | 37 | 754 for floating\-point arithmetic. |
ae59e04c CL |
38 | .Pp |
39 | The | |
40 | .Fn copysign | |
41 | function | |
42 | returns | |
43 | .Fa x | |
44 | with its sign changed to | |
45 | .Fa y Ns 's. | |
46 | .Pp | |
47 | The | |
48 | .Fn drem | |
49 | function | |
50 | returns the remainder | |
51 | .Fa r | |
52 | := | |
53 | .Fa x | |
54 | \- | |
55 | .Fa n\(**y | |
56 | where | |
57 | .Fa n | |
58 | is the integer nearest the exact value of | |
59 | .Bk -words | |
60 | .Fa x Ns / Ns Fa y ; | |
61 | .Ek | |
62 | moreover if | |
63 | .Pf \\*(Ba Fa n | |
64 | \- | |
65 | .Sm off | |
66 | .Fa x No / Fa y No \\*(Ba | |
67 | .Sm on | |
68 | = | |
69 | 1/2 | |
70 | then | |
71 | .Fa n | |
72 | is even. Consequently | |
73 | the remainder is computed exactly and | |
74 | .Sm off | |
75 | .Pf \\*(Ba Fa r No \\*(Ba | |
76 | .Sm on | |
77 | \*(Le | |
78 | .Sm off | |
79 | .Pf \\*(Ba Fa y No \\*(Ba/2. | |
80 | .Sm on | |
81 | But | |
82 | .Fn drem x 0 | |
83 | is exceptional. | |
84 | (See below under | |
85 | .Sx DIAGNOSTICS . ) | |
86 | .Pp | |
87 | The | |
88 | .Fn finite | |
89 | function returns the value 1 just when | |
90 | \-\*(If \*(Lt | |
91 | .Fa x | |
92 | \*(Lt +\*(If; | |
93 | otherwise a | |
94 | zero is returned | |
95 | (when | |
96 | .Pf \\*(Ba Ns Fa x Ns \\*(Ba | |
97 | = \*(If or | |
98 | .Fa x | |
99 | is \*(Na or | |
100 | is the | |
101 | .Tn VAX Ns 's | |
102 | reserved operand). | |
103 | .Pp | |
104 | The | |
105 | .Fn logb | |
106 | function returns | |
107 | .Fa x Ns 's exponent | |
108 | .Fa n , | |
cd30a7d2 | 109 | a signed integer converted to double\-precision floating\-point and so |
ae59e04c CL |
110 | chosen that |
111 | 1 (<= | |
112 | .Pf \\*(Ba Ns Fa x Ns \\*(Ba2** Ns Fa n | |
113 | < 2 | |
114 | unless | |
115 | .Fa x | |
116 | = 0 or | |
117 | (only on machines that conform to | |
118 | .Tn IEEE | |
119 | 754) | |
120 | .Pf \\*(Ba Fa x Ns \\*(Ba | |
121 | = \*(If | |
122 | or | |
123 | .Fa x | |
124 | lies between 0 and the Underflow Threshold. | |
125 | (See below under | |
126 | .Sx BUGS . ) | |
127 | .Pp | |
128 | The | |
129 | Fn calb | |
130 | returns | |
131 | .Fa x Ns \(**(2** Ns Fa n ) | |
132 | computed, for integer n, without first computing | |
133 | .Pf 2\(** Fa n . | |
134 | .Sh RETURN VALUES | |
135 | The | |
136 | .Tn IEEE | |
137 | standard | |
138 | 754 defines | |
139 | .Fn drem x 0 | |
140 | and | |
141 | .Fn drem \\*(If y | |
142 | to be invalid operations that produce a \*(Na. | |
143 | On the | |
144 | .Tn VAX , | |
145 | .Fn drem x 0 | |
146 | generates a reserved operand fault. No \*(If | |
147 | exists on a | |
148 | .Tn VAX . | |
149 | .Pp | |
150 | .Tn IEEE | |
151 | 754 defines | |
cd30a7d2 | 152 | .if n \ |
ae59e04c CL |
153 | .Fn logb \(+-\\*(If |
154 | = \*(If and | |
155 | .Fn logb 0 | |
156 | = \-\*(If, and | |
cd30a7d2 | 157 | requires the latter to signal Division\-by\-Zero. |
ae59e04c CL |
158 | But on a |
159 | .Tn VAX , | |
160 | .Fn logb 0 | |
161 | = 1.0 \- 2.0**31 = \-2,147,483,647.0. | |
162 | And if the correct value of | |
163 | .Fn scalb | |
164 | would overflow on a | |
165 | .Tn VAX , | |
166 | it generates a reserved operand fault and sets the global variable | |
167 | .Va errno | |
168 | to | |
169 | .Dv ERANGE . | |
170 | .Sh SEE ALSO | |
171 | .Xr floor 3 , | |
172 | .Xr math 3 , | |
173 | .Xr infnan 3 | |
174 | .Sh AUTHOR | |
cd30a7d2 | 175 | Kwok\-Choi Ng |
ae59e04c CL |
176 | .Sh HISTORY |
177 | The | |
178 | .Nm ieee | |
179 | functions appeared in | |
180 | .Bx 4.3 . | |
181 | .Sh BUGS | |
182 | Should | |
183 | .Fn drem x 0 | |
184 | and | |
185 | .Fn logb 0 | |
186 | on a | |
187 | .Tn VAX | |
188 | signal invalidity | |
189 | by setting | |
190 | .Va errno No = Dv EDOM ? | |
191 | Should | |
192 | .Fn logb 0 | |
193 | return \-1.7e38? | |
194 | .Pp | |
195 | .Tn IEEE | |
196 | 754 currently specifies that | |
197 | .Fn logb "denormalized no." | |
198 | = | |
199 | .Fn logb "tiniest normalized no. > 0" | |
cd30a7d2 | 200 | but the consensus has changed to the specification in the new |
ae59e04c CL |
201 | proposed |
202 | .Tn IEEE | |
203 | standard p854, namely that | |
204 | .Fn logb x | |
205 | satisfy | |
206 | .Bd -filled -offset indent | |
207 | 1 \(<= | |
208 | .Fn scalb \\*(Bax\\*(Ba \-logb(x) | |
209 | < | |
210 | Radix\0 ... = 2 | |
211 | for | |
212 | .Tn IEEE | |
213 | 754 | |
214 | .Ed | |
215 | .Pp | |
cd30a7d2 | 216 | for every x except 0, |
ae59e04c CL |
217 | \*(If |
218 | and \*(Na. | |
cd30a7d2 | 219 | Almost every program that assumes 754's specification will work |
ae59e04c CL |
220 | correctly if |
221 | .Fn logb | |
222 | follows 854's specification instead. | |
223 | .Pp | |
224 | .Tn IEEE | |
225 | 754 requires | |
226 | .Fn copysign x \\*(Na) | |
227 | = | |
228 | .Pf \(+- Ns Fa x | |
229 | but says nothing | |
230 | else about the sign of a \*(Na. A \*(Na | |
231 | .Em N Ns ot | |
232 | .Em a | |
233 | .Em N Ns umber ) | |
234 | is | |
235 | similar in spirit to the | |
236 | .Tn VAX Ns 's | |
237 | reserved operand, but very | |
cd30a7d2 MAN |
238 | different in important details. Since the sign bit of a |
239 | reserved operand makes it look negative, | |
ae59e04c CL |
240 | .Bd -filled -offset indent |
241 | .Fn copysign x "reserved operand" | |
242 | = | |
243 | .Pf \- Fa x ; | |
244 | .Ed | |
245 | .Pp | |
cd30a7d2 | 246 | should this return the reserved operand instead? |