(_hurd_sig_post): __sig_post renamed to __msg_sig_post.
[kopensolaris-gnu/glibc.git] / manual / arith.texi
1 @node Arithmetic, Date and Time, Mathematics, Top
2 @chapter Low-Level Arithmetic Functions
3
4 This chapter contains information about functions for doing basic
5 arithmetic operations, such as splitting a float into its integer and
6 fractional parts.  These functions are declared in the header file
7 @file{math.h}.
8
9 @menu
10 * Not a Number::                Making NaNs and testing for NaNs.
11 * Predicates on Floats::        Testing for infinity and for NaNs.
12 * Absolute Value::              Absolute value functions.
13 * Normalization Functions::     Hacks for radix-2 representations.
14 * Rounding and Remainders::     Determinining the integer and
15                                  fractional parts of a float.
16 * Integer Division::            Functions for performing integer
17                                  division.
18 * Parsing of Numbers::          Functions for ``reading'' numbers
19                                  from strings.
20 @end menu
21
22 @node Not a Number
23 @section ``Not a Number'' Values
24 @cindex NaN
25 @cindex not a number
26 @cindex IEEE floating point
27
28 The IEEE floating point format used by most modern computers supports
29 values that are ``not a number''.  These values are called @dfn{NaNs}.
30 ``Not a number'' values result from certain operations which have no
31 meaningful numeric result, such as zero divided by zero or infinity
32 divided by infinity.
33
34 One noteworthy property of NaNs is that they are not equal to
35 themselves.  Thus, @code{x == x} can be 0 if the value of @code{x} is a
36 NaN.  You can use this to test whether a value is a NaN or not: if it is
37 not equal to itself, then it is a NaN.  But the recommended way to test
38 for a NaN is with the @code{isnan} function (@pxref{Predicates on Floats}).
39
40 Almost any arithmetic operation in which one argument is a NaN returns
41 a NaN.
42
43 @comment math.h
44 @comment GNU
45 @deftypevr Macro double NAN
46 An expression representing a value which is ``not a number''.  This
47 macro is a GNU extension, available only on machines that support ``not
48 a number'' values---that is to say, on all machines that support IEEE
49 floating point.
50
51 You can use @samp{#ifdef NAN} to test whether the machine supports
52 NaNs.  (Of course, you must arrange for GNU extensions to be visible,
53 such as by defining @code{_GNU_SOURCE}, and then you must include
54 @file{math.h}.)
55 @end deftypevr
56
57 @node Predicates on Floats
58 @section Predicates on Floats
59
60 @pindex math.h
61 This section describes some miscellaneous test functions on doubles.
62 Prototypes for these functions appear in @file{math.h}.  These are BSD
63 functions, and thus are available if you define @code{_BSD_SOURCE} or
64 @code{_GNU_SOURCE}.
65
66 @comment math.h
67 @comment BSD
68 @deftypefun int isinf (double @var{x})
69 This function returns @code{-1} if @var{x} represents negative infinity,
70 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
71 @end deftypefun
72
73 @comment math.h
74 @comment BSD
75 @deftypefun int isnan (double @var{x})
76 This function returns a nonzero value if @var{x} is a ``not a number''
77 value, and zero otherwise.  (You can just as well use @code{@var{x} !=
78 @var{x}} to get the same result).
79 @end deftypefun
80
81 @comment math.h
82 @comment BSD
83 @deftypefun int finite (double @var{x})
84 This function returns a nonzero value if @var{x} is finite or a ``not a
85 number'' value, and zero otherwise.
86 @end deftypefun
87
88 @comment math.h
89 @comment BSD
90 @deftypefun double infnan (int @var{error})
91 This function is provided for compatibility with BSD.  The other
92 mathematical functions use @code{infnan} to decide what to return on
93 occasion of an error.  Its argument is an error code, @code{EDOM} or
94 @code{ERANGE}; @code{infnan} returns a suitable value to indicate this
95 with.  @code{-ERANGE} is also acceptable as an argument, and corresponds
96 to @code{-HUGE_VAL} as a value.
97
98 In the BSD library, on certain machines, @code{infnan} raises a fatal
99 signal in all cases.  The GNU library does not do likewise, because that
100 does not fit the ANSI C specification.
101 @end deftypefun
102
103 @strong{Portability Note:} The functions listed in this section are BSD
104 extensions.
105
106 @node Absolute Value
107 @section Absolute Value
108 @cindex absolute value functions
109
110 These functions are provided for obtaining the @dfn{absolute value} (or
111 @dfn{magnitude}) of a number.  The absolute value of a real number
112 @var{x} is @var{x} is @var{x} is positive, @minus{}@var{x} if @var{x} is
113 negative.  For a complex number @var{z}, whose real part is @var{x} and
114 whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
115 (@var{x}*@var{x} + @var{y}*@var{y})}}.
116
117 @pindex math.h
118 @pindex stdlib.h
119 Prototypes for @code{abs} and @code{labs} are in @file{stdlib.h};
120 @code{fabs} and @code{cabs} are declared in @file{math.h}.
121
122 @comment stdlib.h
123 @comment ANSI
124 @deftypefun int abs (int @var{number})
125 This function returns the absolute value of @var{number}.
126
127 Most computers use a two's complement integer representation, in which
128 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
129 cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined.
130 @end deftypefun
131
132 @comment stdlib.h
133 @comment ANSI
134 @deftypefun {long int} labs (long int @var{number})
135 This is similar to @code{abs}, except that both the argument and result
136 are of type @code{long int} rather than @code{int}.
137 @end deftypefun
138
139 @comment math.h
140 @comment ANSI
141 @deftypefun double fabs (double @var{number})
142 This function returns the absolute value of the floating-point number
143 @var{number}.
144 @end deftypefun
145
146 @comment math.h
147 @comment BSD
148 @deftypefun double cabs (struct @{ double real, imag; @} @var{z})
149 The @code{cabs} function returns the absolute value of the complex
150 number @var{z}, whose real part is @code{@var{z}.real} and whose
151 imaginary part is @code{@var{z}.imag}.  (See also the function
152 @code{hypot} in @ref{Exponents and Logarithms}.)  The value is:
153
154 @smallexample
155 sqrt (@var{z}.real*@var{z}.real + @var{z}.imag*@var{z}.imag)
156 @end smallexample
157 @end deftypefun
158
159 @node Normalization Functions
160 @section Normalization Functions
161 @cindex normalization functions (floating-point)
162
163 The functions described in this section are primarily provided as a way
164 to efficiently perform certain low-level manipulations on floating point
165 numbers that are represented internally using a binary radix;
166 see @ref{Floating Point Concepts}.  These functions are required to
167 have equivalent behavior even if the representation does not use a radix
168 of 2, but of course they are unlikely to be particularly efficient in
169 those cases.
170
171 @pindex math.h
172 All these functions are declared in @file{math.h}.
173
174 @comment math.h
175 @comment ANSI
176 @deftypefun double frexp (double @var{value}, int *@var{exponent})
177 The @code{frexp} function is used to split the number @var{value}
178 into a normalized fraction and an exponent.
179
180 If the argument @var{value} is not zero, the return value is @var{value}
181 times a power of two, and is always in the range 1/2 (inclusive) to 1
182 (exclusive).  The corresponding exponent is stored in
183 @code{*@var{exponent}}; the return value multiplied by 2 raised to this
184 exponent equals the original number @var{value}.
185
186 For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
187 stores @code{4} in @code{exponent}.
188
189 If @var{value} is zero, then the return value is zero and
190 zero is stored in @code{*@var{exponent}}.
191 @end deftypefun
192
193 @comment math.h
194 @comment ANSI
195 @deftypefun double ldexp (double @var{value}, int @var{exponent})
196 This function returns the result of multiplying the floating-point
197 number @var{value} by 2 raised to the power @var{exponent}.  (It can
198 be used to reassemble floating-point numbers that were taken apart
199 by @code{frexp}.)
200
201 For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
202 @end deftypefun
203
204 The following functions which come from BSD provide facilities
205 equivalent to those of @code{ldexp} and @code{frexp}:
206
207 @comment math.h
208 @comment BSD
209 @deftypefun double scalb (double @var{value}, int @var{exponent})
210 The @code{scalb} function is the BSD name for @code{ldexp}.
211 @end deftypefun
212
213 @comment math.h
214 @comment BSD
215 @deftypefun double logb (double @var{x})
216 This BSD function returns the integer part of the base-2 logarithm of
217 @var{x}, an integer value represented in type @code{double}.  This is
218 the highest integer power of @code{2} contained in @var{x}.  The sign of
219 @var{x} is ignored.  For example, @code{logb (3.5)} is @code{1.0} and
220 @code{logb (4.0)} is @code{2.0}.
221
222 When @code{2} raised to this power is divided into @var{x}, it gives a
223 quotient between @code{1} (inclusive) and @code{2} (exclusive).
224
225 If @var{x} is zero, the value is minus infinity (if the machine supports
226 such a value), or else a very small number.  If @var{x} is infinity, the
227 value is infinity.
228
229 The value returned by @code{logb} is one less than the value that
230 @code{frexp} would store into @code{*@var{exponent}}.
231 @end deftypefun
232
233 @comment math.h
234 @comment BSD
235 @deftypefun double copysign (double @var{value}, double @var{sign})
236 The @code{copysign} function returns a value whose absolute value is the
237 same as that of @var{value}, and whose sign matches that of @var{sign}.
238 This is a BSD function.
239 @end deftypefun
240
241 @node Rounding and Remainders
242 @section Rounding and Remainder Functions
243 @cindex rounding functions
244 @cindex remainder functions
245 @cindex converting floats to integers
246
247 @pindex math.h
248 The functions listed here perform operations such as rounding,
249 truncation, and remainder in division of floating point numbers.  Some
250 of these functions convert floating point numbers to integer values.
251 They are all declared in @file{math.h}.
252
253 You can also convert floating-point numbers to integers simply by
254 casting them to @code{int}.  This discards the fractional part,
255 effectively rounding towards zero.  However, this only works if the
256 result can actually be represented as an @code{int}---for very large
257 numbers, this is impossible.  The functions listed here return the
258 result as a @code{double} instead to get around this problem.
259
260 @comment math.h
261 @comment ANSI
262 @deftypefun double ceil (double @var{x})
263 The @code{ceil} function rounds @var{x} upwards to the nearest integer,
264 returning that value as a @code{double}.  Thus, @code{ceil (1.5)}
265 is @code{2.0}.
266 @end deftypefun
267
268 @comment math.h
269 @comment ANSI
270 @deftypefun double floor (double @var{x})
271 The @code{ceil} function rounds @var{x} downwards to the nearest
272 integer, returning that value as a @code{double}.  Thus, @code{floor
273 (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
274 @end deftypefun
275
276 @comment math.h
277 @comment BSD
278 @deftypefun double rint (double @var{x})
279 This function rounds @var{x} to an integer value according to the
280 current rounding mode.  @xref{Floating Point Parameters}, for
281 information about the various rounding modes.  The default
282 rounding mode is to round to the nearest integer; some machines
283 support other modes, but round-to-nearest is always used unless
284 you explicit select another.
285 @end deftypefun
286
287 @comment math.h
288 @comment ANSI
289 @deftypefun double modf (double @var{value}, double *@var{integer-part})
290 This function breaks the argument @var{value} into an integer part and a
291 fractional part (between @code{-1} and @code{1}, exclusive).  Their sum
292 equals @var{value}.  Each of the parts has the same sign as @var{value},
293 so the rounding of the integer part is towards zero.
294
295 @code{modf} stores the integer part in @code{*@var{integer-part}}, and
296 returns the fractional part.  For example, @code{modf (2.5, &intpart)}
297 returns @code{0.5} and stores @code{2.0} into @code{intpart}.
298 @end deftypefun
299
300 @comment math.h
301 @comment ANSI
302 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
303 This function computes the remainder from the division of
304 @var{numerator} by @var{denominator}.  Specifically, the return value is
305 @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
306 is the quotient of @var{numerator} divided by @var{denominator}, rounded
307 towards zero to an integer.  Thus, @w{@code{fmod (6.5, 2.3)}} returns
308 @code{1.9}, which is @code{6.5} minus @code{4.6}.
309
310 The result has the same sign as the @var{numerator} and has magnitude
311 less than the magnitude of the @var{denominator}.
312
313 If @var{denominator} is zero, @code{fmod} fails and sets @code{errno} to
314 @code{EDOM}.
315 @end deftypefun
316
317 @comment math.h
318 @comment BSD
319 @deftypefun double drem (double @var{numerator}, double @var{denominator})
320 The function @code{drem} is like @code{fmod} except that it rounds the
321 internal quotient @var{n} to the nearest integer instead of towards zero
322 to an integer.  For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
323 which is @code{6.5} minus @code{6.9}.
324
325 The absolute value of the result is less than or equal to half the
326 absolute value of the @var{denominator}.  The difference between
327 @code{fmod (@var{numerator}, @var{denominator})} and @code{drem
328 (@var{numerator}, @var{denominator})} is always either
329 @var{denominator}, minus @var{denominator}, or zero.
330
331 If @var{denominator} is zero, @code{drem} fails and sets @code{errno} to
332 @code{EDOM}.
333 @end deftypefun
334
335
336 @node Integer Division
337 @section Integer Division
338 @cindex integer division functions
339
340 This section describes functions for performing integer division.  These
341 functions are redundant in the GNU C library, since in GNU C the @samp{/}
342 operator always rounds towards zero.  But in other C implementations,
343 @samp{/} may round differently with negative arguments.  @code{div} and
344 @code{ldiv} are useful because they specify how to round the quotient:
345 towards zero.  The remainder has the same sign as the numerator.
346
347 These functions are specified to return a result @var{r} such that the value
348 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
349 @var{numerator}.
350
351 @pindex stdlib.h
352 To use these facilities, you should include the header file
353 @file{stdlib.h} in your program.
354
355 @comment stdlib.h
356 @comment ANSI
357 @deftp {Data Type} div_t
358 This is a structure type used to hold the result returned by the @code{div}
359 function.  It has the following members:
360
361 @table @code
362 @item int quot
363 The quotient from the division.
364
365 @item int rem
366 The remainder from the division.
367 @end table
368 @end deftp
369
370 @comment stdlib.h
371 @comment ANSI
372 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
373 This function @code{div} computes the quotient and remainder from
374 the division of @var{numerator} by @var{denominator}, returning the
375 result in a structure of type @code{div_t}.
376
377 If the result cannot be represented (as in a division by zero), the
378 behavior is undefined.
379
380 Here is an example, albeit not a very useful one.
381
382 @smallexample
383 div_t result;
384 result = div (20, -6);
385 @end smallexample
386
387 @noindent
388 Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
389 @end deftypefun
390
391 @comment stdlib.h
392 @comment ANSI
393 @deftp {Data Type} ldiv_t
394 This is a structure type used to hold the result returned by the @code{ldiv}
395 function.  It has the following members:
396
397 @table @code
398 @item long int quot
399 The quotient from the division.
400
401 @item long int rem
402 The remainder from the division.
403 @end table
404
405 (This is identical to @code{div_t} except that the components are of
406 type @code{long int} rather than @code{int}.)
407 @end deftp
408
409 @comment stdlib.h
410 @comment ANSI
411 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
412 The @code{ldiv} function is similar to @code{div}, except that the
413 arguments are of type @code{long int} and the result is returned as a
414 structure of type @code{ldiv}.
415 @end deftypefun
416
417
418 @node Parsing of Numbers
419 @section Parsing of Numbers
420 @cindex parsing numbers (in formatted input)
421 @cindex converting strings to numbers
422 @cindex number syntax, parsing
423 @cindex syntax, for reading numbers
424
425 This section describes functions for ``reading'' integer and
426 floating-point numbers from a string.  It may be more convenient in some
427 cases to use @code{sscanf} or one of the related functions; see
428 @ref{Formatted Input}.  But often you can make a program more robust by
429 finding the tokens in the string by hand, then converting the numbers
430 one by one.
431
432 @menu
433 * Parsing of Integers::         Functions for conversion of integer values.
434 * Parsing of Floats::           Functions for conversion of floating-point
435                                  values.
436 @end menu
437
438 @node Parsing of Integers
439 @subsection Parsing of Integers
440
441 @pindex stdlib.h
442 These functions are declared in @file{stdlib.h}.
443
444 @comment stdlib.h
445 @comment ANSI
446 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
447 The @code{strtol} (``string-to-long'') function converts the initial
448 part of @var{string} to a signed integer, which is returned as a value
449 of type @code{long int}.  
450
451 This function attempts to decompose @var{string} as follows:
452
453 @itemize @bullet
454 @item 
455 A (possibly empty) sequence of whitespace characters.  Which characters
456 are whitespace is determined by the @code{isspace} function
457 (@pxref{Classification of Characters}).  These are discarded.
458
459 @item 
460 An optional plus or minus sign (@samp{+} or @samp{-}).
461
462 @item 
463 A nonempty sequence of digits in the radix specified by @var{base}.
464
465 If @var{base} is zero, decimal radix is assumed unless the series of
466 digits begins with @samp{0} (specifying octal radix), or @samp{0x} or
467 @samp{0X} (specifying hexadecimal radix); in other words, the same
468 syntax used for integer constants in C.
469
470 Otherwise @var{base} must have a value between @code{2} and @code{35}.
471 If @var{base} is @code{16}, the digits may optionally be preceded by
472 @samp{0x} or @samp{0X}.
473
474 @item 
475 Any remaining characters in the string.  If @var{tailptr} is not a null
476 pointer, @code{strtol} stores a pointer to this tail in
477 @code{*@var{tailptr}}.
478 @end itemize
479
480 If the string is empty, contains only whitespace, or does not contain an
481 initial substring that has the expected syntax for an integer in the
482 specified @var{base}, no conversion is performed.  In this case,
483 @code{strtol} returns a value of zero and the value stored in
484 @code{*@var{tailptr}} is the value of @var{string}.
485
486 In a locale other than the standard @code{"C"} locale, this function
487 may recognize additional implementation-dependent syntax.
488
489 If the string has valid syntax for an integer but the value is not
490 representable because of overflow, @code{strtol} returns either
491 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as
492 appropriate for the sign of the value.  It also sets @code{errno}
493 to @code{ERANGE} to indicate there was overflow.
494
495 There is an example at the end of this section.
496 @end deftypefun
497
498 @comment stdlib.h
499 @comment ANSI
500 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
501 The @code{strtoul} (``string-to-unsigned-long'') function is like
502 @code{strtol} except that it returns its value with type @code{unsigned
503 long int}.  The value returned in case of overflow is @code{ULONG_MAX}
504 (@pxref{Range of Type}).
505 @end deftypefun
506
507 @comment stdlib.h
508 @comment ANSI
509 @deftypefun {long int} atol (const char *@var{string})
510 This function is similar to the @code{strtol} function with a @var{base}
511 argument of @code{10}, except that it need not detect overflow errors.
512 The @code{atol} function is provided mostly for compatibility with
513 existing code; using @code{strtol} is more robust.
514 @end deftypefun
515
516 @comment stdlib.h
517 @comment ANSI
518 @deftypefun int atoi (const char *@var{string})
519 This function is like @code{atol}, except that it returns an @code{int}
520 value rather than @code{long int}.  The @code{atoi} function is also
521 considered obsolete; use @code{strtol} instead.
522 @end deftypefun
523
524 Here is a function which parses a string as a sequence of integers and
525 returns the sum of them:
526
527 @smallexample
528 int
529 sum_ints_from_string (char *string)
530 @{
531   int sum = 0;
532
533   while (1) @{
534     char *tail;
535     int next;
536
537     /* @r{Skip whitespace by hand, to detect the end.}  */
538     while (isspace (*string)) string++;
539     if (*string == 0)
540       break;
541
542     /* @r{There is more nonwhitespace,}  */
543     /* @r{so it ought to be another number.}  */
544     errno = 0;
545     /* @r{Parse it.}  */
546     next = strtol (string, &tail, 0);
547     /* @r{Add it in, if not overflow.}  */
548     if (errno)
549       printf ("Overflow\n");
550     else
551       sum += next;
552     /* @r{Advance past it.}  */
553     string = tail;
554   @}
555
556   return sum;
557 @}
558 @end smallexample
559
560 @node Parsing of Floats
561 @subsection Parsing of Floats
562
563 @pindex stdlib.h
564 These functions are declared in @file{stdlib.h}.
565
566 @comment stdlib.h
567 @comment ANSI
568 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
569 The @code{strtod} (``string-to-double'') function converts the initial
570 part of @var{string} to a floating-point number, which is returned as a
571 value of type @code{double}.  
572
573 This function attempts to decompose @var{string} as follows:
574
575 @itemize @bullet
576 @item 
577 A (possibly empty) sequence of whitespace characters.  Which characters
578 are whitespace is determined by the @code{isspace} function
579 (@pxref{Classification of Characters}).  These are discarded.
580
581 @item
582 An optional plus or minus sign (@samp{+} or @samp{-}).
583
584 @item
585 A nonempty sequence of digits optionally containing a decimal-point
586 character---normally @samp{.}, but it depends on the locale
587 (@pxref{Numeric Formatting}).
588
589 @item
590 An optional exponent part, consisting of a character @samp{e} or
591 @samp{E}, an optional sign, and a sequence of digits.
592
593 @item
594 Any remaining characters in the string.  If @var{tailptr} is not a null
595 pointer, a pointer to this tail of the string is stored in
596 @code{*@var{tailptr}}.
597 @end itemize
598
599 If the string is empty, contains only whitespace, or does not contain an
600 initial substring that has the expected syntax for a floating-point
601 number, no conversion is performed.  In this case, @code{strtod} returns
602 a value of zero and the value returned in @code{*@var{tailptr}} is the
603 value of @var{string}.
604
605 In a locale other than the standard @code{"C"} locale, this function may
606 recognize additional locale-dependent syntax.
607
608 If the string has valid syntax for a floating-point number but the value
609 is not representable because of overflow, @code{strtod} returns either
610 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
611 the sign of the value.  Similarly, if the value is not representable
612 because of underflow, @code{strtod} returns zero.  It also sets @code{errno}
613 to @code{ERANGE} if there was overflow or underflow.
614 @end deftypefun
615
616 @comment stdlib.h
617 @comment ANSI
618 @deftypefun double atof (const char *@var{string})
619 This function is similar to the @code{strtod} function, except that it
620 need not detect overflow and underflow errors.  The @code{atof} function
621 is provided mostly for compatibility with existing code; using
622 @code{strtod} is more robust.
623 @end deftypefun